---
name: plan
user-invocable: false
tags: [planning, prd, requirements, research]
model: inherit
model-preference: opus
model-preference-codex: gpt-5.4
model-preference-cursor: claude-opus-4-6
description: >
  Use this skill when performing structured project planning and PRD generation with three modes:
  new (project kickoff with repo scaffolding), feature (compact feature PRD),
  retro (data-driven retrospective). All modes share a researched Q&A engine
  that dispatches parallel Explore agents before each question wave, presents
  options via AskUserQuestion with recommendations, and produces documents
  with prioritized issue creation.
---

# Plan Skill

> Project-instruction file resolution: CLAUDE.md and AGENTS.md (Codex CLI) are transparent aliases — see [skills/_shared/instruction-file-resolution.md](../_shared/instruction-file-resolution.md). All references below to `CLAUDE.md` resolve via that precedence rule.

## File Structure

- `SKILL.md` — Core framework: mode router, Q&A engine, shared phases
- `mode-new.md` — Project kickoff: 3 Q&A waves, PRD template, repo scaffolding
- `mode-feature.md` — Feature PRD: 2 Q&A waves, compact scope, acceptance criteria
- `mode-retro.md` — Retrospective: metrics analysis, reflection waves, improvement actions
- `soul.md` — Product Strategist identity and behavioral anchor

## Soul Reference

Before anything else, read and internalize `soul.md` in this skill directory. It defines WHO you are — a Product Strategist who drives planning outcomes through structured research and decisive recommendations. Every interaction in this skill should reflect this identity. You are not a generic assistant; you are an opinionated product leader who backs every recommendation with data.

## Phase 0: Bootstrap Gate

Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

<HARD-GATE>
Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints.
</HARD-GATE>

## Phase 1: Read Session Config

Read and parse Session Config per `skills/_shared/config-reading.md`. Store result as `$CONFIG`.

After parsing, verify that `plan-baseline-path` is not null: `echo "$CONFIG" | jq -e '."plan-baseline-path"'`. If null, stop with: "Error: `plan-baseline-path` is not configured in Session Config. Add it to your CLAUDE.md (or AGENTS.md on Codex CLI) under `## Session Config`. Example: `plan-baseline-path: ~/Projects/projects-baseline`"

Plan-specific fields (also parse these): `plan-default-visibility`, `plan-prd-location`, `plan-retro-location`, `vcs`

Store all values for use in subsequent phases.

**Path expansion:** Expand `~` to `$HOME` in `plan-baseline-path`, `plan-prd-location`, and `plan-retro-location`. Verify expanded paths exist. If `plan-baseline-path` doesn't exist, warn: "Baseline path not found at [path]. `/plan new` repo scaffolding will be unavailable."

If no `## Session Config` section exists at all, stop and report: "Error: No Session Config section found in CLAUDE.md (or AGENTS.md on Codex CLI). The `/plan` skill requires at minimum `plan-baseline-path` to be configured."

> **Platform Note:** This skill uses `AskUserQuestion` extensively. On Codex CLI where this tool is unavailable, present all choices as numbered Markdown lists with "(Recommended)" on the first option. The user responds with their choice number. See `skills/_shared/platform-tools.md`.

> On Codex CLI, Explore agents map to the `explorer` agent role. See `skills/_shared/platform-tools.md`.

## Phase 2: Mode Router

> **Ambiguous scope?** If the feature's UX/scope is still ambiguous before starting, run `/brainstorm` first (see `skills/brainstorm/SKILL.md`) to produce a design spec, then return here with the spec as input. `/brainstorm` outputs `docs/specs/YYYY-MM-DD-<slug>-design.md`.

Parse `$ARGUMENTS` to determine the planning mode:

- **`new`** — Read `mode-new.md` in this skill directory for mode-specific instructions. This mode handles full project kickoff: requirement gathering, PRD generation, repo scaffolding, and issue creation.
- **`feature`** — Read `mode-feature.md` in this skill directory for mode-specific instructions. This mode handles feature-level PRDs with compact scope and acceptance criteria.
- **`retro`** — Read `mode-retro.md` in this skill directory for mode-specific instructions. This mode handles data-driven retrospectives with metrics analysis and improvement actions.

