/plan-feature

name: plan-feature
user-invocable: true
version: 5.2.0
argument-hint: <NN-slug | #N> | --from-issue N | --scaffold <slug> | --next
author: "Gabriel Trabanco <gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Route designed features or issues into engineering planning and roadmap
  registration; undesigned work stops at design-feature. Supports `--next`,
  `--from-issue`, and `--scaffold`. Triggers: "plan-feature", "plan a feature",
  "plan the next roadmap feature", "create SPEC and TASKS".

Plan Feature (router)

The engineering-planning door for a feature whose product definition already exists. Routes to a focused internal step so only the work you need runs (no fat single skill). **Docs only — no code, no branch.** Product definition (raw-idea interview, capability closure) is `design-feature`'s job, not this one — the routed redirect gate enforces that split.

Turn contract — verify before ending the turn

✓ The redirect gate ran FIRST, before any SPEC edit: undesigned input → STOP,
  print the fixed `/design-feature <slug>` block, do nothing else this turn
✓ Then the Product-review gate ran: no current `spec-review-pass` receipt bound to
  the recomputed snapshot → STOP with its fixed block and the `/review-spec`
  hand-off; a candidate/verification receipt, a Plan receipt, or readiness never counts
✓ Designed input only: engineering half filled, artifacts written, and the
  roadmap entry registered (number, order, deps verified)
✓ If `plan-feature-scaffold` ran this turn: the roadmap row was re-read
  AFTER the write and literally reads `planned` — a dropped `defined→planned`
  write fails this box; do not end the turn until it's fixed
✓ Planned, not reviewed: the ledgers are frozen, `stage: plan` readiness printed
  `READY-FOR-REVIEW`, and the turn hands off to `/review-plan` — this skill never
  reviews the plan it just wrote and never hands off to `/execute-phase` for a
  plan with no current Plan review receipt
✓ The dependency & blocker check was RUN and its result decides which closing block is printed
✓ An unmet dependency? The closing block lists the complete dependency chain, deepest first, joined with ` + `
✓ Artifact language: explicit user instruction > the project's declared docs language > English. The CONVERSATION language never decides — a Spanish prompt still produces English PRs/issues/commits/SPECs 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; this list is first on purpose).

Step 0 — Discover the project (always first)

Per the agent guide's **Workflow conventions** + **documentation map**, then read what THIS skill needs: the **roadmap** (`docs/features/ROADMAP.md`), so routing and roadmap registration match the project's real layout.

Progressive loading — route before planning

The allowlist:

1. Every invocation: read [redirect gate and routing](references/ROUTING.md), apply the status gate, then the Product-review gate, and stop on its exact block when instructed. 2. Any route that can write planning artifacts: after the redirect gate permits routing, consume the [planning preflight](<../planning-preflight/SKILL.md>) — it owns the normalized repository-state read and the ONE final architectural classification — before composing an internal step. 3. Before composing an internal step: load the [phase contract](<../phase-contract/SKILL.md>) so every SPEC written this turn carries the canonical 8-box phase-lint and the normalized phase fingerprint. 4. Only when `node scripts/unit-route.mjs <NN>` prints `route: replan`: load the [replan contract](<../replan-findings/SKILL.md>); it owns the exemption.

Do not load planning gates after a redirect stop. Both resources are normative, one hop from this file, and fail closed when missing.

Process

1. **Redirect gate** from `ROUTING.md` — always first. 2. **Product-review gate** from the same resource — current `spec-review-pass` receipt bound to the recomputed snapshot, or STOP. No bypass flag. 3. **Route** from the same resource. For issue input, resolve and validate the issue identity only; after the [planning preflight](<../planning-preflight/SKILL.md>) confirms that planning may write, compose the from-issue internal to produce a **filled, sized SPEC product half**; that internal stops at the Product-review gate, so `plan-feature-scaffold` runs only once `review-spec` has passed the half: it fills the engineering half, scales the artifacts to the SPEC's size (XS/S → SPEC-only; M/L → full set) and registers the roadmap. The already-designed scoped path runs `plan-feature-scaffold` directly. Every path holds **one immutable planning context** — the roadmap snapshot taken before writing (and one issue payload when `--from-issue`) — reused across the internal steps; never re-fetched mid-plan. 4. **Confirm roadmap.** Verify the feature is registered in `docs/features/ROADMAP.md` with the right number, ordering, and dependencies; if any of the three is missing or wrong, fix the entry now — never leave registration for later. 5. **Dependency & blocker check (always, before recommending execution).**

• Walk the feature's `Depends on:` closure (transitively): every dependency

must be `done` **and merged**. Any unmet → the closing block recommends building the deepest unmet dependency first, NOT this feature.

• Check the fix index + open issues (forge CLI) for fix-now items touching

the same modules this SPEC names. Any hit → the closing block recommends `/plan-fix <n>` before execution ("building on a known defect bakes it in").

• Planning itself never blocks on either — the SPEC/artifacts are still

written; only the **recommended next step** changes. 5. **Print the next