Use when you have an idea, goal, or feature description and need to turn it into an actionable plan with tasks
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: <title>".
# 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:
Google Workspace CLI for Gmail, Calendar, Drive, Contacts, Sheets, and Docs.
Manage Apple Notes via the `memo` CLI on macOS (create, view, edit, delete, search, move, and export notes). Use when a user asks OpenClaw to add a note, list notes, search notes, or manage note folders.
Work with Obsidian vaults (plain Markdown notes) and automate via obsidian-cli.
Use when you need to control Slack from OpenClaw via the slack tool, including reacting to messages or pinning/unpinning items in Slack channels or DMs.
Manage Apple Reminders via remindctl CLI (list, add, edit, complete, delete). Supports lists, date filters, and JSON/plain output.
Manage Trello boards, lists, and cards via the Trello REST API.
Category:productivity