Plan Feature From Issue

---
name: plan-feature-from-issue
user-invocable: false
version: 2.0.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.

**This skill stops at the Product half.** It designs, then the unit goes to
`review-spec` for an independent Product review; engineering planning is a
different authority's turn. Composing `plan-feature-scaffold` in the same breath
as the design it just wrote is the bypass this separation exists to close — the
author of a Product half cannot be the one who decides it is ready to build on.

## 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. Then run the `stage: spec` readiness
   preflight from the internal
   [`evidence-grounding`](<../evidence-grounding/SKILL.md>) capability, mint the
   current `artifactRevisionId`, and **stop**: this skill never continues into the
   engineering half, never promotes the row past `defined`, and never composes
   `plan-feature-scaffold` in this turn. The `plan-feature` router may scaffold only
   after `review-spec` returns a current `spec-review-pass` receipt bound to these
   exact bytes.
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
   Readiness: READY-FOR-REVIEW | NEEDS-EVIDENCE | NEEDS-DESIGN   Artifact revision: <id>
   Traceability: Closes #<N> wired
   → review-spec next (engineering planning is gated on its receipt; do not scaffold here)
   ```

## Guardrails

- Don't silently expand scope beyond the issue — surface additions as proposals.
- Don't open the feature branch or write code here.
- **Don't plan engineering work here.** No Engineering half, no phases, no
  `defined → planned` promotion, no in-turn `plan-feature-scaffold` composition:
  the Product half this skill writes must be reviewed by `review-spec` first, and
  readiness `READY-FOR-REVIEW` is not that review.
- 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.
- `review-spec` — the mandatory next hop for every issue-derived feature: it
  reviews and receipts the Product half this skill produced.
- `plan-feature-scaffold` — fills the engineering half later, only once
  `review-spec` passed. This skill never invokes it.
- `execute-phase` — executes the phases; its PR carries `Closes #N`.

## Done when

- A filled SPEC product half exists, roadmap-registered at `defined`, with the
  `stage: spec` readiness block printed and the current `artifactRevisionId`
  recorded.
- 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.
- Nothing was scaffolded: no Engineering half, no phases, no `planned` write, and
  the fixed report hands off to `/review-spec`.
- `#N` is recorded and the PR plan includes `Closes #N`.
- Scope gaps were resolved with the user, not assumed.