git:20261012.e7232f7 to git:20261012.d370df0

---

name: fix-runner

description: "Dispatch-only corrector: it runs when the evaluator skill dispatches it on FAIL, or qa-preflight after a feature is done — never from a person's request. When someone asks to fix what an evaluation reported, use evaluator instead; it owns the correction loop and hands this skill the report. Reads the structured evaluation-report.json (both producers write the same schema), applies the minimal fix for the reported problem, locally revalidates the failing gate/test, commits (one commit per correction), records the attempt in progress.json, and returns control to whoever dispatched it. Does not implement new features, does not orchestrate the attempt loop, and does not decide ABORTED."

---

# Fix Runner

A surgical corrector. When the `evaluator` returns **FAIL**, it dispatches `fix-runner` with a structured error report. `fix-runner` fixes **only** the reported problem, with the smallest footprint, then hands control back to the `evaluator` to re-confirm. It is deliberately smaller and more focused than `implement-feature`: it corrects, it does not build.

> Base docs: `https://github.com/dayvisonassis/sdd-skills/blob/main/docs/Skill_Fix_Runner.md` (full rationale),

> `https://github.com/dayvisonassis/sdd-skills/blob/main/docs/Contrato_de_Feature.md` (contract criteria),

> `https://github.com/dayvisonassis/sdd-skills/blob/main/docs/ARQUITETURA_DAS_SKILLS.md` (flow, handoff, progress.json).

> Report schema: `../evaluator/references/evaluation-report-schema.md`.

**This skill is stateless about the loop.** The `evaluator` owns the attempt counter, the limit N, and the ABORTED decision. `fix-runner` performs **one** correction per invocation.

**Scope — code, not tests.** `fix-runner` corrects **production code** for failures the evaluator

classifies as `kind: gate` or `kind: observable-criterion`. **Test failures (`kind: test`) are

NOT its job** — the evaluator routes those to the matching test-writer (confirmed by the matching

test-validator). If a report handed to `fix-runner` contains only `kind: test` failures, return

"not resolved — test failures must be routed to a test-writer" without touching code.

## INPUT

- **Target feature** (ID) and the **path to `evaluation-report.json`** — passed by the **`evaluator`** (on FAIL) or by **`qa-preflight`** (after the feature is done). Both write the same schema, and the on-disk report is the source of truth either way.

- If no report path is given, auto-discover the feature's `evaluation-report.json` in `docs/<feature-id>-<kebab>/` and `lastEvaluationReport` in `progress.json`.

- Auto-discovers: the feature's `contract.md` and `progress.json`. Reads `spec.md`/`plan.md` lazily, only for the context the fix needs.

If no error report can be found, abort: "fix-runner requires an evaluation-report from the evaluator or from qa-preflight."

## OUTPUT

- A **minimal code correction** for the reported failure(s).

