--- name: ship-discuss description: "Discover features from idea to full spec." allowed-tools: [Read, Write, Edit, Grep, Glob, LSP, Agent, AskUserQuestion, WebSearch, WebFetch, "Bash(shipyard-context:*)"] effort: high argument-hint: "[topic | feature ID | issue key | --idea ]" --- # Shipyard: Feature Discussion You are facilitating a feature discovery conversation. This is fluid — not a questionnaire. ## Context !`shipyard-context path` !`shipyard-context view config` !`shipyard-context view codebase` !`shipyard-context list epics` !`shipyard-context list features` **Paths.** All file ops use the absolute SHIPYARD_DATA prefix from the context block. No `~`, `$HOME`, or shell variables in `file_path`. No bash command substitution for shipyard-data or shipyard-context — use Read / Grep / Glob. **Never use `echo`/`printf`/shell redirects to write state files** — use the Write tool (auto-approved for SHIPYARD_DATA). ## Input $ARGUMENTS ## Session Mutex Check **Absolute first action — before reading any context, before mode detection, before anything.** Use the Read tool on `/.active-session.json` (substitute the literal SHIPYARD_DATA path from the context block above). Then decide: - **File does not exist** → no other planning session is active. Proceed to "Session Guard" below. - **File exists.** Parse the JSON and check three fields: 1. If `cleared` is set OR `skill` is `null` → previous session ended cleanly (soft-delete sentinel). Proceed. 2. If `started` timestamp is more than 2 hours old → stale lock (probably a crashed session). Print one line to the user: "(recovered stale lock from `/{previous skill}` started {N}h ago)". Proceed. 3. Otherwise → **HARD BLOCK.** Another planning session is active. Print this message as the entire response and STOP — do not continue with any other instructions, do not load any context, do not call any other tools: ``` ⛔ Another planning session is active. Skill: /{skill from file} Topic: {topic from file} Started: {started from file} Concurrent planning sessions can corrupt the spec and lose research notes. Finish or pause the active session first. If the other session crashed or was closed: Run /ship-status — it will offer to clear the stale lock. ``` This is a Read+Write mutex. There is a small theoretical race window between the Read and the Write below, but in practice two human-typed `/ship-discuss` invocations cannot collide within milliseconds. ## Session Guard **Second action — only if the mutex check above said proceed:** Use the Write tool to write `.active-session.json` to the SHIPYARD_DATA directory (use the full literal path from the context block — e.g., `/Users/x/.claude/plugins/data/shipyard/projects/abc123/.active-session.json`). This both claims the mutex (overwriting any stale or cleared marker) AND prevents post-compaction implementation drift: ```json { "skill": "ship-discuss", "topic": "[user's topic or feature ID from $ARGUMENTS]", "started": "[ISO date]" } ``` This file is the active-skill mutex (see the `acquiring-skill-lock` capability skill for semantics). Any other Shipyard skill entering will see the held lock and refuse. The mutex is advisory — no hook physically blocks tool calls — so the discipline is yours: if you find yourself wanting to write implementation code, STOP. Discussion is for shaping the spec, not building the thing. ## Detect Mode Auto-route ONLY on unambiguous inputs. Heuristic classifications must be confirmed with the user before proceeding — wrong-mode-by-default is a high-impact failure (CAPTURE mode demotes a meaty idea to a stub without acceptance criteria; NEW mode interrogates a brainstorm the user wanted to stash). See the per-input rules below. **Unambiguous (auto-route, no confirmation needed):** - If input starts with `--idea ` → **IDEA-CAPTURE mode** (see below). Strip the `--idea` prefix; the rest is the idea description. This is a fast-path: capture immediately, no depth offer, no ceremony. Example: `/ship-discuss --idea webhook retry with exponential backoff`. - If input is an **epic ID** (E001) → **EPIC mode** (refine epic scope, cascade changes to features) - If input is an **idea ID** (IDEA-NNN) → **IDEA mode** (convert idea to feature — see below) - If input is a **feature ID** (F001) → **REFINE mode** (load existing, gather updates) - If input matches an **external issue key** pattern (`[A-Z]+-\d+` but NOT a Shipyard ID like F001/E001/T001/IDEA-NNN) → **EXTERNAL mode**. Fetch context from the user's session MCP tools and seed a NEW mode discussion. See `references/external-issue-fetch.md` for the full protocol. Examples: `JIRA-123`, `SYS-456`, `ENG-789`. - If input is a **triage phrase** — exact phrase match against: "anything requires discussion", "anything requires discussion?", "what's open", "what needs discussion", "what needs attention", "what's pending", "what needs refinement", "anything else", "discuss anything", "what else", "any ideas", "any ideas to discuss", "what ideas" → **TRIAGE mode** (see below) - If no input → AskUserQuestion: "What would you like to discuss?" **Heuristic-classified (REQUIRES confirmation before routing):** Any input that does not match the unambiguous list above MUST be confirmed with the user even if the heuristic strongly suggests a mode. Compose a one-line summary of the input, the inferred mode, and the mode's outcome, and use `AskUserQuestion` to confirm. Default-recommend the inferred mode but always offer the cheaper-to-recover-from neighbor: - **Short one-liner heuristic** (under ~20 words, no questions, no detail) → inferred CAPTURE mode. Ask: "This looks like a quick capture — file as IDEA-NNN (zero ceremony) or open a full feature discussion?" Default: CAPTURE. - **Large-initiative heuristic** (multiple features implied, a whole product area) → inferred EPIC mode. Ask: "This sounds like an epic — multiple features under one initiative. Discuss as an epic, or start with the first feature? (epic / feature)". Default: epic. - **Detailed-topic heuristic** (the user is describing a single feature in more than a few words OR asking questions about a single behavior) → inferred NEW mode. Ask: "Open a full discussion (~6 phases, produces a spec) or stash as an IDEA for later?" Default: NEW. The confirmation step is two sentences max — do not turn it into a full Phase 1 question. Its only purpose is to catch wrong-mode-by-default before the skill commits to a flow that's hard to back out of (CAPTURE writes an IDEA file; NEW writes a feature; EPIC cascades changes). After confirmation, route to the chosen mode. ### TRIAGE Mode: Surface what needs discussion When the user asks "anything requires discussion" or similar: 1. Use Grep with `pattern: ^status: proposed`, `path: /spec/features`, `glob: F*.md`, `output_mode: files_with_matches` to find features still at `status: proposed`. For each match, Read the file and extract `id`, `title`, `story_points`, and acceptance criteria count. 2. Use Glob `/spec/ideas/IDEA-*.md` to enumerate idea files. For each, Read the file, parse frontmatter, and skip any with `status: graduated` or `status: rejected`. 3. Present the result as a compact triage list: ``` Items needing discussion: PROPOSED FEATURES (refine acceptance criteria, estimate, decide): [1] F012 — Payment Analytics (proposed, 0 pts, 0 scenarios) [2] F015 — Split Payments (proposed, 8 pts, 2 scenarios) IDEAS (capture-only — flesh out into features): [3] IDEA-007 — Magic-link auth (captured 2026-03-12) [4] IDEA-009 — Bulk export to CSV (captured 2026-03-21) ``` 4. AskUserQuestion: "Pick a number to discuss, or type 'all proposed' to walk through every proposed feature, or 'done' to exit triage." 5. On selection, jump into the appropriate mode (REFINE for a feature, IDEA for an idea). Do not run any bash commands and do not improvise pipelines — every list item came from native Read/Grep/Glob calls above. If both lists are empty: "Nothing currently needs discussion. The proposed-feature queue is empty and there are no captured ideas. Run /ship-discuss with a topic to start something new." --- ### IDEA-CAPTURE Mode: Instant Idea Stash (`--idea`) When the input starts with `--idea`, this is the fastest possible capture path. No conversation, no depth offer, no questions. Stash and exit. 1. Strip the `--idea` prefix from the input. The remaining text is the idea description. 2. Generate the next available IDEA-NNN ID (same allocation logic as CAPTURE mode). 3. Derive a slug from the description (lowercase, hyphens, max 40 chars). 4. Write `/spec/ideas/IDEA-NNN-[slug].md`: ```yaml --- id: IDEA-NNN title: "[cleaned up title from description]" type: idea status: proposed source: "inline capture (--idea)" captured: [today's date] --- # [Title] ## Idea [User's description text, lightly cleaned up] ## Why It Might Matter [One sentence — best guess at value] ``` 5. Output exactly: ``` Captured: IDEA-NNN — [title] Flesh out later with: /ship-discuss IDEA-NNN ``` 6. Release the session mutex (Write `.active-session.json` with `{"skill": null, "cleared": ""}`). Done. No follow-up question, no Phase 1, no depth offer. **Rules for IDEA-CAPTURE mode:** - Be instant. The user typed `--idea` because they want zero friction. - No `AskUserQuestion`. No clarifying questions. No RICE. No estimates. - No `Why It Might Matter` if nothing is obvious — leave the section with a single dash. - No `Initial Thoughts` section (unlike CAPTURE mode). Keep it minimal. --- ### Compaction Recovery If you lose context mid-discussion (e.g., after auto-compaction): 1. Use the Read tool on `/spec/.research-draft.md`. If it exists, parse its frontmatter — if `obsolete: true` is set, treat it as absent (skip to step 2). Otherwise: - If found and `topic:` matches → research and challenge phases completed. Read it for findings. Resume from Phase 2 (Viability Gate) - If found but its `topic:` doesn't match the current discussion topic → topic-mismatch fork. The user just typed `/ship-discuss [new topic]`, but stale research exists for `[old topic]`. The default behavior MUST favor the user's most recent intent (the new topic) — abandoning a fresh request to resume stale research is the wrong-by-default semantics that surfaced as HIGH-risk in the v2.4.0 audit (user picks "keep" thinking it means "keep my new topic", silently discards the new request). Use `AskUserQuestion` with options labeled by the topic they refer to, NOT by abstract verbs like "keep" or "discard": - **"Continue with the new topic '[new topic]' (recommended)"** → use Edit to set `obsolete: true` in the draft's frontmatter (preserving the old research as a soft-deleted record), proceed fresh into Phase 1.5 (Research) for the current topic. This is the default and should be presented first. - **"Resume the old discussion on '[old topic]' instead"** → switch to the old topic. Read `topic:` from `.research-draft.md`, load its research findings, and resume from Phase 2 (Viability Gate) for that topic. Inform the user: "Resuming discussion on [old topic]. To discuss [new topic], run /ship-discuss [new topic] in a new session." Only choose this if the user explicitly picks it — never default to it. - **"Resume the old topic AND archive the old research before starting the new one"** (when the user wants both) → first finalize the old discussion to Phase 6 in a quick wrap-up pass, then start fresh on the new topic. Never present this as a generic "keep / discard" pair without naming which topic each refers to — that's the exact source of the v2.4.0 wrong-by-default report. Both topic strings must appear in the option labels. 2. Check for feature file matching the topic: use Glob `/spec/features/F*-*.md` to enumerate, then Read each and match by title against the current topic. - If found with empty acceptance criteria → Phase 3 incomplete, resume Phase 3 - If found with acceptance criteria and `status: proposed` → Phase 3 done, resume from Phase 3.5 (Impact Analysis) - If found with `status: approved` but `.active-session.json` still has `skill: ship-discuss` (not cleared) → Phase 6 (Finalize) was interrupted mid-sequence. Read BACKLOG.md: if the feature ID is already listed, resume from Phase 6 step 3 (idea archival) or step 4 (Next Up) depending on whether an idea file still has `status: proposed`. If the feature ID is missing from BACKLOG.md, resume from Phase 6 step 2 (append to BACKLOG.md). Either way, the final mutex-release write still runs last. 3. If neither file exists → pre-research phases only (interactive). AskUserQuestion: "A previous discussion session was interrupted before research completed. Can you summarize what was decided so far?" Resume from Phase 1.5 (Research) Research findings are the most expensive state to lose (WebSearch/WebFetch results). The research draft file preserves them. --- ## CAPTURE Mode: Quick Idea (zero ceremony) When the input is a short one-liner — capture it instantly and offer to go deeper. ### Step C1: Create Idea File Generate the next available IDEA-NNN ID. Write to `/spec/ideas/IDEA-NNN-[slug].md`: ```yaml --- id: IDEA-NNN title: "[title from user's description]" type: idea status: proposed source: "inline capture" captured: [today's date] --- # [Title] ## Idea [User's description, cleaned up slightly but preserving intent] ## Why It Might Matter [One sentence — your best guess at the value. Keep it brief.] ## Initial Thoughts [Any immediate technical considerations. One or two bullets max. Skip if nothing obvious.] ``` ### Step C2: Offer Depth ``` Captured: IDEA-NNN — [title] Want to flesh this out into a full feature now, or save it for later? ``` - **"now" / "yes" / user engages** → switch to IDEA mode (Step I1 below) with the just-created IDEA-NNN - **"later" / "no" / silence** → done. Clean up active-skill mutex and exit. **Rules for CAPTURE mode:** - Be fast. Don't ask clarifying questions upfront. - Don't estimate. No RICE, no story points. - Slug from title — lowercase, hyphens, max 40 chars. - If called mid-conversation or mid-sprint, capture and return immediately. --- ## EPIC Mode: Discuss at Epic Level When the input is an epic ID (E001) or the user describes a large initiative. **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/epic-mode.md` Seven steps in sequence: **EP1 Load Epic Context** (Glob the epic file, Grep features by `^epic: E00N`, present a summary block of features + points + scenarios); **EP2 Epic-Level Discussion** (AskUserQuestion about scope, new/removed features, business context shifts, cross-feature concerns); **EP3 Cascade Changes to Features** (propagate scope changes, new dependencies, priority shifts, acceptance criteria changes, additions/removals/invalidations to each affected feature file — full change-type table in reference; flag sprint-active features before mutating them); **EP4 Create New Features** (run NEW mode Phase 1→5 inline with epic pre-assigned, bundle related features so dependencies are clear); **EP5 Quality Gate** (5 checks: all features have acceptance criteria, no orphan features, consistent dependencies, no duplicates, coherent epic scope); **EP6 Wrap Up** (present changed-state summary, AskUserQuestion: "Approve these changes? (yes / adjust / revert all)"); **EP7 Integration AC** (cross-feature seam-level E2E criteria — see `references/epic-integration-ac.md`). --- ## IDEA Mode: Convert Idea to Feature When the input is an idea ID (IDEA-NNN), the goal is to graduate it into a proper feature. This is NEW mode with the idea pre-loaded as seed context — not REFINE mode. ### Step I1: Load Idea Read `/spec/ideas/IDEA-NNN-[slug].md`. Extract: - Title and description - "Why It Might Matter" section - Any initial thoughts Present it briefly to the user as plain text: ``` Idea: IDEA-NNN — [title] [description] [why it might matter] ``` ### Step I2: Seed NEW Mode Pass the idea content as context into the full NEW mode flow (Phases 1 → 6), starting at Phase 1. The idea's description pre-answers some of Phase 1's questions — skip what's already clear, focus AskUserQuestion on genuine unknowns. Run all phases in sequence: Phase 1 (Understand) → Phase 1.5 (Research) → Phase 1.5b (Challenge & Surface) → Phase 2 (Viability Gate) → Phase 3 (Write to Spec as FNNN) → **Phase 3.5 (Impact Analysis)** → **Phase 3.7 (E2E AC Validation)** → **Phase 3.8 (Simplification Scan)** → Phase 4 (Capture tangential ideas) → Phase 4.5 (Backlog Re-evaluation) → Phase 4.9 (Quality Gate) → Phase 4.95 (Adversarial Critique) → **Phase 4.97 (Scope-Drift Check)** → Phase 5 (Spec Approval Gate) → Phase 6 (Finalize). Impact Analysis (Phase 3.5) runs as normal — it scans existing features for dependencies, overlaps, conflicts, and invalidations caused by the new feature, and uses AskUserQuestion to confirm what to apply. ### Step I3: Mark the Idea as Graduated Idea archival happens inside Phase 6 (Finalize), between the BACKLOG.md append and the mutex release — not here and not as a standalone step. See `references/phase-finalize.md` for the graduation target path and exact ordering. --- ## NEW Mode: Discover Features ### Phase 1: Understand **Read the discovery techniques:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/discovery-techniques.md` — contains JTBD, user journey mapping, pre-mortem, ISO 25010 quality characteristics, ATAM tradeoff analysis, EARS syntax, and IEEE 830 completeness checks. Apply these throughout Phases 1-3. **Communication design:** When surfacing something the user hasn't considered, use the 3-layer pattern from `references/communication-design.md` — one-liner (what + recommendation), context (why it matters, tradeoff, analogy if helpful), detail (only for high-stakes). Max 3–4 new concepts and 2–3 options per question. Under 100 words per decision message. Name the tradeoff on each option. Always recommend a default. Have a natural conversation about the topic. **Always use AskUserQuestion — never plain text — to ask questions.** AskUserQuestion suspends execution and waits for input; plain text does not. Bundle related questions into a single call. Key topics to cover (combine where natural): - Who are the users? What roles/permissions? - What's the core behavior? What should happen? - What's the business value? Why does this matter? - Any constraints, compliance, or technical requirements? - **JTBD**: What job is the user hiring this feature for? What are they doing today without it? What functional/emotional/social dimensions? What adjacent jobs happen before/after? - **Journey**: What triggers usage? What's the full before/during/after flow? Where can they abandon? **Key behaviors during conversation:** - **Splitting:** If the user describes multiple distinct features, use AskUserQuestion: "I'm hearing two things: [X] and [Y]. Want to capture them separately?" - **Branching:** If something tangential comes up, capture it as an idea inline and state it as plain text: "That's a good point — I'll capture that as IDEA-NNN. Let's stay focused on [current topic]." (This is a statement, not a question — no AskUserQuestion needed.) - **Referencing:** If it relates to an existing feature, use AskUserQuestion: "This connects to F003 — should we extend that or keep this separate?" - **Parking:** If user says "not now" about something, record it in the decision log as deferred with their reasoning. ### Phase 1.5: Research **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/phase-1-research.md` Once you understand what the user wants, research before challenging. **Use LSP first** for code navigation; fall back to Grep/Read silently. Walk in order: (1) **Constitution check** — Glob `.claude/rules/project-*.md` and `.claude/rules/learnings/*.md`; flag both **tensions** (feature violates a rule → Phase 1.5b challenge) AND **gaps** (feature enters territory no rule covers → log to `.research-draft.md` `## Constitution Gaps` so Phase 1.5b resolves the gray area and Phase 6 offers to codify it as a new rule); (2) **Internal research** — Glob `/spec/features/F*.md` and read `codebase-context.md`; (3) **How others solve it** — WebSearch established products, common user complaints, security pitfalls; WebFetch official docs; (4) **Architecture visualization** — generate diagrams gated on architectural *significance*, not participation. Seven types, each with its own trigger: **C4** (new boundary/service/component — Component level is the one monoliths need), **sequence** (2+ components with async/error-recovery, not raw count), **state machine** (≥3-state or branching lifecycle/UI graph), **ER** (2+ related entities), **deployment** (new runtime unit or trust boundary), **data-flow** (data crossing a trust boundary), and **user-journey** (multi-step before→during→after). Skip when the feature reuses existing structure with no new boundary, entity, runtime, or non-trivial state graph. Mandatory when a trigger fires — not optional polish. See `references/phase-1-research.md` Step 4 for the per-diagram triggers and the significance skip criteria. **(5) Data‑modeling guidance (gated)** — when the feature persists data (the ER/data‑model trigger fired, or it has a `## Data Model` concern), Read and apply `${CLAUDE_PLUGIN_ROOT}/project-files/references/data-modeling-guide.md` (normalization, keys, right‑sizing, schema anti‑patterns); skip for features with no persistence concern. Write findings to the feature file `## Technical Notes` (after Phase 3 creates it) with HIGH/MEDIUM/LOW confidence labels. Be prescriptive: "Use X" not "Consider X or Y" — the builder needs decisions. Fold findings into the conversation naturally before challenging. Phase 3 persists diagrams from Step 4 to the `## Flows` section as Mermaid. ### Phase 1.5b: Challenge & Surface **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/phase-1-5b-challenge.md` Once you have a reasonable understanding of the feature, **proactively challenge it** before moving to spec. Invoke the **`shipyard:discovering-edge-cases` capability skill** to walk the seven discovery categories (boundary inputs, concurrency, failure modes, adversarial input, observability gaps, NFRs, domain-specific) and return structured findings. Pass `feature_text`, `parent_context`, `domain_hints`, and `data_dir`. The capability skill returns a structured list (~3-5k tokens). Also run a quick pre-mortem inline (from `discovery-techniques.md`). **Presentation:** Follow `references/communication-design.md`. Max 3–4 items per AskUserQuestion; batch into themed groups of 3 if more. For each item: what I found → why it matters → what I recommend. Use the 3-layer pattern for anything genuinely surprising. Compact visual summary before the AskUserQuestion: ``` ⚠️ [Finding] → [impact], recommend [action] ⚠️ [Finding] → [impact], recommend [action] ✅ [Finding] → [status — no action needed] ❓ [Finding] → needs decision ``` **Do not proceed to Phase 2 until grey areas are resolved or explicitly deferred.** Write research findings and challenge resolutions to `/spec/.research-draft.md` (frontmatter `topic:` + `created:`; body sections `## Research Findings` and `## Challenge Resolutions`). This file is absorbed into the feature file's Technical Notes in Phase 3 and then deleted. ### Phase 2: Viability Gate Before writing to spec, evaluate each feature against the 5 gates AND echo the verdicts to the user. The historical "silently evaluate" pattern hid model misjudgments — USER VALUE, SCOPED, and TESTABLE are judgment calls the user has standing on, and silent-pass leaves no feedback channel when the model reads the feature wrong. **The gates:** 1. **USER VALUE** — Can we articulate who wants this and why? → KILL if no clear user story 2. **DEFINABLE** — Can we write testable acceptance criteria (Given/When/Then)? → KILL if too vague 3. **BUILDABLE** — Can we decompose into executable tasks? → KILL if impossible constraints 4. **TESTABLE** — Can we verify with automated tests + demo? → KILL if purely subjective 5. **SCOPED** — Is it one feature, not three in a trench coat? → SPLIT if multiple stories **Verdict echo (MANDATORY — even on PASS).** After running the gates, surface the verdicts in a compact block before continuing: ``` Viability read: USER VALUE ✓ [one-line summary of who + why, as the model read it] DEFINABLE ✓ [acceptance theme — what the criteria will test] BUILDABLE ✓ [task-decomposition shape — small/medium/large] TESTABLE ✓ [verification approach — auto-test + demo path] SCOPED ✓ [N feature(s) — if N>1, list the split] ``` Then `AskUserQuestion`: "I'm reading this as one feature, scoped to [scope], with these acceptance themes: [themes]. Does this match your intent? (looks right / refine the read / split into multiple features)". Default-recommend "looks right" only when all five gates pass cleanly. If the user picks "refine the read" or "split into multiple features", go back to Phase 1 for re-clarification before writing to spec. Do NOT skip this echo step — the v2.4.0 audit flagged silent-pass as a HIGH-risk gap because users have no way to catch a model misjudgment about USER VALUE / TESTABLE / SCOPED otherwise. When SPLIT fires (or BUILDABLE/SCOPED fails on size grounds), invoke the **`shipyard:splitting-stories` capability skill** with `level: feature`, the draft text, the AC list, and `domain_hints` inferred from the discussion. The skill returns split candidates with cited patterns and `acceptance_hint`s. Present them as an AskUserQuestion: "This looks like [N] stories, not one — split it? (split as suggested / pick which children to keep / capture as-is and refine later)". Reject any candidate that fails the skill's horizontal-slice check before presenting (the skill flags these in `horizontal_rejections` — re-prompt the skill if it returned any). If viability kills the feature, use the Edit tool to set `obsolete: true` in `/spec/.research-draft.md`'s frontmatter (soft-delete sentinel — recovery logic filters it out; it stays as a soft-deleted record). If a feature fails a gate, AskUserQuestion — don't block. Frame positively: "This feature needs X to be buildable" not "This feature fails because X is missing." Example: "I can't write testable acceptance criteria for this yet — the scope is too broad. Can we narrow it to something specific? (narrow it / capture as-is and refine later)" The user can override: "Just capture it as proposed, we'll refine later." ### Phase 3: Write to Spec **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/phase-3-write-spec.md` For each well-defined feature: generate the next FNNN ID, determine the epic (existing, new, or empty — see reference for the decision tree), and write `/spec/features/FNNN-[slug].md` with full required frontmatter (id, title, type, epic, status, story_points, complexity, token_estimate, all RICE fields, feasibility, dependencies, references, external_refs, children, tasks, created, updated). **External linking:** If the user mentioned an external issue key during discussion (e.g., "this is JIRA-123" or "relates to GH-456"), add it to `external_refs` in the feature frontmatter. Don't ask — if they said it, link it. Body sections: user story, Why This Matters, **acceptance criteria in Given/When/Then format** (happy path + at least one edge case), optional Interface / Data Model / Configuration / Flows / Error Handling sections (include only if discussed), Technical Notes (absorbed from `.research-draft.md`), Decision Log. **Hard limit: 200 lines per file** — split into sub-features (F001a/b) or extract to `/spec/references/FNNN-.md` if larger. Fill every RICE field; compute `rice_score = (reach × impact × confidence) / effort`. Mark `.research-draft.md` `obsolete: true` only after Phase 3 finishes (it is the recovery checkpoint until then). **Diagram persistence:** Every diagram shown during Phase 1.5 — C4, sequence, state machine, ER, deployment, data-flow, or user-journey — is converted to Mermaid and written to the feature's `## Flows` section (an ER diagram may live under `## Data Model` instead when the schema is the feature's primary artifact). Diagrams shown in conversation are ephemeral — this is the only chance to persist them. The canonical diagram-type → Mermaid-syntax mapping is the single source of truth in `references/phase-3-write-spec.md`; keep this list in lock-step with it. See that reference for format rules. ### Phase 3.5: Impact Analysis **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/impact-analysis.md` **Presentation:** Keep impact summaries under 200 words. Bold the single most important finding. Use the 3-layer pattern for any impact that changes existing behavior. Show an impact diagram for features with multiple ripple effects: ``` F007 (new) ──impacts──▶ F003 (criteria change) ──depends──▶ F001 (must be done first) ──overlaps─▶ F005 (shared data model) ``` **Persist it (≥2 ripple edges):** the inline ASCII is ephemeral. When the impact diagram has 2+ ripple edges, convert it to a Mermaid `graph LR` and write it into the new/refined feature's `## Decision Log` so the ripple map survives the session — see `references/impact-analysis.md` § "What Gets Changed on Approval". A single dependency edge stays a sentence (per `references/communication-design.md` "fewer than 3 data points"). Skip if Glob `/spec/features/F*.md` returns no results. ### Phase 3.7: E2E AC Validation **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/phase-e2e-validation.md` After impact analysis, validate the feature's acceptance criteria against the E2E taxonomy. Invoke `shipyard:validating-e2e-coverage` with the feature file path, existing AC, and domain hints. The skill detects touch surfaces from the spec content, maps to the E2E taxonomy, and returns coverage gaps with draft scenarios. **Skip if:** feature is trivial (`story_points <= 2` AND `complexity == "low"`) or no touch surfaces detected. Present gaps via AskUserQuestion in groups of ≤4. For accepted gaps, write to the feature file under `### E2E AC` within `## Acceptance Criteria`. If adding E2E AC would push the file over 200 lines, extract to `/spec/references/FNNN-e2e-ac.md`. ### Phase 3.8: Simplification Opportunity Scan **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/simplification-scan.md` Scan the codebase for places that hand-roll what this feature's new libraries, utilities, or patterns provide. The scan detects five types of opportunities: new dependency replacements, new utility reuse, pattern consolidation, abstraction adoption, and dead code from supersession. **Skip if:** the feature is purely additive (new endpoint, new UI page) with no reusable infrastructure — nothing introduced that other code could benefit from. **At discuss time**, the scan operates on the feature's Technical Notes and research findings (not implementation code, which doesn't exist yet). Focus on: - Libraries referenced in Technical Notes → grep for hand-rolled equivalents - Patterns decided in the Decision Log → grep for ad-hoc variations - Shared utilities mentioned in research → grep for inline duplicates **Routing at discuss time:** All findings become IDEA files (since there's no sprint to fold tasks into yet). The sprint planning step (Step 3.75) will re-evaluate these and promote trivial/small items into sprint tasks if the feature is selected. Present findings and AskUserQuestion as defined in the protocol. If no opportunities found, move on silently. ### Phase 4: Capture Tangential Ideas Any tangential features mentioned → create as idea files via the same logic as CAPTURE mode above. ### Phase 4.5: Backlog Re-evaluation **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/backlog-reeval.md` !`shipyard-context reference ship-discuss backlog-reeval 55` Skip if BACKLOG.md is empty or doesn't exist. ### Phase 4.9: Quality Gate (self-review loop) **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/phase-quality-and-critique.md` Before presenting to the user, re-read each feature file and run the 15-check quality gate (Given/When/Then formatting, happy + edge cases, no ambiguous words, no TBDs, RICE populated, dependencies identified, prescriptive research, NFRs, EARS syntax, all states covered, etc. — full table in the reference). Iterate fixes up to 3 passes; emit only per-iteration deltas, not the whole table on each pass. Flag remaining gaps as "Unresolved — needs follow-up in /ship-discuss [ID]", then proceed to Phase 4.95. ### Phase 4.95: Adversarial Critique **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/phase-quality-and-critique.md` After the quality gate passes, spawn a `general-purpose` critic subagent (inline prompt in the reference — kept inline per S-1 granularity) to challenge the spec from angles self-review misses: implicit assumptions, feasibility risks, ambiguities, missing error states. Determine stakes level: `high` if feature is part of an epic, story_points ≥ 8, touches auth/payments/data, or has 6+ acceptance scenarios; `standard` otherwise. Process the critic's findings: fix what's fixable without user input, batch judgment calls into a single AskUserQuestion with the critic's evidence and your recommendation, log CONCERN items in the Decision Log, make silent assumptions explicit in the spec. **Do NOT re-run the critic after fixes.** One round only. ### Phase 4.97: Scope-Drift Check ("did we drop something?") Before assembling the Phase 5 approval summary, run an explicit drift check with the user. The discussion entered Phase 1 with one shape (the user's initial topic, idea, or feature request) and may have evolved through challenge, viability, impact, and critique — sometimes losing scope on the way. Up to this point in the skill, there is no checkpoint that asks the user whether the spec they're about to approve still covers everything they originally wanted. Phase 4 captures NEW tangents that come up; this phase asks about OLD intent that may have been dropped. Run this check exactly once per discussion, regardless of mode (NEW, IDEA-graduated-to-NEW, REFINE). Skip only on CAPTURE mode (which doesn't write acceptance criteria at all). Compose a two-column diff in plain text: ``` Started with: Landed at: "[paraphrase of user's initial F012 — [title] topic from Phase 1 / the • [scenario 1 one-liner] IDEA file / the REFINE prompt]" • [scenario 2 one-liner] • [scenario 3 one-liner] (RICE [score], [complexity]) IDEA-007 — [title of tangent captured during Phase 4] IDEA-009 — [title of tangent captured during Phase 4] ``` Then `AskUserQuestion`: "We started with [paraphrase] and landed at the spec above. Did anything important from the original idea NOT make it into the spec? (nothing dropped — proceed to approval / something is missing — let me add it / a piece I wanted got captured as an IDEA instead — promote it)". Default-recommend "nothing dropped" only if the spec's acceptance themes cover every noun/verb in the user's initial topic (paraphrase from Phase 1's first AskUserQuestion). If the user picks "something is missing", re-enter Phase 1 with the dropped concern as the new seed, and re-run Phases 1.5b → 2 → 3 to incorporate it. If the user picks "promote an IDEA", inline-merge the IDEA's content back into the feature spec (or split it into a sibling feature), then return to this phase for re-confirmation. This phase has zero existing coverage anywhere else in the skill — until v2.4.0, there was no point where the user was asked "what did we cut?" Scope creep prevention was implicit in the model's judgment, which means it was silent and unrecoverable. The audit flagged this as a HIGH-risk gap. ### Phase 5: Spec Approval Gate (NOT an Implementation Plan) Feature files are already written with `status: proposed`. This is a spec approval summary — implementation belongs to `/ship-execute` after `/ship-sprint` plans the work. It is never this skill's job. **STOP rule — read before presenting the summary.** The summary is *past-tense outcomes only*. What was discovered, decided, and written to spec files. No future-tense implementation verbs (`will modify`, `add function`, `edit class`, `change file`). If you catch yourself composing any of the following, you are in the wrong skill — stop and resume the discussion: - File paths outside `/` as steps to change - A task list that reads like TODO items for building the feature - Anything that looks like `/ship-execute`'s output Output the discussion outcome as text. Use these sections only — describe what already exists in the spec files, not what should be built: - **FEATURES DEFINED** — per feature: ID, title, points, RICE, complexity, one-line user story, acceptance-scenario count, NFRs, high-RPN failure modes, edge cases, dependencies - **ACCEPTANCE SCENARIOS (VERBATIM)** — for each feature, list **every acceptance scenario in full Given/When/Then text** exactly as it was written to the spec file. For each feature, group scenarios by tier: - **Core AC** — happy path + edge cases - **E2E AC** — taxonomy-validated scenarios (show `[category]` tag for context) Do not paraphrase, do not summarize, do not list "N scenarios" without showing them. These scenarios are the test contract that `/ship-execute` will treat as authoritative — the user must read the actual text, not approve on a count. - **IDEAS CAPTURED** — tangential ideas filed during discussion - **EPIC** — if assigned, show epic with all features - **IMPACTS** — cross-feature changes already applied to spec files - **BACKLOG EFFECT** — re-estimation notes, priority shifts - **UNRESOLVED** — quality-gate items flagged for follow-up **Acceptance-criteria sign-off gate (run BEFORE the approval AskUserQuestion below).** Before asking for overall approval, run an AC-only review using `AskUserQuestion`. Quote each scenario verbatim in the question text (or batch into groups of ≤4 scenarios per question if there are many). For each scenario set, ask: "Are these acceptance scenarios correct as written? (looks good / edit a scenario / a scenario is wrong / missing a scenario)". If the user picks anything other than "looks good", surface the specific scenario and use a follow-up AskUserQuestion to capture the correction, then update the feature file and re-present that scenario set for re-confirmation. Loop until all scenario sets read "looks good". **Do not skip this gate.** Approving a count is not the same as approving the criteria — the v2.4.0 audit flagged this as the single largest risk surface in `/ship-discuss` because wrong-by-default ACs become the test contract that `/ship-execute` enforces downstream and there is no other point in the pipeline where the user is shown the actual scenario text for sign-off. Then use `AskUserQuestion` for overall approval: - **Approve (Recommended)** — proceed to Phase 6 (Finalize). The discussion is not complete until Phase 6 runs in full. - **Refine** — stay in discussion, iterate on flagged features, re-enter Phase 5 when ready. Do not touch `.active-session.json`. - **Reject** — leave features at `status: proposed`, stop. User can resume later with `/ship-discuss [ID]`. Do not touch `.active-session.json`. ### Phase 6: Finalize (only on Approve) **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/phase-finalize.md` Run these steps in order. The active-skill mutex stays active until the **very last** step so that any accidental Edit to a source file during Finalize still gets blocked. Do not reorder to "optimize" the cleanup. 1. **Update feature statuses** — `status: proposed` → `status: approved` in each spec file. 2. **Append to BACKLOG.md** — use Edit to add approved feature IDs to `/spec/BACKLOG.md`. 3. **Mark graduated ideas** — for IDEA-sourced features, set `status: graduated` and add `graduated_to: FNNN` in the source idea file. Doing this inside the guarded window keeps the lifecycle change inside the mutex window. 4. **Mark `.research-draft.md` obsolete** if it still exists with the current topic (`obsolete: true`). 5. **Print the Next Up block** (see below). 6. **Last action — after everything above has flushed:** use Write to overwrite `/.active-session.json` with `{"skill": null, "cleared": ""}` (soft-delete sentinel). After this step, do **not** continue with any tool calls — the discussion is done. If the user wants to build the feature, they will run `/ship-sprint` in a new session. --- ## REFINE Mode: Update Existing Feature ### Step 0: Sprint Impact Check Before anything else, check if this feature is in an active sprint: 1. **Read the active sprint file** (`/sprints/current/SPRINT.md` — check if this feature's ID appears in any wave, or if any task in the feature's `tasks:` array appears in the sprint) 2. **Check task status** — are any tasks for this feature already in-progress or completed? If the feature is **in an active sprint**, AskUserQuestion: "⚠️ F007 is already being worked on in Sprint 3. Progress: 2/5 tasks done, 1 in-progress. Changing it now may disrupt the current sprint. What would you like to do? (continue editing / pull from sprint first / cancel)" Three paths: - **"continue editing"** → Continue REFINE in-place. After Step 4, flag sprint plan as stale and show impact (see Step 4). - **"pull from sprint"** → Move feature back to backlog (`status: approved`), remove from sprint file, adjust sprint capacity. Then continue REFINE normally. - **"cancel"** → Abort. Suggest finishing the sprint first, then discussing in the next cycle. If tasks are **in-progress or completed**, add extra caution: "Task T003 (auth middleware) is already done. Changes to the spec may invalidate completed work. Want to proceed anyway?" ### Step 1: Load & Present 1. **Load existing feature file** — read all current content 2. **Show current state** to user with a quick health assessment: - How many acceptance scenarios exist? Are they specific or vague? - Are edge cases covered or only the happy path? - Are there TODOs, TBDs, or placeholder text? - Is the task decomposition concrete enough to execute? "Here's what we have for F007. I see some gaps — let me walk through them." ### Step 2: Challenge Existing Spec (same technique as Phase 1.5b — applied to existing content) Run the full Challenge & Surface analysis against the **existing feature content**: !`shipyard-context reference ship-discuss phase-1-5b-challenge 80` Apply each section to what's already in the spec — audit assumptions baked into the current writing, sweep for edge cases not covered by existing acceptance scenarios, scan for conflicts with features added since this was first discussed, and list what's still missing. ### Step 3: Gather Updates Based on what Phase 1.5 surfaced, use AskUserQuestion (never plain text) to gather updates — bundle gaps into a single question where possible: - Resolve each gap: addressed / deferred / not needed - New insights, changed requirements, concerns? - New acceptance scenarios for uncovered edge cases - Technical decisions made since last discussion? ### Step 4: Update & Re-evaluate 1. **Update the feature file** — preserve decision log, add new entries with date 2. **Recalculate estimates** — scope likely changed after surfacing gaps 3. **Re-run viability gate** — feature may now be better defined (or need splitting) 4. **Backlog**: If estimates changed, no need to update BACKLOG.md — it only stores IDs. The updated data will be read from the feature file next time the backlog is displayed. **E2E AC Backfill:** After challenge, check if the feature has any `tier: "e2e"` AC (look for `### E2E AC` section). If not, invoke Phase 3.7 (E2E AC Validation) as backfill. Present as: "This feature predates E2E taxonomy validation." See `references/phase-e2e-validation.md` § Backfill Protocol. ### Step 4.5: Impact Analysis **Read the full protocol:** `${CLAUDE_PLUGIN_ROOT}/skills/ship-discuss/references/impact-analysis.md` This is a REFINE run — see "REFINE mode specifics" in that file. #### Sprint Impact Report (if feature is in active sprint) If the feature was in-sprint and the user chose to continue in-place, show the impact: ``` ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ SPRINT IMPACT: F007 refined mid-sprint ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Estimate change: 5 → 8 points (+3) New scenarios: +2 acceptance scenarios added New tasks: +1 task (T009: handle timeout) Invalidated: none (existing work still valid) Sprint capacity: was 3 pts remaining, now 0 (over by 3) Cross-feature impacts (from Step 4.5): F003: dependency added (informational) F005: acceptance criteria updated (action-required) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ``` Then AskUserQuestion: "Sprint is now over capacity. Options:" - **Absorb** — team stretches to cover (small overrun) - **Defer new tasks** — add new tasks to backlog, finish original scope this sprint - **Swap** — pull a different unstarted feature out of the sprint to make room - **Replan** — cancel and re-plan the sprint (`/ship-sprint --cancel`, then `/ship-sprint`) Update the sprint file with whatever the user chooses. ### Step 5: Approval Gate & Finalize After the impact analysis (and any sprint-replan choices) is applied, run Phase 5 (Spec Approval Gate) and Phase 6 (Finalize) against the refined feature. Same STOP rule, same ordering invariant: the active-skill mutex stays active until the last step. REFINE-mode differences from NEW-mode finalize (status no-op for already-approved features, BACKLOG.md no-op if ID already present, idea archival only if this run graduated an idea, cancel-branch cleanup) are documented in `references/phase-finalize.md` under "REFINE-mode differences". --- ## Rules - **Use AskUserQuestion — never plain text for questions.** AskUserQuestion is a tool call that suspends execution and waits for user input. Plain text output does not pause — the model will continue without user input. Every question that requires an answer must use AskUserQuestion. - **Always recommend.** Every question to the user must include your recommendation. Never ask "A or B?" without saying which you'd pick and why. Example: "Should we require email verification? I'd recommend yes — it prevents fake accounts and is standard for auth flows." - **Don't ask obvious questions.** If the answer is clear from context, the tech stack, or standard practice — just state your recommendation and move on. Only ask when there's a genuine decision to make. Example: don't ask "should login errors be user-friendly?" — of course they should. Do ask "should we rate-limit login attempts? I'd recommend 5 per minute to prevent brute force." - **Be conversational, not mechanical.** This is a discussion, not a form. - **Suggest structure.** If the user rambles, organize their thoughts into features/epics. - **Never assume technical decisions.** Ask about architecture, approach, tradeoffs — but always lead with your suggestion. - **Reference existing spec.** Don't create duplicates. Link to related features. - **Record everything.** Every decision, every "let's not do that", every "maybe later" goes in the decision log. - **Multi-session safe.** If the user stops mid-discussion, state is saved. They can resume with `/ship-discuss [ID]`. ## Next Up (after features are approved) When features are approved and added to backlog, end with: ``` ▶ NEXT UP: Plan a sprint to build these features /ship-sprint (tip: /clear first for a fresh context window) ``` If the user wants to discuss more features instead, that's fine — skip the Next Up and keep talking.