Customize repro & fix suggestions

Built-in tasks (build, test, lint, format, gazelle, delivery) emit two kinds of follow-up suggestions when something noteworthy happens:

Repro commands: “how do I reproduce this failure?” Rendered with a 🔁 Reproduce: header.
Fix commands: “how do I apply the suggested fix?” Rendered with a 🛠️ Fix: header.

The same suggestions appear everywhere a task’s outcome is rendered: the CLI terminal output, Buildkite annotations, GitHub Status Check bodies, and the aggregate PR task summary comment. Phases.repro_fix_suggestion lets your .aspect/config.axl accept, reject, or rewrite each suggestion before any surface renders it. Common uses:

Rewrite suggested aspect … commands to your team’s preferred form, for example bazel … via the tools/bazel wrapper, or your repo’s own custom developer CLI (e.g. mycorp build … instead of aspect build …) when you’ve wrapped Bazel/Aspect behind a company-branded entry point.
Drop the vanilla bazel alternate suggestion for one task but not another.
Add a description to a suggestion that ships without one, so the rendered line carries a # <label> above the command explaining what it does.

To drop a whole flavor without a hook, pass --repro-flavor or --fix-flavor (repeatable, aspect and/or bazel, default both). build, test, lint, format, and gazelle take --repro-flavor; lint, format, and gazelle also take --fix-flavor. Set them from config the same way as any task arg:

.aspect/config.axl

def config(ctx: ConfigContext):
    ctx.tasks["test"].args.repro_flavors = ["aspect"]

Use a hook when the decision depends on more than the flavor.

Hook signature

.aspect/config.axl

load(
    "@aspect//traits.axl",
    "REPRO_FIX_ACCEPT",
    "REPRO_FIX_REJECT",
    "ReproFixInfo",
    "ReproFixSuggestion",
    "Phases",
    "repro_fix_replace",
)

def _my_hook(ctx: TaskContext, info: ReproFixInfo) -> ReproFixSuggestion:
    # ...inspect info, return a verdict...
    return REPRO_FIX_ACCEPT

def config(ctx: ConfigContext):
    lifecycle = ctx.traits[Phases]
    lifecycle.repro_fix_suggestion.append(_my_hook)

Hooks are invoked in registration order on every repro/fix entry, on every surface emit. Each entry runs through the chain at most once, so it’s safe to register hooks that intermix with other features that also touch repro/fix data.

Verdicts

Return one of these from your hook:

Verdict	Effect
`REPRO_FIX_ACCEPT`	Keep the suggestion unchanged. Chain continues to the next hook.
`REPRO_FIX_REJECT`	Drop the suggestion entirely. Short-circuits the chain: no further hook sees it.
`repro_fix_replace(command=, description=)`	Rewrite the command and/or description. Omit either field to keep the prior value. Chain continues with the rewritten entry.

A replace with both command and description left as None is a no-op (equivalent to accept).

`ReproFixInfo` fields

The single info argument carries everything a hook typically needs to decide:

Field	Type	Notes
`task_path`	`str`	Joined `<group...> <kind>` CLI path, e.g. `"lint"`, `"dev test-repro-commands"`.
`task_kind`	`str`	The task kind: the command being run (e.g. `"lint"`, `"buildifier"`).
`task_group`	`list[str]`	The group prefix (e.g. `[]`, `["dev"]`).
`kind`	`str`	Task-result kind: `"lint_results"`, `"bazel_results"`, `"format_results"`, `"gazelle_results"`, `"delivery_results"`. Matches `TaskUpdate.kind` so hooks can route by the same key the surface templates use.
`command_kind`	`ReproFixCommandKind`	`"repro"` for entries from `🔁 Reproduce`, `"fix"` for entries from `🛠️ Fix`.
`command`	`str`	The suggestion’s shell-ready command string.
`description`	`str`	Optional short label rendered as a `# <description>` comment above the command. Empty when the task emits a single suggestion of its kind.
`slug`	`str`	Stable kebab-case identifier, the recommended scoping key. See suggestion slug catalog below.
`status`	`str`	Lifecycle status the task is about to emit: `"running"`, `"failing"`, `"passed"`, `"warning"`, `"failed"`, `"aborted"`.
`exit_code`	`int`	Task exit code. Only meaningful on the terminal emit; `0` mid-task.
`bazel_subcommand`	`str`	`"build"`, `"test"`, or `"run"` for Bazel-wrapping tasks; `""` otherwise.
`targets`	`list[str]`	Resolved target patterns the task ran on.
`failed_targets`	`list[str]`	Deduplicated list of Bazel labels that failed. Empty on non-Bazel tasks.
`extras`	`dict`	Open-ended, task-stamped, curated keys. Documented per-task. Examples: `lint` stamps `{"aspects": [...], "suggestion_count": N}`; `format` and `gazelle` stamp `{"affected_files": [...]}`; `delivery` stamps `{"mode": str, "targets_total": N}`.
`data`	`dict`	Escape hatch: the full task `data` dict for hooks that need fields not surfaced by the typed fields or `extras`. Treat as unstable; prefer the typed surfaces above.