- **One commit** per correction — `fix(F<ID>): <error summary>` (or the repo's style). Stage only the touched files. The one exception is in Step 5: a correction a commit hook refuses because of its paired test stays uncommitted.

- A light update to `progress.json` recording that a correction was applied for the current `attempt` (does NOT decide the state).

- A signal back to the evaluator: **"correction applied — re-evaluate F<ID>"** or **"not resolved — <reason>"**.

- The fix-runner does **not** emit a CLEAN/FAIL verdict — the evaluator re-confirms.

---

## EXECUTION STEPS

### Step 1: Resolve Input

- Resolve the target feature and locate the `evaluation-report.json` (from the passed path, or auto-discover via `progress.json`'s `lastEvaluationReport`). No report → abort.

### Step 2: Load Minimal Context

- Read the `evaluation-report.json`: each `failures[]` entry — `kind`, `ref`, `message`, `location`, `evidence`.

- For each failure, re-read **only** the violated criterion/gate (`ref`) in `contract.md`, so the fix conforms to the contract rather than guessing.

- Read the section, in the project's gate documentation (`GATES.md` or its equivalent), of every declared gate whose scope the fix touches — not only the failing one: it states what the gate rejects and the accepted pattern the fix must follow.

- Read `progress.json` to know the feature and the current `attempt`.

- Read `spec.md`/`plan.md` lazily, only for the slice needed to understand the fix. No broad codebase sweep.

### Step 3: Apply the Minimal Correction

- Fix **exclusively** the reported cause(s), with the smallest footprint. No opportunistic refactoring, no "while I'm here" improvements, no scope beyond the report.

- If the report has multiple `failures[]`, address them together only if they are part of the same root cause; otherwise fix what the report lists, in order.

- Record what was changed and why (for the commit message and the handoff signal).

### Step 4: Local Revalidation

- If it still fails, adjust **within the same error's scope** and re-run. Do not expand scope to unrelated problems.

- **A test the report pairs with your failure turns red with your correction, by design.** The report holds a `kind: test` entry for a test that pins the behavior you are correcting, and your entry's `message` names it. That red is your revalidation, and the revalidation has passed when you see it: run that test and see it fail at its assertion, receiving the value the criterion states. If it stays green, the correction missed the behavior: adjust, within the same scope. It is not a failure to adjust for — never undo the correction or change the test: its writer rewrites it in the same round.

- **Browser gates (e2e or visual) run against the dev server, not the files on disk.** Before re-running one, confirm in the dev server's log that the rebuild after your edit finished successfully — a failed build keeps serving the previous bundle with HTTP 200. A `429` or every case on the sign-in screen is the auth rate limit, not your fix: stop re-running and return "correction applied (local revalidation skipped: environment — <which>)". Every run spends logins.

- This local check does NOT replace the evaluator — the evaluator re-confirms against the whole contract afterward.

### Step 5: Commit

- One commit, staging **only** the files touched by this correction. Message: `fix(F<ID>): <error summary>` (or match the repo's recent commit style).

- No `git add -A` / `git add .`. Commit on the current branch — never create or switch branches. Do not skip hooks.

- When a commit hook runs the paired test of Step 4 and refuses the commit, do not skip the hook: leave the correction in the working tree, uncommitted. The code and its test can only be committed together, after the writer's rewrite, and that commit is the human's.

### Step 6: Return to the Evaluator

- Update `progress.json`: record that a correction was applied for the current `attempt` (e.g. a note/timestamp). Do **not** set CLEAN/FAIL/PENDING/ABORTED and do **not** increment `attempt` — those belong to the evaluator.

- Signal back:

- **"correction applied — re-evaluate F<ID>"** when the local revalidation passed and the commit was made, OR

- **"correction applied (uncommitted: a commit hook runs `<test title>`, which this correction turns red; changed: <paths>) — re-evaluate F<ID>"** in the one case of Step 5 where a correct fix cannot be committed alone, OR

- **"not resolved — <reason>"** when the fix could not be made within scope (no commit).

- **"not resolved — needs an allowlist decision: <why>"** when the only way to clear a finding is a gate exception, which is a human decision (definition in `../evaluator/references/evaluation-report-schema.md`, "Gate exceptions"). No commit for it. Name each finding as the gate prints it (file, message and code), and say which of the categories the gate's section accepts it falls in: the evaluator checks the claim. **Never for a failure marked `exceptionRefused`**: a human already refused that exception, so correct it or return an ordinary "not resolved".

- Account for every failure in the report that is yours: fixed, claimed, or not resolved. A `kind: test` entry is not yours — it is its writer's — and gets no line. When one invocation does more than one of these, send the signals together. The evaluator counts the correction applied.

---

## RULES

**Always:**

- Act only from an evaluation-report — produced by the `evaluator` or by `qa-preflight`.

- Re-read the violated criterion/gate (`ref`) in `contract.md` before fixing, so the fix conforms.

- Fix only the reported cause, with the smallest possible footprint.

- Locally revalidate the failing gate/test before returning.

- Make one commit per invocation, staging only the touched files — or none, in the one case of Step 5.

- Hand control back to the evaluator for re-confirmation.

**Never:**

- Implement new features or widen the contract's scope.

- Do opportunistic refactoring outside the reported error.

- Make a gate exception of any kind (an allowlist or baseline entry, a raised ratchet, an edited gate rule or runner, an inline disable) — that is a human decision. When the only way out is one, return "not resolved — needs an allowlist decision: <why>".

- Make a gate pass by hiding the pattern it rejects from its detection: renaming the handle it recognises, wrapping the call in a helper it cannot see, or moving the code out of its scanned path. The fix is the accepted pattern in the gate's section.

- Count attempts, decide ABORTED, or emit a CLEAN/FAIL verdict (the evaluator's job).

- Write CLEAN/FAIL/PENDING/ABORTED into `progress.json` or increment `attempt`.

- Use `git add -A` / `git add .`; skip hooks; create or switch branches.

- Change what a test asserts so that it passes. A test that is wrong is a test-writer's to correct: when the report does not already list it, add "test to correct: <file> — <title>" to your signal.

- Read the codebase with a broad upfront sweep — read lazily, scoped to the fix.

---

## Edge Cases

**No evaluation-report found**: abort — the fix-runner needs the evaluator's report to act.

**Report references a `ref` not found in contract.md**: fix from the report's `message`/`location`/`evidence`, and note the missing contract reference in the return signal so the evaluator/spec-writer can reconcile.

**`kind: qa-finding`**: this is the expected shape, not an anomaly — the finding is a real defect that no contract criterion covered, and its `ref` is the QA case id that found it (e.g. `CT-ACESSIBILIDADE-002`). Fix from `message`/`location`/`evidence` and do **not** report a missing contract reference. Everything else is unchanged: minimal footprint, local revalidation, one commit.

**The report pairs your failure with a `kind: test` entry** (a test that pins the behavior the contract contradicts — one cause, two entries, and yours is the code): correct the code to the criterion, revalidate by that test turning red at its assertion, and return "correction applied". Leave the test exactly as it is. When a commit hook refuses the commit because of that test, return the uncommitted form of the signal, with the correction left in the working tree.

**Fix can't be made within scope** (the real cause is outside the reported failure, or requires a spec/contract change): do not stretch scope. Return "not resolved — <reason>" without committing, so the evaluator can decide (re-evaluate, PENDING, or eventually ABORTED).

**Local revalidation can't run in this environment** (missing toolchain/browser): make the minimal fix the report implies, commit, and return "correction applied (local revalidation skipped: <reason>) — re-evaluate F<ID>" so the evaluator runs the authoritative check.

**Multiple unrelated failures in one report**: fix each within its own scope; if one is unresolvable, fix the others, commit, and return a combined signal noting which remain.

**Working tree has unrelated changes**: stage only the files this correction touched; leave everything else untouched.

**Commit-message style inconsistent in recent history**: fall back to `fix(F<ID>): <error summary>`.