If `$ARGUMENTS` is empty or does not match any mode, use AskUserQuestion to ask:

```
AskUserQuestion({
  questions: [{
    question: "Which planning mode do you want to run?",
    header: "Plan Mode",
    options: [
      { label: "new", description: "Project kickoff — full PRD, repo setup, issue creation. Use when starting a brand new project." },
      { label: "feature", description: "Feature PRD — compact scope, acceptance criteria, issues. Use when adding a feature to an existing project." },
      { label: "retro", description: "Retrospective — metrics analysis, reflection, improvement actions. Use after completing a project phase or sprint." }
    ],
    multiSelect: false
  }]
})
```

After mode selection, proceed to Phase 3 with the chosen mode.

## Phase 3: Q&A Engine (Shared Core)

This is the distinctive mechanic shared by all three modes. Every question wave follows the same pattern: research first, then ask.

### 3.1 Pre-Question Research

Read [Research Evidence Contract](../_shared/research-evidence.md) before the
first research wave. Apply it to findings that materially affect an option or
recommendation; keep trivial local lookups concise. Carry the source revision or
date, evidence basis, local equivalent, disposition, and any falsifiable next
check into each research brief and the synthesis so documented claims and
inferences remain distinct.

Before each Q&A wave, dispatch 2-3 `Agent()` tool calls in a single message (parallel execution) with `subagent_type: "Explore"`:

1. **Market/online context agent** — searches for relevant market data, best practices, competitor analysis, or technical patterns depending on the questions to be asked. Tools: WebSearch, WebFetch.
2. **Baseline analysis agent** — reads projects-baseline templates, rules, and scripts at `$BASELINE_PATH` to discover available options (archetypes, styles, configurations). Tools: Read, Glob, Grep.
3. **Repo context agent** (skip for `/plan new` wave 1) — analyzes the current repository for existing patterns, file structure, dependencies, and conventions. Tools: Read, Glob, Grep.

Example dispatch:

```
Agent({ subagent_type: "Explore", description: "Research market context for [topic]",
  prompt: "Search online for [topic]. Report findings with pros/cons for each option." })
Agent({ subagent_type: "Explore", description: "Analyze baseline templates",
  prompt: "Read projects-baseline at $BASELINE_PATH/templates/. List available archetypes, their README descriptions, and key features." })
Agent({ subagent_type: "Explore", description: "Analyze repo context",
  prompt: "Explore current repo for [relevant patterns]. Report affected files and existing conventions." })
```

Wait for ALL agents to complete before proceeding. Use `run_in_background: false` for all agents.

### Opportunity Score (Ranking Candidate Subfeatures)

When a Wave 1 "what to build" question surfaces multiple candidate subfeatures (rather than one clear scope), rank the candidates before recommending one. Score each candidate:

```
Opportunity Score = Importance × (1 − Satisfaction)
```

Both `Importance` and `Satisfaction` are estimated on a 0..1 scale from the Wave 1 research/Explore agent findings (market signal, existing-issue signal, repo-pattern signal) — not asked of the user directly. Rank candidates descending by score; the top-ranked candidate becomes the `(Recommended)` Option 1 in the AskUserQuestion payload for that question. Apply this only when genuinely multiple candidates are surfaced — a single well-defined feature needs no ranking.

### 3.2 Question Presentation

Synthesize research results into 5 questions per wave. Split across 2 AskUserQuestion calls (3+2 or 4+1) to stay within the 4-question-per-call limit. Note: in `feature` and `new` modes, Wave 1 may present 6 questions (split 3+3) when the optional User-Story toggle question is included; the 5-question / 3+2|4+1 default stands otherwise.

**Option format rules:**
- Option 1 is ALWAYS the recommendation, marked with `(Recommended)` in the label
- Each option includes a `description` with Pros/Cons drawn from the research
- Include an "Other" option when custom input makes sense
- Use `multiSelect: false` unless the question genuinely requires multiple selections

