dr-implement-fix · diff
git:20260805.132bdbb to git:20260813.5683bc4
27 added, 33 removed. Audit A to A.
---
name: dr-implement-fix
description: Apply an approved FIX.md to DeepReason with regression tests and the full gate. The only skill allowed to modify production code. Use after FIX.md passes its approval gate.
---
# Implement the fix
Input: an approved FIX.md. Output: one commit containing the fix, its
regression test, and any fixture updates FIX.md authorized — nothing
else.
## Procedure
1. **Touch only FIX.md's change sites.** If implementation reveals a
needed site FIX.md missed, STOP: amend FIX.md first (one commit),
then continue. Silent scope growth is the failure mode this
workflow exists to prevent.
2. **Write the regression test first**, converting the REPRO artifact:
it fails before your change, passes after. Its docstring names the
live run/record that motivated it (e.g. "Regression (selfstudy
run-9175f0ec): ..."), so the next reader can find the evidence.
Build it to `dr-execute-step`'s "Durable tests, checks, and probes"
rules — committed evidence only, meaning over form, mutation-proved,
wall-clock scrubbed recursively, absence-tolerant — so it survives
repo changes and fails only when the defect returns.
3. Apply the code change. Comments state the constraint the code
cannot show ("compare by handle index, not mapping order: canonical
JSON sorts keys"), never the change's history or your reasoning.
4. **Run outward rings, stop at first failure:**
pytest <regression test> -x -q
pytest <the changed subsystem's test files> -q
pytest tests/ -q -n 4 # full gate, ~8 min
The full gate must report **0 failed**. A pre-existing failure you
did not cause: stop, report, do not "fix it while you're there."
If FIX.md's change sites touch the packaging surface (pyproject
entry points, CLI commands, MCP tools/schema, wheel layout), one
more ring the gate does not run: `python scripts/wheel_smoke.py`,
with its pinned expectations updated in this same commit.
5. A gate failure caused by your change is information: if a fixture
depended on the defective behavior (FIX.md predicted it), update
the fixture minimally so it exercises what the test actually
guards; if the failure is NOT predicted by FIX.md, your fix is
wrong — revert to the last green state and return to the
orchestrator for re-diagnosis. Never weaken an assertion to green.
6. If a live run root is needed for the next phase and the identity is
- occupied: retire the old root (`git mv run-<id>
- <failed|completed>-epochN-run-<id>`), commit the rename FIRST as
- its own commit, then proceed.
+ occupied: retire it — procedure canonical in `dr-drive-harness` §3
+ (retire by rename, commit the rename FIRST as its own commit).
7. **Update the map in THIS commit** — see "Map obligations" below.
- 8. Before committing: compare the ACTUAL changed lines
- (`git diff --stat`) against FIX.md's budget ceiling. Exceeding it is
- a STOP in the standard format (decision, priced options,
- recommendation), not a footnote — an estimate-only ceiling trips on
- nothing (recorded miss: 193 insertions against ≤150, V1 tranche
- 2026-08-05). Then commit once, push with retry:
+ 8. Before committing, run the mechanized budget gate against FIX.md's
+ Estimated-diff ceiling — the same instrument `dr-execute-step` uses
+ for Family-2 steps, so this check can no longer be an eyeballed
+ `git diff --stat` compare:
+ python tools/diff_budget.py <tranche-base> --ceiling <FIX.md's
+ Estimated-diff ceiling> --paths <FIX.md's change sites>
+
+ Read `DIFF_BUDGET_RESULT_V1.verdict`. `WITHIN`/`NO_CEILING`:
+ continue. `EXCEEDED` is a STOP in the standard format (decision,
+ priced options, recommendation), not a footnote — the by-eye
+ version of this check missed an over-budget diff before this gate
+ existed (V1 tranche 2026-08-05: 193 insertions landed against a
+ <=150 ceiling with no stop). Then commit once, push with retry:
+
git add <exact files> <map files> && git commit -m "<what and
why, with the live evidence and 'Full gate: N passed, 0
failed'>"
git push -u origin <branch> # retry x4, backoff 2s 4s 8s 16s
## Map obligations (docs/map/)
- A fix changes what the code does; the map says what the code does. They
- travel together or the map becomes a document that lies, which costs
- more than no document.
-
- - **Same commit, not a follow-up.** A separate "update docs" commit is
- a commit that gets dropped.
- - **Every fix earns a `Traps` entry** in the `SUB-`/`CON-`/`SEAM-`
- document covering the changed code. A defect that reached the record
- is exactly the memory the map exists to keep. Name the run id or the
- tranche. Never delete an old Traps entry — rewrite it to say it was
- fixed and when.
- - **Advance `Verified-at:` only if you re-ran that document's checks.**
- A stale stamp is honest; a false one is not.
- - **A new invariant needs a new check**, at column 0, that would fail
- if the invariant broke. If you cannot write one, the claim is too
- vague to record.
- - Run before committing:
-
- python tools/docs_verify.py # every check; must pass
- python tools/docs_verify.py --audit # no vacuous checks
-
- Both are part of the gate. `--stale` is advisory: read what it lists,
- update what your change actually invalidated.
+ Same procedure `dr-execute-step` uses for Family-2 steps (same commit
+ not a follow-up; SEAM before subsystem docs; new invariant needs a new
+ check; advance `Verified-at:` only if re-run; `docs_verify` full +
+ `--audit` must pass before commit) — canonical there, not restated here.
+ One Family-1-specific addition: **every fix earns a `Traps` entry** in
+ the `SUB-`/`CON-`/`SEAM-` document covering the changed code. A defect
+ that reached the record is exactly the memory the map exists to keep.
+ Name the run id or the tranche. Never delete an old Traps entry —
+ rewrite it to say it was fixed and when.
## Prohibitions
- No drive-by refactors, renames, TODO cleanups, or formatting churn.
- No new dependencies, no config default changes, unless FIX.md lists
them as change sites.
- - Never edit committed run roots; never commit `env` files.
+ - Never edit committed run roots; never commit `env` files — both
+ procedures canonical in `dr-drive-harness` §1/§3.
## Exit criteria
- One pushed commit (plus at most one root-retirement commit).
- Full gate output pasted into the tranche log: N passed, 0 failed.
- `python tools/docs_verify.py` passes, and the map documents covering
the changed code carry a Traps entry for this defect.
- Return to the orchestrator.