Compass Method Bug Fix

Name the domain concepts the report touches and resolve each to a knowledge document (Grounding). Where a cluster has a structure note, read that first: it says which pages are load-bearing.

A concept that resolves to nothing is a finding, not a blocker. Record the assumption you are proceeding on and carry on (compass-principle-never-block-on-the-human); the missing page is a discovered task, not a reason to stop.

Use compass-doc-find and compass-doc-show.

Before touching anything, write down what would make this fixed, in terms someone else could check. "The link resolves" is a predicate. "Search works better" is not.

This is the phase most often skipped and the one that decides whether the rest is honest. A predicate written after the fix describes the fix; a predicate written before it describes the defect.

Make it happen, on the surface it was reported on. A defect you cannot reproduce is one you cannot prove fixed, and a fix for an unreproduced defect is a guess with a commit message.

If it will not reproduce, force it: tighten the conditions, synthesise the trigger, add logging and read it. That work is not overhead; it is the instrument the last phase needs.

For a failing test, use compass-code-investigate-test-failure.

Form the candidate causes, then eliminate them against evidence rather than plausibility (principle-fix-root-causes). Each pass, take the split that cuts the most remaining space.

Stop at the cause, not at the first place the symptom disappears. The test is whether you can say why the defect happened, not merely where it stops happening.

Then check the blast radius before fixing: grep every caller of what you are about to change. A guard in the shared function is a smaller diff than a guard in each caller, and patching only the path the report names leaves its siblings broken.

The smallest change the evidence justifies. A belt-and-suspenders extra that "might also help" is a second hypothesis riding on the first; it does not ship (principle-laziness-protocol).

If the fix crosses a boundary or the design is unclear, stop and design first rather than discovering the shape by editing.

Run the reproduction from phase 3 and watch it pass (principle-prove-it-works). Then climb the verification ladder as far as the change earns: the check that would have caught this, then the class checks for what you touched, via compass-code-run-build.

Leave the check behind. A defect that no check would have caught is a defect that can return, so where the cost is reasonable the fix ships with the test or the lint that fails without it (principle-encode-lessons-in-structure, compass-code-add-tests).

Order the commits so the failing case lands before the fix, and the history tells the story (principle-sequence-verifiable-units). Close the bookkeeping with compass-agile-close-task, then raise with compass-pr-raise.