Example payload:

```
AskUserQuestion({ questions: [
  { question: "Which project archetype fits best?", header: "Archetype", options: [
    { label: "nextjs-saas (Recommended)", description: "Pro: Full SaaS stack with auth, payments. Con: Heavier initial setup." },
    { label: "express-service", description: "Pro: Lightweight API. Con: No frontend." },
    { label: "docker-service", description: "Pro: Maximum flexibility. Con: More manual setup." },
    { label: "Other", description: "Describe your preferred archetype." }
  ], multiSelect: false },
  { question: "Which visibility tier?", header: "Visibility", options: [
    { label: "internal (Recommended)", description: "Pro: GitLab private, team access. Con: No external visibility." },
    { label: "private", description: "Pro: + optional GitHub mirror. Con: Limited collaboration." },
    { label: "public/OSS", description: "Pro: Open source, GitHub public + license. Con: Requires careful secret management." }
  ], multiSelect: false },
  { question: "Who is the target audience?", header: "Audience", options: [
    { label: "Internal team (Recommended)", description: "Pro: Controlled rollout. Con: Limited feedback pool." },
    { label: "B2B customers", description: "Pro: Revenue potential. Con: Higher quality bar." },
    { label: "Public/developers", description: "Pro: Community contributions. Con: Support burden." },
    { label: "Other", description: "Describe your target audience." }
  ], multiSelect: false }
]})
```

### 3.3 Adaptive Depth

Each mode defines a starting wave count:
- `/plan new` — start with 3 waves minimum
- `/plan feature` — start with 1 wave minimum
- `/plan retro` — start with 1 wave minimum

Maximum across all modes: 5 waves.

After each wave, assess whether to continue:
- **Answers are clear and unambiguous** — all key decisions made, no open questions remain. Stop Q&A, proceed to Phase 4.
- **Answers reveal complexity** — multiple subsystems, unclear requirements, conflicting constraints, or new concerns surfaced. Add another wave with targeted follow-up questions.
- **User aborts early** — if the user says "Enough questions, generate the PRD" or similar, proceed directly to Phase 4 with the answers gathered so far.

### 3.4 Answer Tracking

Maintain a running summary of all answers across waves. After each wave, output a brief recap:

```
## Answers So Far (Wave N/M)
1. Archetype: nextjs-saas
2. Visibility: internal
3. Audience: B2B customers
4. ...
```

This ensures transparency and allows the user to correct any misunderstanding before the next wave.

## Phase 4: Document Generation

After Q&A completes, generate the output document.

### 4.1 Read Template

Select the template based on mode:
- `/plan new` — read `prd-full-template.md` in this skill directory (8-section full PRD)
- `/plan feature` — read `prd-feature-template.md` in this skill directory (5-section compact PRD)
- `/plan retro` — read `retro-template.md` in this skill directory (retrospective document)

### 4.2 Fill Template

Fill every template section with gathered answers. Use the research agent outputs to enrich sections beyond what the user explicitly stated — add technical details, risk analysis, and architecture sketches derived from the baseline and repo analysis.

Do NOT leave any section with TBD, placeholder, or empty content. If a section cannot be filled from gathered data, make a best-effort recommendation and mark it with `<!-- REVIEW: inferred from research, confirm with stakeholders -->`.

### 4.3 Save Document

Write the document to the configured location:
- PRDs → `{plan-prd-location}/YYYY-MM-DD-{project-or-feature-name}.md`
- Retros → `{plan-retro-location}/YYYY-MM-DD-retro.md`

Use today's date. Derive the name slug from the project name (for new) or feature name (for feature) — lowercase, hyphens, no special characters.

Ensure the target directory exists (create with `mkdir -p` if needed) before writing.

## Phase 3.5: Package Legitimacy Audit (Slopcheck — #520)

