Menu
Use when you have an idea, goal, or feature description and need to turn it into an actionable plan with tasks
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
Iterative review-fix loop for accumulated milestone/branch changes. Runs parallel reviewers, fixes findings autonomously, repeats until clean. Use after multiple tasks merge to a milestone branch, or before merging to main. Invoke with /milestone-review --base-branch main. Supports --dry-run and --max-iterations.
This skill should be used when the user wants a comprehensive code review using multiple specialized reviewers in parallel. Invoked with /multi-review or when user asks for 'thorough review', 'full code review', or 'review from multiple perspectives'. Use --plan <path> to review an implementation plan pre-coding.
Use when facing a bug, test failure, or unexpected behavior that isn't immediately obvious
Use when starting a new feature or idea that needs thorough pre-execution planning. Use instead of calling /product-review, /spec, and review skills individually.
Use when you need measured performance evidence by running a repeatable command on the current branch and a baseline ref
Use when you need 3-5 intentionally different UI directions before committing to a single design approach
| name | spec |
| description | Use when you have an idea, goal, or feature description and need to turn it into an actionable plan with tasks |
| allowed-tools | Read, Bash, Glob, Grep, Write, Edit, AskUserQuestion, Task, WebSearch, mcp__plugin_context7_context7__resolve-library-id, mcp__plugin_context7_context7__query-docs |
Note: The current year is 2026. Use this when dating plans and searching for documentation.
Transform ideas, feature descriptions, or improvement goals into well-structured plan documents with decomposed tasks. Use --deepen to enhance an existing plan with parallel research.
NEVER CODE! Just research, plan, and decompose into tasks.
$ARGUMENTS = feature description, plan reference, or --deepen [plan-path]--deepen is present, jump to Deepen Mode belowDo not proceed until you have a feature description.
Evaluate whether the feature description needs refinement.
Greenfield check: If the feature is greenfield (new system, new major capability, or significant architectural change), suggest: "This looks like a greenfield feature. Consider running /product-review first to challenge scope and validate the approach before planning." If the feature is primarily UI/frontend, add: "This looks like a UI-heavy feature. Consider running /product-review DESIGN first to map user journeys and interaction patterns before planning." Proceed if user declines.
If already detailed (specific acceptance criteria, exact behavior, constrained scope): Offer to skip: "Your requirements seem detailed enough. Should I proceed with research, or refine further?"
Scope challenge (run for all non-trivial features):
Otherwise, run interactive Q&A using AskUserQuestion (one question at a time):
Adapt questions based on answers. Exit when the idea is clear OR user says "proceed."
Lightweight repo research (parallel with dialogue):
If 2-3 distinct approaches exist, propose them with pros/cons and let user pick. Lead with your recommendation. Apply YAGNI.
Gather signals during refinement for research decision:
Local research (always, parallel):
Research decision based on signals from Phase 0:
Announce the decision briefly, then proceed.
External research (conditional, parallel):
Consolidate findings: relevant file paths, external docs/URLs, CLAUDE.md conventions.
Title & Categorization:
feat: Add User Authentication, fix: Cart Total CalculationYYYY-MM-DD-<type>-<descriptive-name>-plan.md (3-5 words after prefix)SpecFlow Analysis:
Engineering lenses (apply while writing Technical Considerations):
Design lenses (apply for plans with UI scope):
Choose detail level:
---
title: [Title]
type: [feat|fix|refactor]
date: YYYY-MM-DD
---
# [Title]
[Brief description]
## Acceptance Criteria
- [ ] Core requirement 1
## NOT in Scope
[Work considered and explicitly deferred, with one-line rationale each]
## Context
[Critical information]
## References
- [Links]
---
title: [Title]
type: [feat|fix|refactor]
date: YYYY-MM-DD
---
# [Title]
## Overview
[Comprehensive description]
## Problem Statement / Motivation
[Why this matters]
## Proposed Solution
[High-level approach]
## Technical Considerations
- Architecture impacts
- Performance implications
- Security considerations
## Acceptance Criteria
- [ ] Detailed requirement 1
- [ ] Testing requirements
## Success Metrics
[How we measure success]
## Dependencies & Risks
[What could block or complicate this]
## NOT in Scope
[Work considered and explicitly deferred, with one-line rationale each]
## What Already Exists
[Map each sub-problem to existing code/flows. Note whether plan reuses or rebuilds.]
## Architecture Diagram
[ASCII diagram: component boundaries, dependencies, data flow]
[Show happy path AND shadow paths (nil, empty, error)]
## Test Diagram
[Map every new codepath/flow to its required test]
| New Codepath/Flow | Test Type | Happy Path | Failure Path | Edge Case |
|-------------------|-----------|------------|--------------|-----------|
| ... | unit/integration/e2e | Y/N | Y/N | Y/N |
## Interaction States (include for plans with UI scope)
| Feature | Loading | Empty | Error | Success | Partial |
|---------|---------|-------|-------|---------|---------|
| ... | [what user sees] | ... | ... | ... | ... |
## Failure Modes
[For each new codepath: one realistic failure, whether a test covers it, whether error handling exists, whether user sees it or it's silent]
| Codepath | Failure Mode | Test? | Handled? | User Sees? |
|----------|-------------|-------|----------|------------|
| ... | ... | Y/N | Y/N | Error msg / Silent |
> Silent + no test + no handling = **CRITICAL GAP** — must be addressed before implementation.
## References & Research
- Similar implementations: [file_path:line_number]
- Best practices: [documentation_url]
- Related PRs: #[pr_number]
---
title: [Title]
type: [feat|fix|refactor]
date: YYYY-MM-DD
---
# [Title]
## Overview
[Executive summary]
## Problem Statement
[Detailed problem analysis]
## Proposed Solution
[Comprehensive solution design]
## Technical Approach
### Architecture
[Detailed technical design]
### Implementation Phases
#### Phase 1: [Foundation]
- Tasks and deliverables
- Success criteria
- Estimated effort
#### Phase 2: [Core Implementation]
- Tasks and deliverables
- Success criteria
- Estimated effort
#### Phase 3: [Polish & Optimization]
- Tasks and deliverables
- Success criteria
- Estimated effort
## Alternative Approaches Considered
[Other solutions evaluated and why rejected]
## Acceptance Criteria
### Functional Requirements
- [ ] Detailed functional criteria
### Non-Functional Requirements
- [ ] Performance targets
- [ ] Security requirements
- [ ] Accessibility standards
### Quality Gates
- [ ] Test coverage requirements
- [ ] Documentation completeness
- [ ] Code review approval
## Success Metrics
[Detailed KPIs and measurement methods]
## Dependencies & Prerequisites
[Detailed dependency analysis]
## Risk Analysis & Mitigation
[Comprehensive risk assessment]
## Resource Requirements
[Team, time, infrastructure needs]
## Future Considerations
[Extensibility and long-term vision]
## Documentation Plan
[What docs need updating]
## NOT in Scope
[Work considered and explicitly deferred, with one-line rationale each]
## What Already Exists
[Map each sub-problem to existing code/flows. Note whether plan reuses or rebuilds.]
## Architecture Diagram
[ASCII diagram: component boundaries, dependencies, data flow]
[Show happy path AND shadow paths (nil, empty, error)]
## Test Diagram
[Map every new codepath/flow to its required test]
| New Codepath/Flow | Test Type | Happy Path | Failure Path | Edge Case |
|-------------------|-----------|------------|--------------|-----------|
| ... | unit/integration/e2e | Y/N | Y/N | Y/N |
## Interaction States (include for plans with UI scope)
| Feature | Loading | Empty | Error | Success | Partial |
|---------|---------|-------|-------|---------|---------|
| ... | [what user sees] | ... | ... | ... | ... |
## Reversibility Assessment
- Rollback procedure: [exact steps]
- Data migration reversibility: [Y/N, details]
- Feature flag strategy: [what to flag, kill switch]
- Deploy-time risk window: [what breaks between step 1 and step N]
## Failure Modes
[For each new codepath: one realistic failure, whether a test covers it, whether error handling exists, whether user sees it or it's silent]
| Codepath | Failure Mode | Test? | Handled? | User Sees? |
|----------|-------------|-------|----------|------------|
| ... | ... | Y/N | Y/N | Error msg / Silent |
> Silent + no test + no handling = **CRITICAL GAP** — must be addressed before implementation.
## References & Research
### Internal References
- Architecture decisions: [file_path:line_number]
- Similar features: [file_path:line_number]
### External References
- Framework documentation: [url]
- Best practices guide: [url]
### Related Work
- Previous PRs: #[pr_numbers]
- Related issues: #[issue_numbers]
Write plan to docs/plans/:
mkdir -p docs/plans
Cross-reference: Link related issues/PRs, reference specific file paths, add external resource links.
Unresolved decisions: If any question asked during Phase 0 goes unanswered or the user defers a decision, log it explicitly at the end of the plan as:
## Unresolved Decisions
[Decisions deferred during planning that may affect implementation]
- [Question] — [Why it matters] — [Default assumption if not resolved]
Never silently default. Surface these so implementers know where ambiguity lives.
Completion summary — append to every STANDARD and COMPREHENSIVE plan:
## Plan Review Summary
- Scope challenge: [passed / flagged N concerns]
- NOT in scope: [N items deferred]
- What already exists: [N items mapped]
- Architecture diagram: [included / N/A]
- Test diagram: [N codepaths mapped, N gaps]
- Interaction states: [included / N/A — no UI scope]
- Failure modes: [N mapped, N CRITICAL GAPS]
- Engineering review: [N issues found, N critical gaps]
- Design review: [scores per dimension / N/A — no UI scope]
- Unresolved decisions: [N open]
Review the plan through engineering and design lenses before decomposition. Runs for ALL plans — including MINIMAL. There is no option to skip this phase. Individual issues can be deferred (logged as unresolved), but the checks themselves always execute.
Core checks (always run, all plan levels):
Scope Challenge (from skills/plan-eng-review/SKILL.md Step 0):
Test Diagram (from skills/plan-eng-review/SKILL.md Section 3):
Failure Modes (from skills/plan-eng-review/SKILL.md):
UI checks (if plan includes Interaction States section or otherwise has UI scope):
Interaction State Coverage (from skills/plan-design-review/SKILL.md Pass 2):
AI Slop Risk (from skills/plan-design-review/SKILL.md Pass 4):
Additional review for COMPREHENSIVE plans:
Run the engineering review inline. Apply cognitive patterns from skills/plan-eng-review/SKILL.md:
If plan has UI scope, also run remaining design passes (from skills/plan-design-review/SKILL.md):
Key cognitive patterns to apply throughout:
Amend plan with all findings. Update Plan Review Summary.
Check if Linear MCP is available (test: can you call list_teams?).
If Linear MCP is not available:
Skip decomposition silently. Set decomposed = false. The plan file is the deliverable. Proceed to Phase 4.
If Linear MCP is available: Use AskUserQuestion:
Question: "Decompose this plan into Linear issues for tracking and dispatch?" Options:
If user selects "Execute directly":
Set decomposed = "execute". Proceed to Phase 4.
If user selects "Yes":
Set decomposed = true. Create issues in Linear:
Every issue must be fully executable without reading the plan file. Workers receive the issue description as their sole specification — /dispatch injects the issue title and description into the worker prompt, and /start-task reads project docs (CLAUDE.md, README.md) but never docs/plans/. The plan file is a project record. It is NOT a worker dependency.
Prohibited patterns — these produce unusable issues:
docs/plans/ as a substitute for including implementation details in the issueRequired: Distribute ALL actionable plan detail across issues. After decomposition, every implementation detail, code path, test requirement, and failure mode in the plan must exist in at least one issue description. The plan should contain nothing a worker needs that isn't already in their assigned issue.
save_issue)Build a coverage matrix mapping every actionable plan section to an issue. Display it in the conversation. This is how you prove no detail is orphaned.
Step 1: Extract rows. Read the plan. Create one row per actionable section or subsection. Actionable = contains implementation details, code paths, test requirements, failure modes, or acceptance criteria. Skip narrative-only sections. Split sections with multiple distinct concerns into separate rows.
Step 2: Fill the matrix.
| Plan Section | Key Details to Transfer | Assigned Issue | Est. Words |
|---|---|---|---|
| [section name] | [2-3 specifics: file paths, functions, behaviors] | [Issue N: title] | [~NNN] |
Rules:
Step 3: User confirmation. Display the matrix. Use AskUserQuestion: "Coverage matrix maps N plan sections to M issues. Any gaps or reassignments?" Proceed only after user confirms.
Step 4: Post-creation verification. After all issues are created, re-display the matrix with actual issue IDs replacing planned titles. Spot-check via get_issue that each row's Key Details appear in the assigned issue. Update any issue where Key Details are missing.
Dedup check first: Before creating any issue, call list_issues(project=<project>, query=<title>) to check if an issue with this title already exists. Skip creation if found and log "Issue already exists: ".
# Create or find the project
save_project(name="<project name>", addTeams=[<team>])
# Create issues within the project — QUALITY GATE applies (see below)
save_issue(title="<task>", team=<team>, project=<project>, priority=<1-4>, description="<description>", labels=["<label>"])
# Set parent-child relationships (parentId = containment)
save_issue(id=<child-id>, parentId=<parent-id>)
# Wire execution-order dependencies between sibling tasks
save_issue(id=<blocked-task>, blockedBy=[<blocking-task>])
# Post-write validation: read back and check for formatting artifacts
get_issue(id=<created-id>)
# If description contains literal \n, \\n, XML tags, or trailing ") — rewrite it
# Display created issues
list_issues(project=<project>)
Every issue created during decomposition must be a complete, standalone specification. A worker who reads only the issue description plus the project's CLAUDE.md must be able to implement the task without consulting any other document.
Required description structure:
## Problem
[Full context for WHY this task exists. Not a summary — include the motivation,
the current state, and what's broken or missing. Transfer relevant context from
the plan's Problem Statement, Overview, and Technical Considerations.
A worker reading only this section must understand why this task matters
and how it fits into the broader change.]
## Approach
[Detailed implementation guidance — specific enough to code from:]
- Which files and functions to create or modify, with file paths
- Which existing code/patterns to reuse (file paths from plan research)
- Data flow: what goes in, what comes out, how state changes
- Key design decisions from the plan that constrain this task
- Architecture patterns to follow or extend
["Implement the feature" is NEVER sufficient. Name the files, the functions,
the data flow. If the plan's research identified specific line numbers or
existing utilities, include them here.]
## Acceptance Criteria
- [ ] Specific, testable criterion scoped to THIS task
- [ ] Each criterion should be verifiable with a named command or test
[Do not include criteria that belong to sibling tasks in the decomposition.
Every criterion must be independently provable by the worker.]
## Test Requirements
- [ ] Unit tests: [what to test, which test file, what fixtures]
- [ ] Integration tests: [if applicable — what systems interact]
- [ ] Edge cases to cover: [from plan's Test Diagram and Failure Modes]
[Map directly from the plan's Test Diagram entries that fall within this
task's scope. If the plan identified CRITICAL GAPs here, they MUST appear.]
## Target Files
- path/to/file.ext — [what changes in this file and why]
- path/to/other.ext — [what changes in this file and why]
[Annotate each file with what the task does to it. Not a bare file list —
a file-by-file roadmap. This also enables file-conflict detection during dispatch.]
## Edge Cases & Failure Modes
- [Failure scenario from plan]: [expected handling]
- [Edge case from plan]: [expected behavior]
[Transfer the relevant entries from the plan's Failure Modes table for this
task's scope. If the plan identified CRITICAL GAPs (silent + no test + no
handling) that touch this task, they MUST be listed and addressed.]
## Dependencies
- Assumes [task-id] is complete: [what it provides that this task builds on]
- Produces for [task-id]: [what this task creates that downstream tasks need]
[If no dependencies, state "None — independently executable".
Workers use this to validate their starting state before coding.]
Section depth requirements — an issue fails the quality gate if any section is thin:
- src/foo.py without explanation fails the gate.Required fields: title (descriptive), description (meets full structure above), priority (1-4), labels (at least one: Bug, Feature, Improvement, Refactor), project.
Formatting rules: Write actual markdown with real line breaks. Never use \n escape sequences. Do not include XML tool syntax or string delimiters in content.
Post-write validation: After each save_issue, call get_issue(id=<id>) and check the description for formatting artifacts (literal \n, \\n, XML tags like </invoke>, trailing ")). If found, rewrite with corrected content.
parentId= "this issue is a sub-issue of that one" (containment).blockedBy/blocks= "this issue cannot start until that one finishes" (execution ordering). Append-only — cannot remove via MCP. Projects = top-level grouping. Projects are NOT issues — they can't have blockers or be claimed.
Target files: Include a
## Target Filessection in each issue description listing the primary files the task will create or modify. This enables file-conflict detection during dispatch.
No transitive edges: If A depends on B and B depends on C, do NOT also add A→C. Only direct edges.
If user selects "No":
Set decomposed = false. Proceed to Phase 4.
Use AskUserQuestion to present options:
If decomposed = "execute":
Spec complete. Output: "Plan ready at <path>. Implementing now."
The /spec skill ends here — read the plan file and begin implementation:
/start-task or /finish-task neededDo NOT present the post-plan menu below. Proceed directly to implementation.
If decomposed = true:
Engineering and design reviews ran in Phase 2.5. For a deeper dive, run /plan-eng-review or /plan-design-review standalone.
Question: "Plan created, reviewed, and decomposed into tasks. What next?"
Options:
--deepen mode for parallel research enhancement/multi-review for specialized feedback/dispatch to start parallel execution/start-taskgh issue create --title "<type>: <title>" --body-file <plan_path>If decomposed = false:
Engineering and design reviews ran in Phase 2.5. For a deeper dive, run /plan-eng-review or /plan-design-review standalone.
Question: "Plan created and reviewed. What next?"
Options:
--deepen mode for parallel research enhancement/multi-review for specialized feedbackgh issue create --title "<type>: <title>" --body-file <plan_path>--deepen)Enhance an existing plan with parallel research agents, skill applications, and learnings.
If argument provided after --deepen, match it in docs/plans/. Otherwise find most recent:
ls -lt docs/plans/*.md 2>/dev/null | head -5
If no plans found: "No plans in docs/plans/. Run /spec first." Then STOP.
Read the plan file.
Extract: sections, technologies/frameworks, domain areas, code examples, acceptance criteria. Create a section manifest listing each section and what to research.
ls .claude/skills/*/SKILL.md 2>/dev/null
ls ~/.claude/skills/*/SKILL.md 2>/dev/null
Read each skill's description. For every skill matching a plan section, spawn a parallel sub-agent:
Spawn ALL matched skill sub-agents in PARALLEL.
For each major section:
Discover ALL available agents:
find .claude/agents -name "*.md" 2>/dev/null
find ~/.claude/agents -name "*.md" 2>/dev/null
Launch ALL agents in parallel against the plan. Maximum coverage, not efficiency.
Collect outputs from all sources. Extract actionable recommendations, code patterns, anti-patterns, performance/security considerations, edge cases. Deduplicate, prioritize by impact, flag conflicts.
Merge research back preserving original structure. Add Research Insights subsections with: Best Practices, Performance Considerations, Implementation Details (code examples), Edge Cases, References.
Add Enhancement Summary at top: date, sections enhanced, agents used, key improvements, new considerations.
If Linear MCP is available:
save_issue(id=<id>, description="<enhanced description>") # Refined tasks
save_issue(title="<title>", team=<team>, project=<project>) # New tasks
save_issue(id=<id>, state=Done) + save_comment(body="Obsoleted") # Obsolete tasks
Check if Linear issues exist for this plan (call list_issues(project=<project>) if Linear MCP available).
Use AskUserQuestion:
For a deeper review after deepening, run /plan-eng-review or /plan-design-review standalone.
If Linear issues exist:
Question: "Plan deepened. What next?"
Options:
git diff [plan_path]/multi-review — Feedback from reviewers/dispatch — Spawn parallel workers/start-task <id> — Begin a specific taskIf no Linear issues exist:
Question: "Plan deepened. What next?"
Options:
git diff [plan_path]/multi-review — Feedback from reviewers