fix-as-poc

name

fix-as-poc

description

Use when fixing a bug, dependency mismatch, broken build, or any other defect in product code under a canonical-branch-protecting workflow. Treat the fix exactly like a feature PoC — open a purpose-named report with the diagnosis and acceptance criteria, do the change in an isolated worktree, prove the gate goes from red to green, then cherry-pick. Trigger on "fix this", "build is broken", "deps mismatch", "rename leaks". This is the bug-side companion to `isolate-and-integrate`; it inherits that operation and adds the report-first discipline so a fix is documented evidence, not a hidden patch.

Treat a fix as a one-purpose PoC

A fix is a hypothesis under test, not a small patch you slip in. The same isolation that protects features from half-formed work also protects the canonical branch from "the obvious one-liner" that turned out wrong, masked a deeper failure, or carried a silent scope creep.

The shape of the operation

1. Open a problem ticket as a report. Create reports/<purpose>/README.md before opening any product file. State
   • the observed failure (the exact command + the exact output);
   • the diagnosis (what is the root cause, evidence-backed);
   • the hypotheses considered (table of options + why one was chosen);
   • the acceptance criteria (the precise definition of "green" — which gates must pass, which side-effects must be absent);
   • the scope boundary (what this fix does NOT cover; what other pre-existing issues are deferred). This sits in reports/ because the diagnosis and the choice are knowledge that outlives the diff.
2. Cut a worktree off the canonical branch on a fix/<purpose> branch (per isolate-and-integrate).
3. Apply the smallest change that satisfies the acceptance criteria.
   • For dependency drifts: bump within the documented peer range; do not refactor.
   • For partial renames: complete the rename — do not paper over with shims.
   • For environmental glitches: change the environment, not the code.
4. Run the full gate (typecheck / lint / test / build, all four). The previously-red gate must go green AND no previously-green gate may regress.
5. Cherry-pick onto the canonical branch and re-run the gate there.
6. Close the report. Append a ## 5. Result section with the actual diff, the gate output (last lines per stage), and a docs/ promotion judgement (most one-shot fixes do not promote; some, like a recurring runbook, do).
7. Discard the worktree.

Special rule: red-on-arrival is a separate ticket

While running the gate inside the worktree, an unrelated, pre-existing failure may surface (a build red on source/main that the previous PR didn't catch, a ghost untracked file, a partial earlier rename). When this happens:

• Do NOT widen the current PoC's scope. "While I'm here" is how fixes lose their evidence trail.
• Stop, surface the finding, and open a sibling report reports/<other-purpose>/README.md.
• Land the sibling fix first, in its own worktree. Then git rebase the original worktree onto the new canonical tip and continue.
• The original report's ## 5. Result records the discovery and repeats the facts and evidence needed to explain the dependency. Do not link to the sibling report; each report must satisfy the zero-knowledge evidence rule in CLAUDE.md on its own.

This rule preserves "1 PoC = 1 purpose" and keeps each commit's blast radius readable.

Where the change lives

Most fixes touch one of:

• Product source (source/<package>/...) — same isolate→cherry-pick rules as features.
• Workspace metadata (lock files, root configs, dependency manifests) — still through the worktree; the gate runs the same way.
• Build / CI config — even more reason to PoC: red CI is what catches the next regression.

If the fix would naturally span more than one of these, that is itself a signal the diagnosis is incomplete; refine the report's "diagnosis" section, not the patch.

When the diagnosis is unclear

Use the orient-before-edit skill first: build a structure brief over reports/ and the suspected owner subtree to find prior investigations and the likely owner. The orientation tooling can read both the report directory and the canonical source tree in one pass — a previous report on the same area is often the fastest path to a correct hypothesis.

The one allowed shortcut

A trivial mechanical fix in a single line (a typo, a one-char import path, a clearly-isolated formatter glitch) MAY be applied without a report, provided the worktree gate is still run. If the gate exposes anything beyond the typo, fall back to the full procedure — the patch is no longer trivial.

The concrete commands, branch-naming, gate invocations, and commit conventions are project-specific — read the project's CLAUDE.md. This skill is the discipline; the project supplies the verbs.