> Despite the name, this phase runs *after* Phase 4 (Document Generation) and *before* Phase 5 (PRD Review). The "3.5" identifier is historical, anchored to the PRD's Pattern-2 specification so cross-references stay searchable.

> Skip this phase if `slopcheck.enabled: false` in Session Config (default).

After the PRD is generated, scan the PRD body for package mentions and run
`classifyPackages()` from `scripts/lib/slopcheck.mjs` against them.

### Detection

Look for these patterns in the PRD body:
- npm: code-fenced blocks with `pnpm add`, `npm install`, `npm i`, or
  bare package names in `## Dependencies` / `## Affected Files` sections
- pip: `pip install`, `requirements.txt` references
- cargo: `cargo add`, `Cargo.toml` deps section

Extract package names + registry tuples: `[{name: 'react', registry: 'npm'}, ...]`.

### Dispatch

```javascript
import { classifyPackages } from '../../scripts/lib/slopcheck.mjs';
const results = await classifyPackages(detectedPackages);
```

### Handling per classification

- **LEGITIMATE**: no action, continue.
- **ASSUMED**: append "Package Legitimacy Audit" section to PRD body with the
  ASSUMED list. No user interaction required. Operator can review before close.
- **SUS**: AskUserQuestion: "Package <name> has audit warning: <evidence>.
  Continue anyway, replace, or remove?"
- **SLOP**: AskUserQuestion (BLOCKING): "Package <name> not found in <registry>
  registry. Possible LLM hallucination. Options: abort plan, correct name,
  mark as experimental in PRD body."

### Fail-Soft

If `classifyPackages` returns `{classification: 'ASSUMED', evidence: 'registry-timeout'}`
or `'cache-error'`, treat as ASSUMED + log to stderr. Never block plan
generation due to slopcheck failure — log + continue.

### Skip Conditions

- `slopcheck.enabled: false` in Session Config (default)
- PRD contains no package mentions
- `slopcheck.sources` does not include `plan` (e.g., set to `[discovery]` only)

## Phase 5: PRD Review (skip for retro mode)

### 5.1 Dispatch Reviewer

Dispatch a reviewer subagent: read `prd-reviewer-prompt.md` in this skill directory for review instructions. Pass the full PRD content to the reviewer.

