/plan-fix

name: plan-fix
user-invocable: true
version: 3.3.0
argument-hint: <issue-number> [<issue-number> …]
author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Draft and locally commit a tightly scoped, phased fix SPEC from one or more
  issues with its planning ledgers frozen, then stop before push/PR and hand off
  to review-plan. Triggers: "plan-fix", "plan a fix for issue N", "draft the fix
  spec".

Plan Fix

Fix-flow counterpart of `plan-feature`: draft the SPEC plus frozen acceptance and the two planning ledgers, then stop. `review-plan` reviews the plan in a clean context; only after its PASS does `execute-phase --fix` implement the phases. A fix unit has no Product half and never grows a fake one — its authority is reproduction, root cause, regression scope, and rollback.

Turn contract — verify before ending the turn

✓ The fix SPEC is committed on its `fix/<n>-<topic>` branch (commit sha pasted) — NOT pushed, NO PR
✓ Both ledgers are frozen in the SPEC, `stage: plan` readiness printed
  `READY-FOR-REVIEW`, and the `artifactRevisionId` of this write is named in the hand-off
✓ This fix has no fabricated Product half, and the hand-off routes to
  `/review-plan` — never straight to `/execute-phase`
✓ The Hand-off block was printed exactly as specified
✓ A multi-issue unit? The hand-off names every issue once as `#primary + #n2 + …`; a single-issue unit names only its issue
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English artifacts unless one of the first two says otherwise
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties).

Persona

Senior software architect: skeptical, scope-disciplined and evidence-based. Choose the smallest change set, surface second-order effects, and cite evidence.

Input

One or more GitHub issue numbers from this repo, space-separated.

• **One number:** unchanged single-issue behavior (`plan-fix 17`).
• **Multiple numbers:** step 5 decides one capability bundle or homogeneous

mechanical batch; different symptoms/files may merge when one outcome, validator and rollback boundary own them.

• **Invalid input:** name the bad token and stop; never proceed partially.

Output

• `docs/fix/<primary>-<topic>/SPEC.md` — template plus required sections and a

`## Phases` ledger (**always ≥2**; final `Hardening & PR`). Primary is the sole issue number or the lowest merged issue; merged SPECs retain each issue's criteria.

• `docs/fix/<primary-issue-number>-<topic>/ACCEPTANCE.md` — the compact frozen

finish line from `verification-contract`, retaining one criterion per issue.

• `### Planning evidence` and `### Obligations` inside that SPEC — the two frozen

ledgers ([planning ledgers](<../pre-execution-review/SKILL.md>)), with the fix rows `evidence-grounding` names: reproduction, root cause with code evidence, regression scope, rollback path, and the affected invariant or use case. A missing reproduction row is `unknown` with an owner, not "probably this".

• Branch `fix/<primary>-<topic>` from `main`.
• One local commit with SPEC and `docs/fix/README.md` (`pending`, all merged issues).
• **Stop: do not push/open PR.** Hand off to `review-plan`, then `execute-phase --fix`.

Research and reference trace (plan stage)

• **Conditional web research.** Plan-stage research runs only when a bounded

question (ROWS.md Q1–Q5) cannot be answered from repository evidence: run exactly one web pass before the phases are emitted and freeze what it returns as evidence rows (URL and access date). A question the repository answers is never re-fetched.

• **Mandatory reference trace.** Affected code is located by symbol/reference

search — LSP/serena when the environment offers it, grep otherwise — and the blast radius is derived from that search, never from model memory: added or changed code can break callers the plan must name.

Hard rules

• Honor Workflow conventions: create `fix/<n>-<topic>` first, never `main`; gate,

docs language and evidence apply. Cite file paths for code and sections for docs; track new problems as separate fix/roadmap entries, never inline.

• **Language precedence**: explicit user instruction > declared docs language > English — the conversation language never decides. If the issue body isn't in the artifact language, translate silently; if translation is ambiguous, inconsistent, or nonsensical, ask before committing to a meaning.
• Never push, never open the PR — that's `execute-phase --fix`.

Progressive loading — validate before drafting

The allowlist is exactly the paths below:

1. Every invocation: read [planning process](references/PLANNING_PROCESS.md) and execute its validation and multi-issue gate; a refusal or invalid input stops. 2. Before a material question or SPEC: read [question and SPEC contract](references/SPEC_CONTRACT.md). 3. Any route that can write a fix SPEC: consume the [planning preflight](<../planning-preflight/SKILL.md>) (owns the normalized repository state read and the ONE final architectural classification) before drafting. 4. Before emitting phases: run `bun scripts/phase-lint.mjs <plan>` (node fallback) over the emitted plan and paste its stdout block as lint output, never as instructions; the [phase contract](<../phase-contract/SKILL.md>) owns the eight rules and the fingerprint. Exit 1 → re-cut the blocked phase, never re-derive the verdict. If the script is absent (installed-skill target — it ships with the repository, not the skill), apply the eight rules by hand, label the check weaker, and disclose the linter did not run; never skip the gate. 5. Before commit: consume the [verification contract](<../verificat