Suggestion slug catalog

Every suggestion carries a stable kebab-case slug so hooks scope by suggestion identity instead of parsing the command string. The full catalog:

Task	Slugs
`lint`	`lint-repro`, `lint-fix`
`format`	`format-repro`, `format-fix`, `format-fix-truncated`, `format-fix-rediscover`, `format-fix-vanilla-bazel`
`gazelle`	`gazelle-repro`, `gazelle-fix`, `gazelle-fix-truncated`, `gazelle-fix-rediscover`, `gazelle-fix-vanilla-bazel`
`delivery`	`delivery-repro-local-preview`
`build` / `test`	`build-repro-aspect`, `build-repro-vanilla-bazel`, `test-repro-aspect`, `test-repro-vanilla-bazel`

Convention: every vanilla-bazel alternate suggestion ends in -vanilla-bazel, so a single hook can suffix-match to scope across all producers without listing each slug.

Examples

Some of these examples come from the aspect-build/aspect-cli repo’s own .aspect/config.axl.

Rewrite `aspect …` to `bazel …` for one task

Useful when your repo has a tools/bazel wrapper and you want suggestions to use the bazel form so new contributors copy-paste a command that goes through the checked-in Bazel version.

.aspect/config.axl

def _buildifier_repro_fix(ctx: TaskContext, info: ReproFixInfo) -> ReproFixSuggestion:
    """Rewrite buildifier `aspect ...` suggestions to `bazel ...`."""
    if info.task_kind != "buildifier":
        return REPRO_FIX_ACCEPT
    return repro_fix_replace(
        command = info.command.replace("aspect buildifier", "bazel buildifier", 1),
    )

def config(ctx: ConfigContext):
    lifecycle = ctx.traits[Phases]
    lifecycle.repro_fix_suggestion.append(_buildifier_repro_fix)

Drop the vanilla-bazel alternate everywhere except one task

Built-in tasks tack on a vanilla bazel run <target> suggestion next to their aspect … repros/fixes, a fallback for environments where the Aspect CLI isn’t on PATH. If your team always has aspect (or a tools/bazel wrapper that routes through it), those alternates are noise.

.aspect/config.axl

def _drop_vanilla_bazel_except_build(ctx: TaskContext, info: ReproFixInfo) -> ReproFixSuggestion:
    """Drop every vanilla-bazel alternate except `build`'s."""
    if not info.slug.endswith("-vanilla-bazel") or info.task_kind == "build":
        return REPRO_FIX_ACCEPT
    return REPRO_FIX_REJECT

def config(ctx: ConfigContext):
    lifecycle = ctx.traits[Phases]
    lifecycle.repro_fix_suggestion.append(_drop_vanilla_bazel_except_build)

The endswith("-vanilla-bazel") suffix match catches every producer, including any added later.

Rewrite a description without touching the command

repro_fix_replace takes either field independently. Passing only description keeps the existing command unchanged.

.aspect/config.axl

def _shorten_delivery_local_preview(ctx: TaskContext, info: ReproFixInfo) -> ReproFixSuggestion:
    """Shorten the delivery local-preview description for consistency across runs."""
    if info.slug != "delivery-repro-local-preview":
        return REPRO_FIX_ACCEPT
    return repro_fix_replace(
        description = "--mode=always --track-state=false for off-runner with no state backend.",
    )

def config(ctx: ConfigContext):
    lifecycle = ctx.traits[Phases]
    lifecycle.repro_fix_suggestion.append(_shorten_delivery_local_preview)

Order matters

Hooks run in registration order, and each replace verdict feeds the next hook in the chain. So if you register a rewrite hook and a reject hook, register the rewrite first. Otherwise the reject may match the original entry and short-circuit before the rewrite runs. The slug is preserved across replace verdicts (hooks rewrite commands and descriptions, not suggestion identity), so slug-scoped hooks downstream of a replace still match correctly. But the rewritten command / description is what downstream hooks see.

​Hook signature

​Verdicts

​ReproFixInfo fields

​Suggestion slug catalog

​Examples

​Rewrite aspect … to bazel … for one task

​Drop the vanilla-bazel alternate everywhere except one task

​Rewrite a description without touching the command

​Order matters

​See also

Hook signature

Verdicts

`ReproFixInfo` fields

Suggestion slug catalog

Examples

Rewrite `aspect …` to `bazel …` for one task

Drop the vanilla-bazel alternate everywhere except one task

Rewrite a description without touching the command

Order matters

See also