From shipyard
Feature discovery — from quick idea capture to full spec with acceptance criteria. Use when the user mentions a new feature, a 'what if', a 'we should also', wants to discuss requirements, brainstorm, refine an existing feature, explore what to build next, define acceptance criteria, or jot down something for later.
npx claudepluginhub acendas/shipyard --plugin shipyardThis skill is limited to using the following tools:
You are facilitating a feature discovery conversation. This is fluid — not a questionnaire.
Searches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
You are facilitating a feature discovery conversation. This is fluid — not a questionnaire.
!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).
$ARGUMENTS
Absolute first action — before reading any context, before mode detection, before anything. Use the Read tool on <SHIPYARD_DATA>/.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:
cleared is set OR skill is null → previous session ended cleanly (soft-delete sentinel). Proceed.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.⛔ 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.
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:
{
"skill": "ship-discuss",
"topic": "[user's topic or feature ID from $ARGUMENTS]",
"started": "[ISO date]"
}
This file activates a PreToolUse hook that blocks source code writes. If you find yourself wanting to write implementation code, STOP — you are in a discussion, not an execution session.
When the user asks "anything requires discussion" or similar:
pattern: ^status: proposed, path: <SHIPYARD_DATA>/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.<SHIPYARD_DATA>/spec/ideas/IDEA-*.md to enumerate idea files. For each, Read the file, parse frontmatter, and skip any with status: graduated or status: rejected.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)
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."
If you lose context mid-discussion (e.g., after auto-compaction):
<SHIPYARD_DATA>/spec/.research-draft.md. If it exists, parse its frontmatter — if obsolete: true is set, treat it as absent (skip to step 2). Otherwise:
topic: matches → research and challenge phases completed. Read it for findings. Resume from Phase 2 (Viability Gate)topic: doesn't match the current discussion topic → AskUserQuestion: "A previous discussion left unfinished research on '[topic]'. Mark it obsolete and start fresh on your current topic? (mark obsolete / keep and resume that topic instead)"
obsolete: true in the draft's frontmatter, proceed fresh into Phase 1.5 (Research) for the current topictopic: 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."<SHIPYARD_DATA>/spec/features/F*-*.md to enumerate, then Read each and match by title against the current topic.
status: proposed → Phase 3 done, resume from Phase 3.5 (Impact Analysis)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 session-guard sentinel write still runs last.Research findings are the most expensive state to lose (WebSearch/WebFetch results). The research draft file preserves them.
When the input is a short one-liner — capture it instantly and offer to go deeper.
Generate the next available IDEA-NNN ID. Write to <SHIPYARD_DATA>/spec/ideas/IDEA-NNN-[slug].md:
---
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.]
Captured: IDEA-NNN — [title]
Want to flesh this out into a full feature now, or save it for later?
Rules for CAPTURE mode:
When the input is an epic ID (E001) or the user describes a large initiative.
If existing epic:
<SHIPYARD_DATA>/spec/epics/E00N-*.md (substitute the epic ID), then Read the matching file.pattern: ^epic: E00N, path: <SHIPYARD_DATA>/spec/features, glob: F*.md, output_mode: files_with_matches, then Read each match.Present the current state:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EPIC: E001 — Payment System
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Features (4):
F003 — Card Payments (done, 8 pts, 5 scenarios)
F004 — Refund Flow (approved, 5 pts, 3 scenarios)
F012 — Payment Analytics (proposed, 3 pts, 2 scenarios)
F015 — Split Payments (proposed, 8 pts, 0 scenarios)
Total: 24 pts | Done: 8 pts | Remaining: 16 pts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
If new epic (user described a large initiative): create the epic file first, then proceed.
Use AskUserQuestion to understand the direction:
This is the critical step. Based on the discussion, identify changes that need to propagate to features:
For each affected feature:
| Change type | What happens |
|---|---|
| Scope change | Update feature's acceptance criteria, re-estimate RICE/points |
| New dependency | Add to feature's dependencies: array (bidirectional) |
| Priority shift | Update RICE fields, note in decision log |
| Acceptance criteria change | Edit feature file, add decision log entry: "Updated due to epic E00N discussion: [reason]" |
| Feature removed from epic | Set epic: "" in feature frontmatter, note in decision log |
| Feature added to epic | Set epic: E00N in feature frontmatter |
| Feature invalidated | Set status: cancelled in feature frontmatter, note reason in decision log |
| New feature identified | Run NEW mode inline to create it, assign to this epic |
Sprint impact check: For each modified feature, check if it's in an active sprint. If yes, flag:
⚠ F004 (Refund Flow) is in Sprint 3 — 2/4 tasks done.
Changing acceptance criteria may invalidate completed work.
Apply now / defer to post-sprint / skip this change
For each new feature identified during the epic discussion, run the standard NEW mode phases (Phase 1 → 5) with the epic pre-assigned. Bundle related features — discuss all new features before writing any, so dependencies are clear.
Review the epic after all changes:
| # | Check | Fail criteria |
|---|---|---|
| 1 | All features have acceptance criteria | Any feature in epic has 0 scenarios |
| 2 | No orphan features | Features that lost their epic assignment aren't floating unassigned |
| 3 | Dependencies are consistent | Feature A depends on B, but B doesn't know about A |
| 4 | No duplicates within epic | Two features describe the same behavior |
| 5 | Epic scope is coherent | Features in the epic don't logically belong together |
Present the changed state:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
EPIC UPDATED: E001 — Payment System
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Changes:
F004: acceptance criteria updated (3 → 5 scenarios)
F012: RICE re-estimated (score: 18 → 24)
F015: split into F015 + F018 (split payments → basic + advanced)
F018: NEW — Advanced Split Payments (5 pts, 4 scenarios)
Sprint impact:
F004 is in Sprint 3 — changes deferred to post-sprint
Features (5):
F003 — Card Payments (done)
F004 — Refund Flow (approved, updated)
F012 — Payment Analytics (proposed, re-estimated)
F015 — Basic Split Payments (proposed, scoped down)
F018 — Advanced Split Payments (proposed, NEW)
Total: 29 pts | Done: 8 pts | Remaining: 21 pts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
AskUserQuestion: "Approve these changes? (yes / adjust / revert all)"
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.
Read <SHIPYARD_DATA>/spec/ideas/IDEA-NNN-[slug].md. Extract:
Present it briefly to the user as plain text:
Idea: IDEA-NNN — [title]
[description]
[why it might matter]
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 (Simplification Scan) → Phase 4 (Capture tangential ideas) → 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.
Idea archival happens inside Phase 6 (Finalize), between the BACKLOG.md append and the session-guard cleanup — not here and not as a standalone step. The graduation target is:
<SHIPYARD_DATA>/spec/ideas/IDEA-NNN-[slug].md
When Phase 6 runs for an idea-sourced feature, after appending to BACKLOG.md, use the Edit tool to set the idea file's frontmatter to status: graduated and add graduated_to: FNNN. Confirm: "IDEA-NNN has been graduated to [FNNN: title]." Doing the Edit inside Phase 6 keeps it inside the session-guard window. Listings filter status: graduated ideas out by default; the reap-obsolete housekeeping reaps them physically after retention.
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):
Key behaviors during conversation:
Once you understand what the user wants, research before challenging. Walk this in order. Use LSP first for code navigation; fall back to Grep/Read silently.
Constitution check. Glob .claude/rules/project-*.md and .claude/rules/learnings/*.md, read every match. Extract architecture boundaries, banned patterns, naming conventions, domain vocabulary, shared utilities. Flag tensions with the proposed feature as pre-loaded Phase 1.5b challenge items. Skip silently if no project-*.md files exist.
Internal research. Glob <SHIPYARD_DATA>/spec/features/F*.md and Read each to find overlaps. Use LSP documentSymbol / findReferences for relevant codebase patterns. Read <SHIPYARD_DATA>/codebase-context.md for stack constraints.
How others solve it. WebSearch how established products handle this same problem, the standard UX patterns users expect, and open-source implementations to study. WebSearch common user complaints about existing solutions to learn from their mistakes. WebSearch best practices and security pitfalls for the domain (include the current year for currency). WebFetch official docs for mentioned libraries/APIs.
Write findings to the feature file ## Technical Notes (after Phase 3 creates it) with this structure:
## Technical Notes
### Research Findings
**How others do it**
- [Product/project] — [how they solve this, what we can learn] (confidence: HIGH/MEDIUM)
- [Open-source repo] — [relevant approach or pattern] (confidence: HIGH/MEDIUM)
- [Common user complaints about existing solutions] — [what to avoid]
**Relevant docs**
- [URL] — [why it matters] (confidence: HIGH)
**Codebase patterns to follow**
- [file path] — [what pattern to mirror]
**Constitution constraints**
- [rule from project-*.md] — [how it applies to this feature]
**Known gotchas**
- [pitfall] — [how to avoid] (confidence: HIGH/MEDIUM/LOW)
**Recommended approach**
- [prescriptive direction — "Use X" not "Consider X or Y"]
Confidence levels: HIGH = verified in official docs or codebase. MEDIUM = multiple sources agree but not officially verified. LOW = single source or AI knowledge only.
Be prescriptive: "Use X" not "Consider X or Y". The builder needs decisions, not options.
Fold findings into the conversation naturally before challenging: "I looked into how other apps handle this — most use [X] because [Y]. That aligns with what you're describing."
Visual context: If the feature spans multiple services, external APIs, or touches multiple parts of the architecture, show a C4 diagram (Context or Container level) so the user can see where it fits. If it involves 3+ components communicating in sequence, show a sequence diagram to make the interaction flow visible. See references/communication-design.md for C4 and sequence diagram patterns. Skip for features that live entirely within one component.
Once you have a reasonable understanding of the feature, proactively challenge it before moving to spec. Delegate the heavy methodology pass to a shipyard-discovery-scout subagent so you keep the user dialogue context clean.
Spawn the scout (single Agent call):
subagent_type: shipyard:shipyard-discovery-scout
prompt: |
Feature draft: <inline summary of the user's feature so far, OR path to .research-draft.md if it exists>
Codebase context: <SHIPYARD_DATA>/codebase-context.md
Project rules: .claude/rules/project-*.md
Apply the four methodology references — references/challenge-surface.md,
references/edge-case-framework.md, references/nfr-scan.md,
references/failure-modes.md — and return your structured findings list.
The scout reads the methodology files and returns a DISCOVERY SCOUT REPORT with grouped findings (challenges / edge cases / NFRs / failure modes). You hold the report; the methodology files never enter your context. Also run a quick pre-mortem (from discovery-techniques.md) — that one is short enough to do inline.
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 <SHIPYARD_DATA>/spec/.research-draft.md:
---
topic: "[primary topic from user input]"
created: [ISO date]
---
Body sections: ## Research Findings (implementation context, patterns, docs/references, gotchas — same structure as feature Technical Notes), ## Challenge Resolutions (resolved grey areas, deferred items). This file is absorbed into the feature file's Technical Notes in Phase 3 and then deleted.
Before writing to spec, silently evaluate each feature:
If viability kills the feature, use the Edit tool to set obsolete: true in <SHIPYARD_DATA>/spec/.research-draft.md's frontmatter (soft-delete sentinel — recovery logic filters it out; reap-obsolete reaps it later).
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."
Use the Read tool on <SHIPYARD_DATA>/spec/.research-draft.md. If it exists and is not marked obsolete: true, absorb its content into the feature file's ## Technical Notes and ## Decision Log sections. Do not mark it obsolete yet — it serves as a recovery checkpoint until Phase 3 is fully complete (feature file written with acceptance criteria, estimates, and epic assignment). Use Edit to set obsolete: true in .research-draft.md's frontmatter only after Phase 3 finishes.
For each well-defined feature:
Generate ID — Next available FNNN (F001, F002, etc.)
Determine epic — Use Glob <SHIPYARD_DATA>/spec/epics/E*.md to enumerate epics and Read each. Use Grep with pattern: ^epic:, path: <SHIPYARD_DATA>/spec/features, glob: F*.md, output_mode: content, -n: false to see how features are grouped. Then decide:
Does it belong to an existing epic? Check if the feature:
Should it create a new epic? Check if:
If unclear — explain the options and AskUserQuestion:
This feature touches [domain]. I see two options:
1. Add to E002 (Payments) — it's related to billing, but the scope is broader
2. Create new epic "Revenue Analytics" — this is the first of likely 3+ features in this area
Recommended: 2 — this feels like a distinct product area that will grow
If no epics exist yet — create the first one if the feature is part of a larger initiative. Otherwise, leave epic: "" and let it accumulate. Epics emerge from patterns, don't force them early.
Write feature file to <SHIPYARD_DATA>/spec/features/FNNN-[slug].md.
Frontmatter — every field is required. No omissions.
---
id: FNNN
title: ""
type: feature
epic: "" # E00N if assigned, empty string if none
status: proposed
story_points: 0 # rough estimate from discussion
complexity: "" # low | medium | high
token_estimate: 0 # estimated total tokens (input+output) to implement this feature. Guide: S task ~50K, M task ~150K, L task ~300K. Sum across expected tasks.
rice_reach: 0 # 0–10: how many users affected
rice_impact: 0 # 0–3: massive=3, high=2, medium=1, low=0.5
rice_confidence: 0 # 0–100: % confidence in reach/impact estimates
rice_effort: 0 # person-months (use 0.5 for small features)
rice_score: 0 # computed: (reach × impact × confidence) / effort
feasibility: 0 # 1–10 from viability gate
dependencies: [] # feature IDs this depends on
references: [] # full relative paths: <SHIPYARD_DATA>/spec/references/FNNN-slug.md
children: [] # sub-feature IDs if split
tasks: [] # populated during sprint planning
created: YYYY-MM-DD
updated: YYYY-MM-DD
---
Body sections:
.research-draft.md)<SHIPYARD_DATA>/spec/tasks/ and referenced via the tasks: array in frontmatter. Preliminary task IDs can be listed during discuss; full task files are created during sprint planning.<SHIPYARD_DATA>/spec/references/FNNN-<slug>.md. Add frontmatter to each extracted file: feature: FNNN and source: extracted from FNNN during discuss.<SHIPYARD_DATA>/spec/references/F001-api.md) to the references: array in the feature's frontmatterInitial estimates — fill every RICE field in the frontmatter written above:
rice_reach and rice_impact if not obvious from contextrice_confidence, rice_effort, story_points, complexity, token_estimate, and feasibility yourself based on the discussionrice_score = (rice_reach × rice_impact × rice_confidence) / rice_effortEpic: If an epic was assigned, set epic: E00N in feature frontmatter. Do NOT update the epic file with a features list — epic membership is derived by querying feature files.
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)
Skip if Glob <SHIPYARD_DATA>/spec/features/F*.md returns no results.
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:
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.
Any tangential features mentioned → create as idea files via the same logic as CAPTURE mode above.
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.
Before presenting to the user, review your own output. Re-read each feature file you wrote and check against this checklist:
| # | Check | Fail criteria |
|---|---|---|
| 1 | Every acceptance scenario is Given/When/Then | Vague prose like "user can do X" without structured scenario |
| 2 | Happy path + at least 1 edge case per feature | Only happy path covered |
| 3 | No ambiguous words | "appropriate", "properly", "as needed", "etc.", "various" in acceptance criteria |
| 4 | No TBDs or placeholders | Any "TBD", "TODO", "to be decided", "[fill in]" left in the spec |
| 5 | User story has clear actor, action, and value | "As a... I want... so that..." missing any part |
| 6 | RICE fields all populated | Any RICE field still at 0 without a reason in the decision log |
| 7 | Dependencies identified | Feature touches other features but dependencies: [] is empty |
| 8 | Research findings are prescriptive | "Consider X or Y" instead of "Use X" |
| 9 | How others do it section populated | No real-world product references found |
| 10 | Feature is one feature, not multiple | Acceptance scenarios describe unrelated behaviors |
| 11 | NFRs considered | Feature handles sensitive data or has scale concerns but no NFR notes |
| 12 | Edge cases covered | No boundary values, state transitions, or concurrency scenarios |
| 13 | Failure modes analyzed | Write operations exist but no failure mode table |
| 14 | EARS syntax used | Acceptance criteria use vague language instead of WHEN/WHILE/IF patterns |
| 15 | All states covered | Missing empty state, error state, loading state, or offline state |
Iterate the checklist on each feature file, fixing failures (AskUserQuestion when input is needed) and re-running. Max 3 iterations. Hold the table in mind across iterations — emit only per-iteration deltas (which checks fixed, which remain). Do not re-print the table on each pass. Flag remaining gaps as "Unresolved — needs follow-up in /ship-discuss [ID]". Then proceed to Phase 4.95.
After the self-review quality gate passes, spawn the critic agent to challenge the spec from angles the self-review doesn't cover — implicit assumptions, feasibility risks, and design decision quality.
Determine stakes level:
high if: feature is part of an epic, story_points >= 8, touches auth/payments/data, or has 6+ acceptance scenariosstandard otherwiseSpawn the critic:
subagent_type: shipyard:shipyard-critic
Prompt the critic with:
feature-critique[standard|high]<SHIPYARD_DATA>/codebase-context.md.claude/rules/project-*.mdProcess the critic's findings:
PRIORITY ACTIONS section — these are mandatory fixes## Decision Log as "Critic flagged — [summary]. Accepted because: [your reasoning]" or fix if quickDo NOT re-run the critic after fixes. One round only. Address what you can, ask the user about the rest, and proceed.
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:
<SHIPYARD_DATA>/ as steps to change/ship-execute's outputOutput the discussion outcome as text. Use these sections only — describe what already exists in the spec files, not what should be built:
Then use AskUserQuestion for approval:
.active-session.json.status: proposed, stop. User can resume later with /ship-discuss [ID]. Do not touch .active-session.json.Run these steps in order. The session guard stays active until the very last step so that any accidental Edit to a source file during Finalize still gets blocked — that's the whole point of the ordering. Do not reorder to "optimize" the cleanup.
status: proposed → status: approved in its spec file (.md, allowed by the guard).<SHIPYARD_DATA>/spec/BACKLOG.md (.md, allowed by the guard).status: graduated and add graduated_to: FNNN in the corresponding <SHIPYARD_DATA>/spec/ideas/IDEA-NNN-*.md frontmatter now. Doing this here — inside the guarded window — keeps the lifecycle change inside the session-guard cover..research-draft.md obsolete if it still exists with the current topic — sets obsolete: true in its frontmatter.<SHIPYARD_DATA>/.active-session.json with {"skill": null, "cleared": "<iso-timestamp>"} (soft-delete sentinel — session-guard treats skill: null as inactive). Until this step, any Edit to a source-code path is still blocked by the session guard. 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.Before anything else, check if this feature is in an active sprint:
<SHIPYARD_DATA>/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)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:
status: approved), remove from sprint file, adjust sprint capacity. Then continue REFINE normally.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?"
"Here's what we have for F007. I see some gaps — let me walk through them."
Run the full Challenge & Surface analysis against the existing feature content:
!shipyard-context reference ship-discuss challenge-surface 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.
Based on what Phase 1.5 surfaced, use AskUserQuestion (never plain text) to gather updates — bundle gaps into a single question where possible:
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.
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:"
/ship-sprint --cancel, then /ship-sprint)Update the sprint file with whatever the user chooses.
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 session guard stays active until the last step.
REFINE-specific differences from the NEW-mode finalize:
status: approved before this session — leave the status alone..active-session.json delete) always run, in that order. The guard cleanup is still the very last action so any accidental source-code Edit during the wrap-up is still blocked.If the REFINE run was interrupted by the "cancel" branch of the Sprint Impact Check (Step 0), the session guard still needs to be cleaned up — delete .active-session.json as the last action before returning control to the user.
/ship-discuss [ID].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.