The reviewer checks 7 criteria:
1. **Completeness** — all sections filled, no TBD or placeholder content
2. **Consistency** — no internal contradictions between sections
3. **Clarity** — unambiguous enough that a developer could implement from this document alone
4. **Scope** — focused on one project/feature, not sprawling across multiple subsystems
5. **YAGNI** — no unrequested features or gold-plating
6. **SMART metrics** — success criteria are Specific, Measurable, Achievable, Relevant, Time-bound
7. **User Stories** (gated — active only when a populated ## User Stories section is present) — section present, every story in one complete form (either the Als/möchte/damit persona form, or the job-story form: "When [situation], I want [motivation], so I can [outcome]"), each story links ≥1 acceptance criterion; SKIP when no User Stories section. No INVEST checks.

### 5.2 Revision Loop

If any criterion is FAIL:
1. Read the reviewer's feedback
2. Revise the affected PRD sections
3. Re-submit to the reviewer

Maximum 3 iterations. After 3 iterations with remaining issues, list the flagged points in plain text (they are context, not a choice), then ask via AskUserQuestion:

```
AskUserQuestion({
  questions: [{
    question: "The reviewer still flags [N] points after 3 revision rounds. Proceed anyway?",
    header: "PRD Review",
    options: [
      { label: "Accept as-is (Recommended)", description: "Three rounds did not close them, so a fourth probably will not. The flags then stay in the PRD and travel into the issues filed from it." },
      { label: "Manual edit", description: "You edit the PRD yourself; the flow waits, then re-runs the reviewer on your version." },
      { label: "Re-run review", description: "One more revision round. Cost: another reviewer pass, and the same points may come back unchanged." }
    ],
    multiSelect: false
  }]
})
```

### 5.3 User Review Gate

After the reviewer passes (or user accepts), present the final PRD in plain text — path plus a short section summary — then ask:

```
AskUserQuestion({
  questions: [{
    question: "Approve the PRD at [path]?",
    header: "PRD Approval",
    options: [
      { label: "Approve PRD (Recommended)", description: "Nothing further is checked after this: approval commits the PRD to HEAD (Phase 5.5), then issue creation starts." },
      { label: "Request changes", description: "Describe what to change; the PRD is rewritten and comes back here. No limit on rounds." }
    ],
    multiSelect: false
  }]
})
```

If user requests changes, apply them, save the updated document, and re-present for approval. No limit on user-requested revisions.

## Phase 5.5: PRD Commit Gate (all modes)

<HARD-GATE>
Do NOT proceed to Phase 6 (Issue Creation) until the generated document (PRD or retro) is committed to HEAD. There is no bypass. An issue referencing an uncommitted file is an unverifiable claim — see `.claude/rules/verification-before-completion.md` (VBC).
</HARD-GATE>

Two prior `/plan` sessions filed issues referencing a PRD path that no downstream session could find, because the document was written to disk (Phase 4.3) but never committed (issue #784). This gate closes that gap mechanically, right after user approval (Phase 5) and before any issue is filed (Phase 6). It applies to every mode that reaches Phase 6 — including `/plan retro`, which skips Phase 5's review loop but still saves a document and (conditionally) files issues.

### 5.5.1 Commit the Document

The Epic issue does not exist yet at this point in the flow — do NOT reference an issue number in the commit message. Use a session-dated message instead:

```bash
git add {plan-prd-location}/YYYY-MM-DD-{project-or-feature-name}.md   # or {plan-retro-location}/YYYY-MM-DD-retro.md
git commit -m "docs(prd): {project-or-feature-name} PRD (plan-session YYYY-MM-DD)"
```

For `/plan retro`, use `"docs(retro): YYYY-MM-DD retrospective (plan-session YYYY-MM-DD)"` — the retro document has no Epic wrapper by default.

### 5.5.2 Verify the Commit Landed

Both checks MUST pass before Phase 6 starts. Quote both outputs per VBC-001 — a bare claim of "committed" without this evidence is exactly the unverifiable-claim failure mode this gate exists to close:

```bash
git status --porcelain <doc-path>   # MUST be empty — no staged/unstaged diff remains on the doc
git ls-files <doc-path>             # MUST print the path — confirms it is tracked at HEAD
```

If either check fails, the commit did not land. Do not proceed to Phase 6 — diagnose (uncommitted hunk, wrong path, `.gitignore` collision) and retry § 5.5.1.

### 5.5.3 Push Timing (Not This Gate's Job)

This gate guarantees HEAD-presence, not remote-presence. Do not push here — push timing remains the session's normal `/close` responsibility. If the session pushes before `/close`, the PRD rides along; if not, `/close`'s commit+push flow carries it to the remote in the ordinary course.

### 5.5.4 Headless / Autopilot

The gate is a mechanical git step, not a judgment call — it applies unchanged in headless/autopilot mode. No `AskUserQuestion` is required here; run § 5.5.1 and § 5.5.2 exactly as above.

### 5.5.5 Epic Backlink (Phase 6 Followup)

The Epic issue's number is not known during § 5.5.1. Once Phase 6 creates it, see § 6.6 for the small follow-up commit that adds the Epic reference to the document.

## Phase 6: Issue Creation (all modes)

### 6.1 Derive Issue Structure

**If the PRD contains a populated `## User Stories` section** (story toggle was "yes"):
- Each user story becomes exactly one issue. The issue body carries the story text (`Als/möchte/damit`) plus its linked Gherkin/EARS acceptance criteria (the story's `↳ AC:` targets). Group under an Epic named after the feature/project.

**Otherwise** (no User Stories section — status quo), determine Epic and sub-issues based on mode:
- **`/plan new`** — derive from PRD Section 4 (Solution & Scope). Each major scope item becomes a sub-issue. Group under an Epic named after the project.
- **`/plan feature`** — derive from PRD Section 3 (Acceptance Criteria). Each Given/When/Then block becomes a sub-issue. Group under an Epic named after the feature.
- **`/plan retro`** — derive from the improvement actions in the reflection phase. Each action becomes an issue (no Epic wrapper unless 5+ actions).

### 6.2 Auto-Prioritize

Score each issue using three factors:

1. **Technical dependencies (highest weight):** Issues that other issues depend on get `priority::critical` or `priority::high`. Identify dependency chains: DB schema before API, API before frontend, shared libs before consumers, infrastructure before application.

2. **Business value (medium weight):** Issues the user marked as core MVP features in the PRD get `priority::high`. Nice-to-haves and polish items get `priority::medium` or `priority::low`.

3. **Risk (tiebreaker) — Impact × Risk 2×2 triage:** Classify each issue by Impact (high/low) and Risk (high/low) before applying the bump:
   - **High-Impact + Low-Risk → Implement.** Proceed directly; apply the one-level priority bump from the tiebreaker rule.
   - **High-Impact + High-Risk → Experiment.** De-risk with the smallest possible spike first (a time-boxed investigation issue) before scheduling the full-scope issue.
   - **Low-Impact + Low-Risk → Defer.** Push to backlog rather than scheduling in this PRD's issue set.
   - **Low-Impact + High-Risk → Reject.** Do not create an issue for this candidate; note the rejection rationale in the PRD's Risks & Dependencies section instead.

Assign labels from the standard taxonomy:
- `priority::critical` / `priority::high` / `priority::medium` / `priority::low`
- `type:feature` / `type:enhancement` / `type:bug` / `type:chore` / `type:discovery`
- `status:ready`
- `area:<inferred from content>` (e.g., `area:api`, `area:frontend`, `area:infra`)
- For `/plan new`: add `appetite:<1w|2w|6w>` and `mvp-phase` labels where applicable

### 6.3 User Review

Present the full issue structure via AskUserQuestion before creating anything. The table is the text that is about to be filed, so it belongs in `preview` — not in the question:

```
AskUserQuestion({
  questions: [{
    question: "Create these [N] issues from the PRD?",
    header: "Issues",
    options: [
      { label: "Create all [N] (Recommended)",
        description: "Priorities and blocked-by links come straight from the approved PRD. Cost: one API call per issue, ~1s apart.",
        preview: "**Epic:** [title]\n\n| # | Sub-Issue | Priority | Labels | Blocked By |\n|---|----------|----------|--------|------------|\n| 1 | [title]  | critical | [labels] | — |\n| 2 | [title]  | high     | [labels] | #1 |\n| ... | ... | ... | ... | ... |" },
      { label: "Adjust priorities", description: "Same [N] issues, different priority labels. Name them and this question comes back with the table updated." },
      { label: "Remove issues", description: "Name the ones to drop; the rest are created unchanged." },
      { label: "Cancel", description: "Nothing is created. The PRD stays committed, so Phase 6 can run again later." }
    ],
    multiSelect: false
  }]
})
```

If user selects "Adjust priorities" or "Remove issues", handle the adjustments interactively and re-present.

### 6.4 Create Issues

> **VCS Reference:** Detect the VCS platform per the "VCS Auto-Detection" section of the gitlab-ops skill. Use CLI commands per the "Common CLI Commands" section.

For each approved issue:

1. Create via VCS CLI using comma-separated labels in a single `--label` flag:
   - **GitLab**: `glab issue create --title "[Plan] <title>" --label "type:feature,priority::high,status:ready" --description "<body>"`
   - **GitHub**: `gh issue create --title "[Plan] <title>" --label "type:feature,priority::high,status:ready" --body "<body>"`
2. Brief pause (1s) between creations for rate limiting
3. After all issues are created, set dependency links:
   - **GitLab**: use `glab api` to set `blocks`/`is-blocked-by` relations. On HTTP 403 (non-Premium/Ultimate): `relates_to` + body-ordering-note fallback — see gitlab-ops SKILL.md § "Issue Linking (`blocks` / `is_blocked_by`)".
   - **GitHub**: note dependencies in issue body (GitHub lacks native blocking)

### 6.5 Final Report

```
## Plan Complete

### Document
- [PRD/Retro] saved to: [path]
- Review status: [approved / accepted with notes]

### Issues Created
| # | Title | Priority | Labels | Blocks |
|---|-------|----------|--------|--------|
| <IID> | <title> | <priority> | <labels> | <blocked issues> |

### Dependencies
[Dependency graph as text: #1 → #2 → #4, #1 → #3, #5 (independent)]

### Next Steps
- [Contextual recommendations based on mode]
```

For `/plan new`, next steps include: "Run `/session feature` in the new repo to begin implementation."
For `/plan feature`, next steps include: "Run `/session feature` to implement this PRD."
For `/plan retro`, next steps include: "Address improvement issues in your next session."

### 6.6 Epic Backlink Commit (PRD Update)

Once § 6.4 creates the Epic issue, its IID is known. Update the document to reference it, then commit as a **separate, small follow-up commit** — never amend the § 5.5.1 commit (amending risks clobbering a commit the session may already have pushed, or that a sibling session has based work on; see `parallel-sessions.md` PSA-003/PSA-004).

1. Add or update a status line near the top of the document body (e.g. next to `**Status:**`) with `**Epic:** #<IID>`.
2. Save the document to the same path used in § 4.3 / § 5.5.1.
3. Commit:
   ```bash
   git add <doc-path>
   git commit -m "docs(prd): link {project-or-feature-name} PRD to Epic #<IID>"
   ```

Skip this step if issue creation was cancelled at § 6.3 ("Cancel") — there is no Epic number to backlink. For `/plan retro` without an Epic wrapper (fewer than 5 improvement actions — see § 6.1), skip this step as well.

## Critical Rules

- **NEVER skip the Q&A phase** — even if the user provides a detailed brief, validate through structured questions. The Q&A surfaces blind spots.
- **NEVER assume projects-baseline templates** — always read from the configured `plan-baseline-path`. Templates change; hardcoded assumptions break.
- **ALWAYS research before asking** — dispatch Explore agents before every Q&A wave. Questions without research backing are guesses.
- **ALWAYS mark Option 1 as recommended** — with `(Recommended)` in the label. Every question must have a clear recommendation.
- **ALWAYS use AskUserQuestion** — never present options as plain text. The structured UI is mandatory.
- **ALWAYS save documents before creating issues** — the PRD/retro document is the source of truth. Issues reference it.
- **ALWAYS commit the PRD before creating issues** — see Phase 5.5 (HARD-GATE). A saved-but-uncommitted document is unverifiable by any downstream session; commit to HEAD is the trust boundary, not disk-write.
- **Security** — never include internal paths, IPs, or infrastructure details in output documents. Read sensitive baseline areas for context but filter from outputs.
- **Idempotency** — if the user re-runs `/plan` with the same mode, check for an existing PRD at the target location. If found, use AskUserQuestion to offer: "Update existing PRD" vs. "Create new version" vs. "Cancel".

## Sub-File Reference

This skill uses 8 sub-files in the same directory:

| File | Purpose |
|------|---------|
| `soul.md` | Product Strategist identity — read first, defines communication style and values |
| `mode-new.md` | Project kickoff mode: 3-wave requirement gathering, repo scaffolding, full PRD |
| `mode-feature.md` | Feature PRD mode: 1-2 wave discovery, compact PRD, acceptance criteria |
| `mode-retro.md` | Retrospective mode: metrics analysis, reflection waves, improvement actions |
| `prd-full-template.md` | 8-section PRD template for `/plan new` |
| `prd-feature-template.md` | 5-section compact PRD template for `/plan feature` |
| `retro-template.md` | Retrospective document template for `/plan retro` |
| `prd-reviewer-prompt.md` | PRD quality review instructions for the reviewer subagent |