Fix

Failure-driven iterative repair. Detect → Prioritize → Fix ONE thing → Commit → Verify → Keep/Revert → Repeat.

When to Apply / NOT

Apply: user says "fix", "make it pass", "apply findings"; input is a verifier failure, findings file, or bug description.

NOT apply:

• CI/PR workflows with no local context → use gh-fix-ci
• PR review comments → use gh-address-comments
• Merge conflicts
• Analysis-only tasks → use resolve or debug
• Planned change without a failure driver → use proceed

Detected Mode Acknowledgement [LOAD-BEARING]

First output line before ANY edit:

detected: <mode> — target=TARGET guard=GUARD scope=SCOPE cap=20

Mode values: gh-route, findings, verifier-failure, bug-spec. Full classifier: references/classifier.md.

Input Classifier

First-match wins. Full detail: references/classifier.md.

Auto-Detect Gate

Auto-infer: target verifier, scope glob, guard command, iteration cap (default 20).

Trigger AskUserQuestion (single-select per axis, NEVER multiSelect) when:

• MIXED_MODE: findings artifact AND verifier-failure output both present
• GH_PARTIAL: GH-flavored input but no open PR, or gh auth status fails
• LANG_UNKNOWN: verifier-failure detected but verifier undetectable
• SCOPE_AMBIGUOUS: bug-spec with no module, file, or component reference

Iterative Loop

Full spec: references/loop.md. Key rules:

• One fix per iteration. Apply fix → stage checkpoint commit → run verifiers → KEEP on green, revert with git revert HEAD --no-edit on red. A commit is kept only when the guard passes.
• Decide matrix:
  • delta > 0 + guard ok → KEEP
  • delta > 0 + guard fail → REWORK (max 2 reworks per item; 4th attempt → SKIP)
  • delta ≤ 0 → DISCARD — revert immediately
  • 3 total skips → HALT with summary
• Revert: always git revert HEAD --no-edit. Never reset --hard.
• Cap: 20 iterations default. Print progress every 5 iterations.
• Refuse loop on protected branches (main, master, release/*).
• Override: iterations: N or --iterations N in invocation.

Verifier Detection

Repo-native first (use fd --max-depth 2 to locate):

1. Justfile → just test (guard: just check)
2. Makefile → make test (guard: make check)
3. package.json → npm test (guard: tsc --noEmit && eslint .)
4. dune-project → dune build @runtest (guard: dune build)

Language fallbacks:

• Python: pytest + ruff check . && mypy .
• TypeScript: vitest run + tsc --noEmit && eslint .
• Rust: cargo test + cargo clippy -- -D warnings
• Go: go test ./... + golangci-lint run
• OCaml: dune build @runtest + dune build

Full matrix: references/verifiers.md.

GH Auto-Route

When open PR + gh auth status clean + GH-flavored input:

Both sets of language → fire AMBIGUOUS_GH_ROUTE (single-select: gh-fix-ci vs gh-address-comments). Partial match → GH_PARTIAL ambiguity flag.

Hand-off & Integration

• debug upstream: unclear root cause — debug findings become the fix target.
• triage-issue upstream: bug-spec mode — triage produces repro + TDD plan first.
• test-driven partner: failing test ↔ green flip; delegate RED→GREEN cycle.
• proceed complement: planned change without failure → proceed; failure-driven → fix.
• resolve / review / triage-issue as findings sources: their output paths feed findings mode.

Failure Modes

• No verifier output: emit warning, raise LANG_UNKNOWN.
• 3 strikes on one item: SKIP, add to blocked.md, recommend debug.
• 3 total skips: HALT with session summary.
• Guard ambiguous: AskUserQuestion for guard command.
• Mixed-mode input: raise MIXED_MODE.
• Protected branch: REFUSE with message before entering loop.

Anti-Patterns

• Never @ts-ignore / # type: ignore / // eslint-disable to silence errors.
• Never delete tests to make them pass.
• ONE fix per iteration — no "while I'm here" changes.
• No git reset --hard.
• Recursion guard: --mode <X> bypasses classifier entirely; gh-fix-ci re-entering as fix --mode verifier-failure cannot loop back into gh-fix-ci.

Constitutional Rules

• Evidence before claims: run verifiers, read output, then state result.
• Compress-first: reduce coupling before behavior change.
• Atomic commits: one concern per commit; guard must pass before a loop commit is kept (KEEP in decide matrix = tests-pass gate).
• Never skip the guard.
• Full specs: references/loop.md, references/classifier.md, references/verifiers.md.