@gtrabanco/pi-agentic-workflow 0.1.0

package/skills/plan-feature-from-issue/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: plan-feature-from-issue
+user-invocable: false
+version: 1.7.0
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal step of plan-feature: turn a feature-request issue into a scoped,
+  sized, roadmap-mapped SPEC **product half** (capability closure satisfied)
+  with Closes #N traceability.
+---
+
+# Plan Feature — From Issue (internal)
+
+Convert a feature-request issue into the project's planning artifacts, keeping a
+clean issue → SPEC → PR(Closes #n) trace. Writes the SPEC's **product half**
+(same two-halves convention `design-feature` uses) and must satisfy capability
+closure before handing off — a thin issue does not get a shortcut around it.
+
+## When to use
+
+- The `plan-feature` router calls this when the input is a GitHub issue (or
+  `--from-issue N`) that describes new product capability.
+
+If the issue is a **bug or tech-debt**, stop and route it: `triage-issue` to
+classify, then `plan-fix` + `execute-phase --fix`. This skill is for
+genuine features only.
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, then read
+what THIS skill needs: the feature SPEC template, the roadmap, and the issue/PR
+templates (`.github/ISSUE_TEMPLATE/`, `.github/PULL_REQUEST_TEMPLATE.md`) so the
+SPEC mirrors the fields reviewers expect. Then read the issue (forge CLI per the
+project's Workflow conventions — examples use `gh`):
+
+```sh
+gh issue view <N> --json number,title,body,labels,state,comments
+```
+
+## Process
+
+1. **Classify first.** Confirm it is a feature. Not a feature if it describes a
+   defect, regression, duplicated code, perf debt, or carries a "when to
+   fix / trigger" clause → hand to `triage-issue`. State the verdict explicitly.
+2. **Normalize language.** If not in the project's docs language (this repo:
+   **English**), translate before drafting any artifact.
+3. **Map to the roadmap.** Assign the next number + slug. Identify dependencies
+   and conflicts with existing features, coupling/migration risks, and whether
+   it should instead extend an existing feature.
+4. **Close product-half gaps proactively.** Compare the issue against what a
+   complete SPEC **product half** needs (goals, scope in/out, business goals,
+   i18n/SEO/a11y/pricing per the docs map, a UI design reference when the
+   feature has a UI surface), probing the same fixed **vagueness rubric**
+   `design-feature`'s interview uses: affected users/roles · error & edge
+   states · data shape · boundaries & limits · out of scope · success
+   criteria — each slot filled or explicit `n/a: <reason>`. For each genuine
+   gap you can't safely default, ask the user **one question per turn, never
+   batched**, each with a recommended default; never ask what the issue or
+   docs already answer. **Structural hand-off threshold:** if ≥ 3 rubric
+   slots remain unfillable from the issue plus the answers so far, stop and
+   hand the feature to `design-feature` (the thin-issue rule below, now with
+   a fixed trigger) instead of continuing to interview here.
+5. **Satisfy capability closure.** Walk the same fixed checklist
+   `design-feature` uses (per entity: CRUD + state transitions, each with UI +
+   API + test, or explicit `n/a: <reason>`; per capability: entry point + ACL;
+   per role: assigned/revoked/viewed where) into the SPEC's `## Capability
+   closure` and `## Acceptance criteria`. **A thin issue that doesn't carry
+   enough to fill it is not a shortcut around the gate** — hand it to
+   `design-feature` (compose in-turn only at ≥ this skill's tier, per
+   *Guardrails*; otherwise hand off with `run /design-feature <slug>` and stop
+   here) rather than stamping `designed` on a hollow closure.
+6. **Size it.** Estimate `XS / S / M / L` (scale defined in the SPEC template)
+   and record it in the SPEC. XS/S → the SPEC is the only planning artifact
+   (single-pass execution); M/L → full artifact set. If L, propose splitting.
+7. **Produce the SPEC product half.** Fill it and stamp `## Design status:
+   designed` once closure is complete; set the roadmap row (added at `idea`
+   first if it didn't exist) to `defined` in the same edit — the same
+   `idea → defined` transition `design-feature` owns, performed here when this
+   skill is the one that satisfies closure. The `plan-feature` router then runs
+   `plan-feature-scaffold` for the engineering half + `defined → planned`
+   roadmap promotion.
+8. **Wire traceability.** Record `#N` in the SPEC; the PR body must include
+   `Closes #N` so the issue closes on merge.
+9. **Hand off — return exactly** (fixed completion report, back to the router):
+
+   ```
+   ISSUE #<N> → SPEC <slug> — size: <XS|S|M|L>
+   Verdict: feature (not bug/debt — else this would have routed to triage-issue)
+   Gaps closed: <n> asked / <n> defaulted (logged)   Closure: designed | handed to design-feature
+   Traceability: Closes #<N> wired
+   → scaffold next (plan-feature-scaffold)
+   ```
+
+## Guardrails
+
+- Don't silently expand scope beyond the issue — surface additions as proposals.
+- Don't open the feature branch or write code here.
+- Keep the `Closes #N` link; an issue-born feature must close it.
+- **Never stamp `## Design status: designed` with a blank Capability closure
+  row** — the same rule `design-feature` follows; a thin issue hands off
+  instead of faking closure.
+- **Composition tier.** Composing `design-feature` in-turn for a thin issue is
+  allowed only when this skill is running at ≥ `design-feature`'s tier
+  (planning-class — strongest model / highest effort); otherwise hand off
+  (`run /design-feature <slug>`) rather than under-power it.
+- Otherwise honor the project's **Workflow conventions** (branch/PR, docs-language).
+
+## Architectural invariants
+
+The [planning preflight](<../planning-preflight/SKILL.md>) owns the normalized
+repository state read and the ONE final architectural classification for the
+whole plan. Consume it here before writing the product half: for each applicable
+invariant rule, cite its ID and repository evidence and classify the issue
+proposal as `preserves`, `violates`, `introduces`, or `changes`. Only
+`preserves` can be stamped `designed`; every other classification stops for an
+explicit architectural decision through the project-declared authority — never
+before the full plan exists, and never inferred from the issue body, SPEC, or
+passing test.
+
+## Relationship to other skills
+
+- `triage-issue` — decides bug vs feature vs defer; call it if unsure.
+- `plan-fix` — the fix-side sibling for bug/debt issues.
+- `design-feature` — receives thin issues this skill cannot safely close
+  capability closure for; both write the SPEC's product half in the same format.
+- `plan-feature-scaffold` — fills the engineering half once the product half
+  is designed.
+- `execute-phase` — executes the phases; its PR carries `Closes #N`.
+
+## Done when
+
+- A filled SPEC product half + planning artifacts exist, roadmap-registered.
+- Capability closure is satisfied (or the issue was handed off to
+  `design-feature` instead of faking it) and `## Design status` is accurate.
+- The roadmap row status is `defined` (added at `idea` first if new) whenever
+  `## Design status: designed` was stamped — never `defined` on a hollow
+  closure, never left at `idea` once `designed` is stamped.
+- `#N` is recorded and the PR plan includes `Closes #N`.
+- Scope gaps were resolved with the user, not assumed.

package/skills/plan-feature-scaffold/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: plan-feature-scaffold
+user-invocable: false
+version: 1.14.0
+author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
+license: MIT
+description: >
+  Internal step of plan-feature: from an already-designed SPEC (product half
+  `designed`), fill the **engineering half** and generate the planning
+  artifact set scaled to the feature's size (XS/S → SPEC-only with ≥ 2 phases
+  in the SPEC, last = Hardening & PR; M/L → full set with a hardening phase),
+  freeze one compact ACCEPTANCE.md for every size, and register the roadmap
+  entry. Docs only — never code.
+---
+
+# Plan Feature — Scaffold (internal)
+
+Turn a designed feature into the project's complete planning artifact set,
+ready for phase-by-phase execution. Fills only the SPEC's **engineering half**
+— the product half (goal, context, scope, capability closure) already exists
+and is marked `designed` before this skill ever runs (`plan-feature`'s
+redirect gate guarantees it). **Docs only — never code.**
+
+## When to use
+
+- The `plan-feature` router calls this once a feature's product half is
+  `designed` — from `design-feature`, `plan-feature-from-issue`, or an
+  already-scoped slug/SPEC — to fill the engineering half of its
+  `docs/features/<NN>-<slug>/SPEC.md` and the rest of the folder, then update
+  the roadmap.
+
+Not for product definition (that is `design-feature`) or writing code (that is
+`execute-phase`) or deciding *whether* to build (that is the `plan-feature`
+router / `triage-issue`).
+
+## Step 0 — Discover the project (always first)
+
+Per the agent guide's **Workflow conventions** + **documentation map**, then read
+what THIS skill needs: the feature SPEC **template**, the **roadmap**
+(numbering/order/deps), 1–2 recent feature folders to mirror the artifact set, and
+the architecture/domain docs the map points to. No template/roadmap → fall back to
+the agent guide and state the assumption.
+
+## Progressive loading — scaffold only after discovery
+
+The reference allowlist is exactly one path. After Step 0, read and execute the
+complete [scaffold process](references/SCAFFOLD_PROCESS.md). It owns the product-
+half gate, artifact scaling, roadmap transition, re-read, and fixed completion
+report. The [phase contract](<../phase-contract/SKILL.md>) owns the 8-box
+phase-lint and the normalized phase fingerprint.
+
+The resource is normative and one hop from this file. Missing resource → stop;
+never reconstruct phase or close-out wording from memory.
+
+The [verification contract](<../verification-contract/SKILL.md>) owns the
+`ACCEPTANCE.md` schema, validation ladder, and anti-weakening rules. Consume it
+after the engineering plan is complete and before registering `planned`.
+
+## Guardrails
+
+- Docs only. No source edits, migrations, or dependencies.
+- Respect the architecture: honor layer rules (inner layers don't import outer)
+  and any domain/i18n/SEO/a11y rules from the docs map.
+- **Architectural invariants.** The [planning preflight](<../planning-preflight/SKILL.md>)
+  owns the normalized repository state read and the ONE final architectural
+  classification for the whole plan; consume it here. Its absence is compatible:
+  record `n/a: no project invariants declared` in the engineering half. For
+  every applicable rule, record its ID, repository evidence, and
+  `preserves | violates | introduces | changes` classification in
+  `### Architecture impact`. Only `preserves` may produce phases; the other
+  classifications stop for an explicit architectural decision through the
+  project's declared authority — and only after the full plan exists, never
+  converted into a phase task or inferred from the product half.
+- Surface conflicts (numbering clashes, dependency cycles, scope overlap) before
+  writing, not after.
+- Otherwise honor the project's **Workflow conventions** (branch/PR, docs-language).
+
+## Relationship to other skills
+
+Invoked by the `plan-feature` router (after `design-feature` /
+`plan-feature-from-issue` designed the product half, or directly for an
+already-designed scoped slug/SPEC). Hands off to `execute-phase` for P1;
+`audit-docs` audits anytime.
+
+## Done when
+
+- `docs/features/<NN>-<slug>/` exists with the SPEC's engineering half +
+  `ACCEPTANCE.md` + every scaled planning artifact filled — the product half untouched from what
+  `design-feature` / `plan-feature-from-issue` wrote.
+- The roadmap lists the feature with correct number, order, dependencies, and
+  **status `planned`** (the `defined → planned` write this skill owns) —
+  **re-read and confirmed after the write**, not assumed from having run it.
+- No code changed; open questions captured in `decisions.md`.

package/skills/plan-feature-scaffold/references/SCAFFOLD_PROCESS.md

@@ -0,0 +1,76 @@
+## Scaffold process
+
+1. **Verify design.** `## Design status` must be `designed` and Capability
+   closure complete. Otherwise stop: this is a caller bug; never repair the
+   Product half here.
+2. **Resolve identity.** Confirm the existing number/slug, or choose the next
+   free number for a designed SPEC missing from the roadmap. Record dependencies
+   and surface numbering, ordering, cycle, or overlap conflicts before writing.
+3. **Fill only the Engineering half:** technical goals, architecture impact,
+   design, decisions to confirm, branch, phases, testing requirements, and dev
+   scenarios covering happy path plus reproducible empty/degraded, race, and
+   outage cases. Leave no placeholders; put genuine unknowns in `decisions.md`.
+4. **Scale by size:**
+
+   - **XS/S:** SPEC + `ACCEPTANCE.md`. Its `### Phases` has checkbox tasks and at least `P1`
+     implementation plus final `P2 — Hardening & PR`. Copy the final phase's
+     literal tasks from `docs/fix/_TEMPLATE/SPEC.md`; never paraphrase them.
+   - **M/L:** create `ACCEPTANCE.md`, `PLAN.md`, `TASKS.md`, `progress.md`, `testing.md`,
+     `known-issues.md`, `decisions.md`, and `architecture-notes.md`.
+   - **Mandatory split:** use `Depends on:`-chained features when the plan would
+     exceed about five phases, any phase spans multiple layers/concerns, or a
+     phase contains an unresolved design decision. Reuse the existing dependency
+     gate/build order; never invent another mechanism.
+   - Every phase passes: independently checkable tasks without judgment; zero
+     open design decisions; one layer/concern; locally runnable verification.
+     Re-cut or split on any failure.
+    - Run the canonical eight-box Phase-lint owned by the
+      [phase contract](<../../phase-contract/SKILL.md>) against every phase
+      before emission. Any FAIL is re-cut/split; never emit an unticked phase.
+   - Run the feature template's full Spec-lint after the Engineering half is
+     filled, including Product-half regression boxes. Fix every presence failure
+     before reporting.
+   - Consume the canonical [verification contract](<../../verification-contract/SKILL.md>)
+     and write one compact, frozen `ACCEPTANCE.md` for every size. Map every SPEC
+     criterion to a deterministic command, labelled read check, or exact manual
+     observation. The manifest is the implementation/review finish line, not a
+     second specification.
+
+### M/L artifact contract
+
+- `PLAN.md`: `P1, P2, …` phases only; no `S1`/`Step`. The last implementation
+  phase hardens and tests the SPEC failure scenarios.
+- `TASKS.md`: per-phase checklists. Express command-checkable acceptance as the
+  command; label judgment-only checks `read-verified`. Its final phase ends with
+  these literal tasks:
+
+  ```text
+  [ ] open the PR (`gh pr create --body-file <path>` — body written as a Markdown file, real backticks, never inline `--body`/heredoc that leaves `\`-escaped backticks) and PRINT THE PR URL in the chat
+  [ ] update the roadmap row to `done · [#<pr>](<pr-url>)`
+  [ ] commit `docs: link PR #<n>` and push
+  ```
+
+- `progress.md`: initialize only `Last reviewed: —`; the executor appends one
+  fixed-schema handoff entry after each phase with `Done`, `Remains`, `Gotchas`,
+  `Files`, and `Next`.
+- `testing.md`: test layers, preferring integration; use the same command rule.
+- `ACCEPTANCE.md`: required for every size; frozen validation manifest owned by
+  `verification-contract`, with the literal quality floor.
+- `known-issues.md`: deferred items linked to/destined for issues, never inline.
+- `decisions.md`: architecture/scope decisions and open questions.
+- `architecture-notes.md`: layer, port, schema, and binding impact.
+
+5. **Register and verify.** Set the roadmap row to `planned` (`defined → planned`;
+   a missing row may be added directly as `planned`). Re-read it after the write.
+   If it does not literally say `planned`, reapply and re-read before continuing.
+6. **Do not branch or code.** Record the future branch in the SPEC only.
+7. **Return exactly**; the `plan-feature` caller prints the closing hand-off:
+
+```
+SCAFFOLD <NN>-<slug> — size: <XS|S|M|L>
+Artifacts written: <SPEC.md ACCEPTANCE.md [+ PLAN.md TASKS.md progress.md testing.md
+  known-issues.md decisions.md architecture-notes.md for M/L]>
+Roadmap: registered as <NN> (deps: <list|none>)   Phases: <n> (P1…P<n>, last = <hardening (M/L) | Hardening & PR (XS/S)>)
+Spec-lint: PASS (<n>/<n> boxes)   Phase-lint: PASS (all phases)
+Open questions: <n> (in decisions.md) | none
+```

package/skills/plan-fix/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: plan-fix
+user-invocable: true
+version: 2.7.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, then stop before push/PR and hand off to execute-phase --fix. 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,
+stop for review, then `execute-phase --fix` implements every remaining phase.
+
+## 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
+✓ 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.
+- 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 `execute-phase --fix`.
+
+## 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 these five paths:
+
+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: load the [phase contract](<../phase-contract/SKILL.md>) for the 8-box phase-lint and phase fingerprint.
+5. Before commit: consume the [verification contract](<../verification-contract/SKILL.md>)
+   and write the frozen `ACCEPTANCE.md`.
+
+Resources are normative and one hop from this file. Missing required resource →
+stop; never approximate fixed blocks or phase rules.
+
+## Hand-off
+
+After commit, print exactly:
+
+```
+SPEC drafted: docs/fix/<primary>-<topic>/SPEC.md
+Branch: fix/<primary>-<topic> (local, not pushed)
+Commit: <short hash>
+Issue set: #<primary> + #<n2> + #<n3> (print every issue in this unit; single issue → #<primary>)
+
+→ Next: review the SPEC, then /execute-phase --fix <primary> — execute every remaining phase in issue set #<primary> + #<n2> + #<n3> and open the PR
+  · explicit atomic mode → /execute-phase --fix <primary> P<n> (same issue set: #<primary> + #<n2> + #<n3>)
+  · the final `Hardening & PR` phase pushes and opens the PR with `Closes #<primary>`
+    plus one `Closes #<n>` line for every other issue listed in the Issue set
+  · scope looks wrong → adjust the SPEC and re-run /plan-fix
+```
+
+Replace every placeholder with the complete actual issue set before printing;
+never print `<n2>`, `<n3>`, or `…` in a live hand-off.
+
+Then end in the user's language with a 2-3 sentence summary: what the SPEC ships, the biggest risk, and any open decisions left for the implementer.
+
+## Portability (agents other than Claude Code)
+
+Use explicit fallbacks when a primitive is absent: open named `SKILL.md` files in
+a fresh context; run architect-level scoping on the strongest model, then hand
+implementation to a cheaper worker.
+
+## Done when
+
+- The SPEC and frozen `ACCEPTANCE.md` follow canonical contracts, surface
+  risks/blockers, register in `docs/fix/README.md`, and are committed locally on
+  `fix/<n>-<topic>` (not pushed/no PR). The closing `→ Next:` Hand-off is printed.

package/skills/plan-fix/references/PLANNING_PROCESS.md

@@ -0,0 +1,118 @@
+## Planning process
+
+1. **Ingest all inputs.** Each token must be a numeric issue resolved by
+   `gh issue view <n> --json title,body,labels,number,author,createdAt,comments`
+   (use the declared forge equivalent). Any failure stops the whole set. Translate
+   issue text to the artifact language; ask only on material ambiguity. Derive a
+   kebab-case topic (≤40 chars, no leading verb) from the primary issue title.
+2. **Read the docs map.** Read `CLAUDE.md`, then relevant mapped docs; every SPEC
+   claim cites a path/section.
+3. **Locate affected code.** Name per issue the layers, modules/files, ports,
+   adapters, and entities.
+4. **Cross-check work.** List open issues and PRs; classify overlaps as
+   prerequisite, parallel, absorbable, or unrelated. Record dependencies and
+   Cross-issue notes.
+5. **Resolve one vs. many issues before drafting.** One issue proceeds as the
+   primary. Multiple issues may form one unit through either supported mode:
+
+   - **Capability bundle** — different symptoms/root causes jointly prevent one
+     user-visible or operational outcome (for example, login succeeds end to
+     end). They may touch different layers or the same file repeatedly.
+   - **Homogeneous mechanical batch** — the same low-risk transformation is
+     repeated across independent surfaces (for example, CSS token replacement,
+     documentation correction, or one API rename).
+
+   Evaluate the set as one atomic delivery boundary, not every pair by file
+   coincidence. All five boxes must pass:
+
+   Select the mode by first match: (1) different corrections jointly unblock
+   one named end-to-end outcome → `capability bundle`; (2) otherwise, the same
+   literal low-risk transformation repeats on every member → `homogeneous
+   mechanical batch`; (3) otherwise → split. Different files/layers never turn
+   an end-to-end capability bundle into a mechanical batch.
+
+   - one sentence names the shared outcome **or** the repeated mechanical rule;
+   - one verification plan proves every issue's separate acceptance criteria;
+   - the set can ship and roll back together without leaving a partial state;
+   - no conflicting dependency, release order, product/architecture decision,
+     permission/schema migration, or triage route requires isolation;
+   - aggregate work fits one reviewable fix PR (XS/S/M); an L bundle is promoted
+     to one feature rather than fragmented into fixes.
+
+   Shared files, one root cause, and equal severities are useful evidence but
+   are **not requirements**. A security-critical member raises the whole unit's
+   verification/routing floor instead of forcing a separate PR when the atomic
+   boundary still holds.
+
+   All pass → one unit whose primary is the lowest number; every issue retains
+   separate acceptance criteria and manifest IDs, the fix index names all, and
+   the PR later uses one `Closes #<n>` line per issue. Print exactly:
+
+   ```text
+   MULTI-ISSUE MERGE — #<primary> + #<n2> + #<n3>
+   Atomic-delivery mode: <capability bundle|homogeneous mechanical batch>
+   Checklist: ALL 5 boxes ticked
+     ✓ shared outcome/rule: <one sentence>
+     ✓ one verification plan covers every issue: <commands/checks>
+     ✓ one release + rollback boundary: <evidence>
+     ✓ no isolation conflict: <evidence>
+     ✓ aggregate size: <XS|S|M>
+   Unit: docs/fix/<primary>-<topic>/SPEC.md
+   Issues merged: #<primary> (primary) + #<n2> + #<n3>
+   PR will carry: Closes #<primary>
+                 Closes #<n2>
+   Closes #<n3>
+   ```
+
+   Replace the placeholders with every actual issue number before printing;
+   use ` + ` between all members and never print a literal ellipsis.
+
+   Any box fails → write nothing. Partition the input into the **fewest maximal
+   compatible groups** that do pass (singletons only when no bundle exists),
+   cite the set-level boundary that prevents their combination, print exactly,
+   and end:
+
+   ```text
+   MULTI-ISSUE SPLIT — the full set is not one atomic delivery unit
+   Boundary: <failing box> — <one-line repository/issue evidence>
+   No SPEC written. Recommended maximal groups:
+     /plan-fix <a> <b> <c> — <shared outcome/rule + verifier>
+     /plan-fix <d> <e> — <shared outcome/rule + verifier>
+     [/plan-fix <f> — singleton only because <reason>]
+   ```
+
+   Invalid/unknown token → print exactly and end without partial work:
+
+   ```text
+   Usage: plan-fix <issue-number> [<issue-number> …]
+   Invalid token: "<token>" — not a number, or not an issue in this repo.
+   ```
+
+6. **Define scope.** Include only the smallest change closing every unit issue.
+   Route each adjacent problem elsewhere; never absorb hypothetical improvement.
+7. **Analyze risk:** blast radius, detection lead time, operations (jobs, queues,
+   cache, schema, external adapters), security (auth, secrets, PII, webhooks,
+   limits), compliance (`n/a` when none), and migration/backward compatibility.
+8. **Acceptance/tests.** Make every criterion objective and map it to unit,
+   integration, contract, architecture, or justified manual verification. Name
+   regression-risk tests; keep merged-issue criteria identifiable.
+9. **Observability.** Name the log/metric/alert proving health and silent failure.
+10. **Affected docs.** Add an acceptance criterion for every mapped doc update.
+11. **Rollback.** Give one command/PR-revert flow, data cleanup (or `none`), and
+    what is preserved/lost.
+12. **Effort.** XS ≤1h/1 commit; S ≤4h/1 commit; M ≤1 day/multi-commit; L >1 day
+    → propose `plan-feature`; the user decides.
+13. **Phases.** Emit at least one `P1..Pn` implementation phase plus final
+    `P(n+1) — Hardening & PR` (always ≥2 total). Each task is independently
+    checkable without judgment; each phase has zero open design decisions, one
+    layer/concern, and a local gate. Copy the template's final tasks literally.
+    Run the canonical eight-box Phase-lint (owned by the [phase contract](<../../phase-contract/SKILL.md>)) on every implementation phase; re-cut or split any FAIL.
+14. **Self-review.** All template/extra sections filled; claims cited; no scope
+    creep; out-of-scope work routed; acceptance checkboxes independently
+    verifiable; phase rules satisfied; template Spec-lint fully ticked; no
+    placeholders; artifact language correct.
+15. **Commit locally.** Run `git branch --show-current`. From the default branch,
+    create `fix/<primary>-<topic>`; from another working branch, stop and ask.
+    Stage the SPEC and `docs/fix/README.md`; commit
+    `docs(fix): draft SPEC for #<primary>[+#<n2>+…] — <topic>`. Never push or
+    open a PR. Print branch, sha, and the entrypoint's hand-off block.

package/skills/plan-fix/references/SPEC_CONTRACT.md

@@ -0,0 +1,22 @@
+## Question protocol
+
+Follow the project's **Workflow conventions** question protocol (what / scope / criticality / each option with pros-cons + flagged recommendation). Fix-specific: *critical* = a wrong answer breaks production or invalidates the fix; also note **what it affects** (users, ops, security, data, future features). Only ask when the answer changes the SPEC materially — routine assumptions (e.g. a helper name) are made silently and recorded under "Decisions made during drafting".
+
+## SPEC sections (extends the base template)
+
+The base template at `docs/fix/_TEMPLATE/SPEC.md` is mandatory. Add these sections in order, after the existing ones:
+
+- **Impact** — layers touched (per the architecture doc); modules and files (paths); blast radius; detection lead time.
+- **Rules that must never be violated** — project-wide invariants the fix must preserve, from CLAUDE.md "Hard rules" + the cited docs. E.g. "Domain value-object rules hold", "Inner layers cannot import outer layers".
+- **Operational risks** — scheduled-job / queue / cache / schema / external-adapter interactions; concurrency or eventual-consistency hazards.
+- **Security risks** — auth, secrets, PII, webhooks, rate-limits.
+- **Compliance touchpoints** — any domain/compliance rules; note "n/a" explicitly if none.
+- **Affected docs** — files in `docs/` needing updates; each becomes an acceptance criterion.
+- **Observability** — log line / metric / alert confirming the fix is live and healthy.
+- **Cross-issue notes** — open issues / PRs that may absorb, block, or be blocked by this fix; decision for each.
+- **Effort** — T-shirt size with one-line justification.
+- **Decisions made during drafting** — non-blocking assumptions made by the architect, so the implementer can re-question.
+
+After the SPEC is complete, write `ACCEPTANCE.md` using the canonical
+`verification-contract`. For merged issues, keep at least one stable criterion
+ID per source issue so a shared implementation cannot hide an unclosed report.