
Plan Task
- 922 installs
- 1.3k repo stars
- Updated July 26, 2026
- neolabhq/context-engineering-kit
plan-task is an agent skill that turns vague task files into testable acceptance criteria and complete scope using a scratchpad-first business analysis workflow for developers who need spec quality before coding.
About
plan-task is a neolabhq/context-engineering-kit skill that analyzes business requirements and rewrites task files with comprehensive, testable acceptance criteria. The workflow gathers all findings in a scratchpad first, then copies only verified details into the task file so vague prompts do not reach implementation. Developers and tech leads invoke plan-task when tickets lack measurable success conditions, scope boundaries, or verifiable outcomes that engineers can test. The skill explicitly warns that untestable criteria and incomplete scope cause rework, positioning the agent as accountable for specification quality before any code changes.
- Scratchpad-first mandate: create .specs/scratchpad via create-scratchpad.sh before any analysis
- Four analysis phases: requirements discovery, concept extraction, requirements analysis, draft consolidation
- Explicit quality bar: no vague, untestable, or incomplete specifications
- Acceptance criteria oriented so developers know what to build and how success is measured
- Selective promotion from scratchpad into the task file after verification
Plan Task by the numbers
- 922 all-time installs (skills.sh)
- +52 installs in the week ending Jul 28, 2026 (Skillselion tracking)
- Ranked #514 of 3,301 Productivity & Planning skills by installs in the Skillselion catalog
- Security screen: LOW risk (skills.sh audit)
- Data as of Jul 28, 2026 (Skillselion catalog sync)
npx skills add https://github.com/neolabhq/context-engineering-kit --skill plan-taskAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 922 |
|---|---|
| repo stars | ★ 1.3k |
| Security audit | 3 / 3 scanners passed |
| Last updated | July 26, 2026 |
| Repository | neolabhq/context-engineering-kit ↗ |
How do you write testable acceptance criteria for tasks?
Turn a vague task file into testable acceptance criteria and complete scope using a scratchpad-first business analysis workflow.
Who is it for?
Tech leads and developers who receive underspecified task files and need agent-assisted acceptance criteria before sprint work starts.
Skip if: Teams that already maintain formal PRDs with signed test plans and do not use lightweight task markdown files.
When should I use this skill?
A developer provides a vague task file and asks for acceptance criteria, scope completion, or business requirements analysis.
What you get
Updated task file, scratchpad analysis notes, and explicit acceptance criteria with complete scope boundaries.
- Acceptance criteria list
- Refined task file
Files
Refine Task Workflow
Role
You are a task refinement orchestrator. Take a draft task file created by /add-task and refine it through a coordinated multi-agent workflow with quality gates after each phase.
Goal
This workflow command refines an existing draft task through:
1. Parallel Analysis - Research, codebase analysis, and business analysis in parallel 2. Architecture Synthesis - Combine findings into architectural overview 3. Decomposition - Break into implementation steps with risks 4. Parallelize - Reorganize steps for maximum parallel execution 5. Verify - Add LLM-as-Judge verification sections 6. Promote - Move refined task from draft/ to todo/
All phases include judge validation to prevent error propagation and ensure quality thresholds are met.
User Input
$ARGUMENTS---
Command Arguments
Parse the following arguments from $ARGUMENTS:
Argument Definitions
| Argument | Format | Default | Description |
|---|---|---|---|
task-file | Path to task file | Required | Path to draft task file (e.g., .specs/tasks/draft/add-validation.feature.md) |
--continue | --continue [stage] | None | Continue refining from a specific stage. Stage is optional - resolve from context if not provided. |
--target-quality | --target-quality X.X | 3.5 | Target threshold value (out of 5.0) for judge pass/fail decisions. |
--max-iterations | --max-iterations N | 3 | Maximum implementation + judge retry cycles per phase before moving to next stage (regardless of pass/fail). |
--included-stages | --included-stages stage1,stage2,... | All stages | Comma-separated list of stages to include. |
--skip | --skip stage1,stage2,... | None | Comma-separated list of stages to exclude. |
--fast | --fast | N/A | Alias for --target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition,verifications |
--one-shot | --one-shot | N/A | Alias for --included-stages business analysis,decomposition --skip-judges - minimal refinement without quality gates. |
--human-in-the-loop | --human-in-the-loop phase1,phase2,... | None | Phases after which to pause for human verification. |
--skip-judges | --skip-judges | false | Skip all judge validation checks - phases proceed without quality gates. |
--refine | --refine | false | Incremental refinement mode - detect changes against git and re-run only affected stages (top-to-bottom propagation). |
Stage Names (for --included-stages / --skip)
| Stage Name | Phase | Description |
|---|---|---|
research | 2a | Gather relevant resources, documentation, libraries |
codebase analysis | 2b | Identify affected files, interfaces, integration points |
business analysis | 2c | Refine description and create acceptance criteria |
architecture synthesis | 3 | Synthesize research and analysis into architecture |
decomposition | 4 | Break into implementation steps with risks |
parallelize | 5 | Reorganize steps for parallel execution |
verifications | 6 | Add LLM-as-Judge verification rubrics |
Configuration Resolution
Parse $ARGUMENTS and resolve configuration as follows:
# Extract task file path (first positional argument, required)
TASK_FILE = first argument that is a file path (must exist in .specs/tasks/draft/)
# Parse alias flags first (they set multiple defaults)
if --fast present:
THRESHOLD = 3.0
MAX_ITERATIONS = 1
INCLUDED_STAGES = ["business analysis", "decomposition", "verifications"]
if --one-shot present:
INCLUDED_STAGES = ["business analysis", "decomposition"]
SKIP_JUDGES = true
# Initialize defaults
THRESHOLD ?= --target-quality || 3.5
MAX_ITERATIONS ?= --max-iterations || 3
INCLUDED_STAGES ?= --included-stages || ["research", "codebase analysis", "business analysis", "architecture synthesis", "decomposition", "parallelize", "verifications"]
SKIP_STAGES = --skip || []
HUMAN_IN_THE_LOOP_PHASES = --human-in-the-loop || []
SKIP_JUDGES = --skip-judges || false
REFINE_MODE = --refine || false
CONTINUE_STAGE = null
if --continue [stage] present:
CONTINUE_STAGE = stage or resolve from context
# Compute final active stages
ACTIVE_STAGES = INCLUDED_STAGES - SKIP_STAGESContext Resolution for --continue
When --continue is used without explicit stage:
1. Stage Resolution:
- Parse the task file for completion markers (e.g.,
[x]checkboxes) - Identify the last completed phase/judge
- Resume from the next incomplete phase
Refine Mode Behavior (--refine)
When --refine is used:
1. Change Detection:
- First check file status:
git status --porcelain -- <TASK_FILE> - Compare current task file against last git commit:
git diff HEAD -- <TASK_FILE> - This captures both staged and unstaged changes vs HEAD
- If file is untracked or has no git history, compare against the original task structure
- Identify which sections have been modified by the user
- Look for
//comment markers indicating user feedback/corrections
2. Top-to-Bottom Propagation:
- Determine the earliest modified section (highest in document)
- Re-run only stages that correspond to or come after the modified section
- Earlier stages (above the modification) are preserved as-is
3. Section-to-Stage Mapping:
| Modified Section | Re-run From Stage |
|---|---|
| Description / Acceptance Criteria | business analysis (Phase 2c) |
| Architecture Overview | architecture synthesis (Phase 3) |
| Implementation Process / Steps | decomposition (Phase 4) |
| Parallelization / Dependencies | parallelize (Phase 5) |
| Verification sections | verifications (Phase 6) |
4. Refine Execution:
- Skip research (2a) and codebase analysis (2b) unless explicitly requested
- Pass user modifications and
//comments as additional context to agents - Agents should incorporate user feedback while preserving unchanged content
5. Example:
# User edited the Architecture Overview section
/plan .specs/tasks/todo/my-task.feature.md --refine
# Detects Architecture section changed → re-runs from Phase 3 onwards
# Skips: research, codebase analysis, business analysis
# Runs: architecture synthesis, decomposition, parallelize, verificationsHuman-in-the-Loop Behavior
Human verification checkpoints occur:
1. Trigger Conditions:
- After implementation + judge verification PASS for a phase in
HUMAN_IN_THE_LOOP_PHASES - After implementation + judge + implementation retry (before the next judge retry)
2. At Checkpoint:
- Display current phase results summary
- Display generated artifacts with paths
- Display judge score and feedback
- Ask user: "Review phase output. Continue? [Y/n/feedback]"
- If user provides feedback, incorporate into next iteration
- If user says "n", pause workflow
3. Checkpoint Message Format:
---
## 🔍 Human Review Checkpoint - Phase X
**Phase:** {phase name}
**Judge Score:** {score}/{THRESHOLD} threshold
**Status:** ✅ PASS / ⚠️ RETRY {n}/{MAX_ITERATIONS}
**Artifacts:**
- {artifact_path_1}
- {artifact_path_2}
**Judge Feedback:**
{feedback summary}
**Action Required:** Review the above artifacts and provide feedback or continue.
> Continue? [Y/n/feedback]:
------
Usage Examples
# Refine a draft task with all stages
/plan .specs/tasks/draft/add-validation.feature.md
# Fast refinement with minimal stages
/plan .specs/tasks/draft/quick-fix.bug.md --fast
# Continue from a specific stage
/plan .specs/tasks/draft/complex-feature.feature.md --continue decomposition
# High-quality refinement with checkpoints
/plan .specs/tasks/draft/critical-api.feature.md --target-quality 4.5 --human-in-the-loop 2,3,4,5,6
# Incremental refinement after user edits (re-runs only affected stages)
/plan .specs/tasks/todo/my-task.feature.md --refinePre-Flight Checks
Before starting workflow:
1. Validate task file exists:
- If
REFINE_MODEis false: Check thatTASK_FILEexists in.specs/tasks/draft/ - If
REFINE_MODEis true: Check thatTASK_FILEexists in.specs/tasks/todo/or.specs/tasks/draft/ - If not found, show error and exit
2. Parse and display resolved configuration:
### Configuration
| Setting | Value |
|---------|-------|
| **Task File** | {TASK_FILE} |
| **Target Quality** | {THRESHOLD}/5.0 |
| **Max Iterations** | {MAX_ITERATIONS} |
| **Active Stages** | {ACTIVE_STAGES as comma-separated list} |
| **Human Checkpoints** | Phase {HUMAN_IN_THE_LOOP_PHASES as comma-separated} |
| **Skip Judges** | {SKIP_JUDGES} |
| **Refine Mode** | {REFINE_MODE} |
| **Continue From** | {CONTINUE_STAGE} or "Start" |3. Handle `--continue` mode:
If CONTINUE_STAGE is set:
- Read the task file to get current state
- Identify completed phases from task file content
- Skip to
CONTINUE_STAGE(or auto-detected next incomplete stage) - Pre-populate captured values from existing artifacts
- Resume workflow from the appropriate phase
4. Handle `--refine` mode:
If REFINE_MODE is true:
- Check file status:
git status --porcelain -- <TASK_FILE> M(staged) orM(unstaged) orMM(both) → proceed with diff??(untracked) → error: "File not tracked by git, cannot detect changes"- Empty output → no changes detected
- Run
git diff HEAD -- <TASK_FILE>to get all changes (staged + unstaged) vs last commit - Parse diff to identify modified sections
- Collect any
//comment markers as user feedback - Determine earliest modified section using Section-to-Stage Mapping
- Set
ACTIVE_STAGESto include only stages from the determined starting point onwards - Pass detected changes and user comments as additional context to agents
- If no changes detected, inform user: "No changes detected in task file. Edit the file first, then run --refine." and exit
5. Extract task info from file:
- Read task file to extract title and type from filename
- Parse frontmatter for title and depends_on
6. Initialize workflow progress tracking using TodoWrite:
Only include todos for phases in ACTIVE_STAGES. If continuing, mark completed phases as completed.
{
"todos": [
{"content": "Ensure directories exist", "status": "pending", "activeForm": "Ensuring directories exist"},
{"content": "Phase 2a: Research relevant resources and documentation", "status": "pending", "activeForm": "Researching resources"},
{"content": "Judge 2a: PASS research quality (> {THRESHOLD})", "status": "pending", "activeForm": "Validating research"},
{"content": "Phase 2b: Analyze codebase impact and affected files", "status": "pending", "activeForm": "Analyzing codebase impact"},
{"content": "Judge 2b: PASS codebase analysis (> {THRESHOLD})", "status": "pending", "activeForm": "Validating codebase analysis"},
{"content": "Phase 2c: Business analysis and acceptance criteria", "status": "pending", "activeForm": "Analyzing business requirements"},
{"content": "Judge 2c: PASS business analysis (> {THRESHOLD})", "status": "pending", "activeForm": "Validating business analysis"},
{"content": "Phase 3: Architecture synthesis from research and analysis", "status": "pending", "activeForm": "Synthesizing architecture"},
{"content": "Judge 3: PASS architecture synthesis (> {THRESHOLD})", "status": "pending", "activeForm": "Validating architecture"},
{"content": "Phase 4: Decompose into implementation steps", "status": "pending", "activeForm": "Decomposing into steps"},
{"content": "Judge 4: PASS decomposition (> {THRESHOLD})", "status": "pending", "activeForm": "Validating decomposition"},
{"content": "Phase 5: Parallelize implementation steps", "status": "pending", "activeForm": "Parallelizing steps"},
{"content": "Judge 5: PASS parallelization (> {THRESHOLD})", "status": "pending", "activeForm": "Validating parallelization"},
{"content": "Phase 6: Define verification rubrics", "status": "pending", "activeForm": "Defining verifications"},
{"content": "Judge 6: PASS verifications (> {THRESHOLD})", "status": "pending", "activeForm": "Validating verifications"},
{"content": "Move task to todo folder", "status": "pending", "activeForm": "Promoting task"},
{"content": "Human checkpoint reviews", "status": "pending", "activeForm": "Awaiting human review"}
]
}Note: Filter todos based on configuration:
- If
SKIP_JUDGESis true, omit ALL Judge todos (Judge 2a, 2b, 2c, 3, 4, 5, 6) - If
researchnot inACTIVE_STAGES, omit Phase 2a and Judge 2a todos - If
codebase analysisnot inACTIVE_STAGES, omit Phase 2b and Judge 2b todos - If
business analysisnot inACTIVE_STAGES, omit Phase 2c and Judge 2c todos - If
architecture synthesisnot inACTIVE_STAGES, omit Phase 3 and Judge 3 todos - If
decompositionnot inACTIVE_STAGES, omit Phase 4 and Judge 4 todos - If
parallelizenot inACTIVE_STAGES, omit Phase 5 and Judge 5 todos - If
verificationsnot inACTIVE_STAGES, omit Phase 6 and Judge 6 todos - If
HUMAN_IN_THE_LOOP_PHASESis empty, omit human checkpoint todo
7. Ensure directories exist:
Run the folder creation script to create task directories and configure gitignore:
bash ${CLAUDE_PLUGIN_ROOT}/scripts/create-folders.shThis creates:
.specs/tasks/draft/- New tasks awaiting analysis.specs/tasks/todo/- Tasks ready to implement.specs/tasks/in-progress/- Currently being worked on.specs/tasks/done/- Completed tasks.specs/scratchpad/- Temporary working files (gitignored).specs/analysis/- Codebase impact analysis files.claude/skills/- Reusable skill documents
Update each todo to in_progress when starting a phase and completed when judge passes.
CRITICAL
- Do not mark PASS for any judge if it did not pass the rubric. Retry the judge after each implementation change till it passes the check!
- Do not read task files in .claude or .specs directories, your job is orchestrate agents that will do the work, not do it by yourself!
- Use
THRESHOLD(default 3.5) for all judge pass/fail decisions, not hardcoded values! - Use
MAX_ITERATIONS(default 3) for retry limits, not hardcoded values! - After `MAX_ITERATIONS` reached: PROCEED to next stage automatically - do NOT ask user unless phase is in `HUMAN_IN_THE_LOOP_PHASES`!
- Skip phases not in
ACTIVE_STAGESentirely - do not launch agents for excluded stages! - Trigger human-in-the-loop checkpoints ONLY after phases in
HUMAN_IN_THE_LOOP_PHASES! - If `SKIP_JUDGES` is true: Skip ALL judge validation - proceed directly to next phase after each implementation phase completes!
- Task file must exist in `.specs/tasks/draft/` before running this command (unless `--refine` mode)!
- If `REFINE_MODE` is true: Detect changes via git diff, skip unchanged stages, pass user feedback to agents!
Execution & Evaluation Rules
- Use foreground agents only: Do not use background agents. Launch parallel agents when possible. Background agents constantly run in permissions issues and other errors.
Relaunch judge till you get valid results, of following happens:
- Reject Long Reports: If an agent returns a very long report instead of using the scratchpad as requested, reject the result. This indicates the agent failed to follow the "use scratchpad" instruction.
- Judge Score 5.0 is a Hallucination: If a judge returns a score of 5.0/5.0, treat it as a hallucination or lazy evaluation. Reject it and re-run the judge. Perfect scores are practically impossible in this rigorous framework.
- Reject Missing Scores: If a judge report is missing the numerical score, reject it. This indicates the judge failed to read or follow the rubric instructions.
Workflow Execution
You MUST launch for each step a separate agent, instead of performing all steps yourself.
CRITICAL: For each agent you MUST:
1. Use the Agent type and Model specified in the step 2. Provide the task file path and user input as context 3. Provide the value of `${CLAUDE_PLUGIN_ROOT}` so agents can resolve paths like `@${CLAUDE_PLUGIN_ROOT}/scripts/create-scratchpad.sh` 4. Require agent to implement exactly that step, not more, not less 5. After each sub-phase, launch a judge agent to validate quality before proceeding
Complete Workflow Overview
Note: Phases not in ACTIVE_STAGES are skipped. If SKIP_JUDGES is true, all judge steps are skipped entirely. Human checkpoints (🔍) occur after phases in HUMAN_IN_THE_LOOP_PHASES.
Input: Draft Task File (.specs/tasks/draft/*.md)
│
▼
Phase 2: Parallel Analysis
│
├─────────────────────┬─────────────────────┐
▼ ▼ ▼
Phase 2a: Phase 2b: Phase 2c:
Research Codebase Analysis Business Analysis
[sdd:researcher sonnet] [sdd:code-explorer sonnet] [sdd:business-analyst opus]
Judge 2a Judge 2b Judge 2c
(pass: >THRESHOLD) (pass: >THRESHOLD) (pass: >THRESHOLD)
│ │ │
└─────────────────────┴─────────────────────┘
│
▼
Phase 3: Architecture Synthesis
[sdd:software-architect opus]
Judge 3 (pass: >THRESHOLD)
│
▼
Phase 4: Decomposition
[sdd:tech-lead opus]
Judge 4 (pass: >THRESHOLD)
│
▼
Phase 5: Parallelize
[sdd:team-lead opus]
Judge 5 (pass: >THRESHOLD)
│
▼
Phase 6: Verifications
[sdd:qa-engineer opus]
Judge 6 (pass: >THRESHOLD)
│
▼
Move task: draft/ → todo/
│
▼
Complete---
Phase 2: Parallel Analysis
Phase 2 launches three analysis phases in parallel, each with its own judge validation.
Phase 2a/2b/2c: Parallel Sub-Phases
Launch these three phases in parallel immediately:
---
Phase 2a: Research
Model: sonnet Agent: sdd:researcher Depends on: Task file exists Purpose: Gather relevant resources, documentation, libraries, and prior art. Creates or updates a reusable skill.
Launch agent:
- Description: "Research task resources and create/update skill"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Task File: <TASK_FILE>
Task Title: <title from task file>
CRITICAL: DO NOT OUTPUT YOUR RESEARCH, ONLY CREATE THE SCRATCHPAD AND SKILL FILE.Capture:
- Skill file path (e.g.,
.claude/skills/<skill-name>/SKILL.md) - Skill action (Created new / Updated existing)
- Scratchpad file path (e.g.,
.specs/scratchpad/<hex-id>.md) - Number of resources gathered
- Key recommendation summary
CRITICAL: If expected files not created, launch the agent again with the same prompt.
---
Phase 2b: Codebase Impact Analysis
Model: sonnet Agent: sdd:code-explorer Depends on: Task file exists Purpose: Identify affected files, interfaces, and integration points
Launch agent:
- Description: "Analyze codebase impact"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Task File: <TASK_FILE>
Task Title: <title from task file>
CRITICAL: DO NOT OUTPUT YOUR ANALYSIS, ONLY CREATE THE SCRATCHPAD AND ANALYSIS FILE.Capture:
- Analysis file path (e.g.,
.specs/analysis/analysis-{name}.md) - Scratchpad file path (e.g.,
.specs/scratchpad/<hex-id>.md) - Files affected count (modify/create/delete)
- Risk level assessment
- Key integration points
CRITICAL: If expected files not created, launch the agent again with the same prompt.
---
Phase 2c: Business Analysis
Model: opus Agent: sdd:business-analyst Depends on: Task file exists Purpose: Refine description and create acceptance criteria
Launch agent:
- Description: "Business analysis"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Read ${CLAUDE_PLUGIN_ROOT}/skills/plan-task/analyse-business-requirements.md and execute it exactly as is!
Task File: <TASK_FILE>
Task Title: <title from task file>
CRITICAL: DO NOT OUTPUT YOUR BUSINESS ANALYSIS, ONLY CREATE THE SCRATCHPAD AND UPDATE THE TASK FILE.Capture:
- Scratchpad file path (e.g.,
.specs/scratchpad/<hex-id>.md) - Acceptance criteria count
- Scope defined (yes/no)
- User scenarios documented
---
Judge 2a/2b/2c: Validate Parallel Phases
After each parallel phase completes, launch its respective judge with the same agent type and model.
Judge 2a: Validate Research/Skill
Model: sonnet Agent: sdd:researcher Depends on: Phase 2a completion Purpose: Validate skill completeness and relevance
Launch judge:
- Description: "Judge skill quality"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
### Artifact Path
{path to skill file from Phase 2a}
### Context
This is a skill document for task: {task title}. Evaluate comprehensiveness and reusability.
### Rubric
1. Resource Coverage (weight: 0.30)
- Documentation and references gathered?
- Libraries and tools identified with recommendations?
- 1=Missing critical resources, 2=Basic coverage, 3=Adequate, 4=Comprehensive, 5=Excellent
2. Pattern Relevance (weight: 0.25)
- Are identified patterns applicable?
- Are recommendations actionable?
- 1=Irrelevant, 2=Somewhat useful, 3=Adequate, 4=Well-targeted, 5=Perfect fit
3. Issue Anticipation (weight: 0.20)
- Common pitfalls identified with solutions?
- 1=None identified, 2=Few issues, 3=Adequate, 4=Good coverage, 5=Comprehensive
4. Reusability (weight: 0.15)
- Is the skill general enough to help multiple tasks?
- Does it avoid task-specific details?
- 1=Too specific, 2=Limited reuse, 3=Adequate, 4=Good, 5=Highly reusable
5. Task Integration (weight: 0.10)
- Was task file updated with skill reference?
- 1=Not updated, 3=Updated, 5=Updated with clear instructionsCRITICAL: use prompt exactly as is, do not add anything else. Including output of implementation agent!!!
Decision Logic:
- PASS (score >=
THRESHOLD): Research complete, proceed - FAIL (score <
THRESHOLD): Re-launch Phase 2a with feedback - MAX_ITERATIONS reached: Proceed to next stage regardless of score (log warning)
---
Judge 2b: Validate Codebase Analysis
Model: sonnet Agent: sdd:code-explorer Depends on: Phase 2b completion Purpose: Validate file identification accuracy and integration mapping
Launch judge:
- Description: "Judge codebase analysis quality"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
### Artifact Path
{path to analysis file from Phase 2b}
### Context
This is codebase impact analysis for task: {task title}. Evaluate accuracy and completeness.
### Rubric
1. File Identification Accuracy (weight: 0.35)
- All affected files identified with specific paths?
- New files and modifications distinguished?
- 1=Major files missing, 2=Mostly correct, 3=Adequate, 4=Precise, 5=Complete
2. Interface Documentation (weight: 0.25)
- Key functions/classes documented with signatures?
- Change requirements clear?
- 1=Missing, 2=Partial, 3=Adequate, 4=Good, 5=Complete
3. Integration Point Mapping (weight: 0.25)
- Integration points identified with impact?
- Similar patterns in codebase found?
- 1=Missing, 2=Partial, 3=Adequate, 4=Good, 5=Comprehensive
4. Risk Assessment (weight: 0.15)
- High risk areas identified with mitigations?
- 1=No assessment, 2=Basic, 3=Adequate, 4=Good, 5=ThoroughCRITICAL: use prompt exactly as is, do not add anything else. Including output of implementation agent!!!
Decision Logic:
- PASS (score >=
THRESHOLD): Analysis complete, proceed - FAIL (score <
THRESHOLD): Re-launch Phase 2b with feedback - MAX_ITERATIONS reached: Proceed to next stage regardless of score (log warning)
---
Judge 2c: Validate Business Analysis
Model: opus Agent: sdd:business-analyst Depends on: Phase 2c completion Purpose: Validate acceptance criteria quality and scope definition
Launch judge:
- Description: "Judge business analysis quality"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
### Artifact Path
{path to task file from Phase 2c}
### Context
This is business analysis output. Evaluate description clarity and acceptance criteria quality.
### Rubric
1. Description Clarity (weight: 0.30)
- What/Why clearly explained?
- Scope boundaries defined?
- 1=Vague, 2=Basic, 3=Adequate, 4=Clear, 5=Excellent
2. Acceptance Criteria Quality (weight: 0.35)
- Criteria specific and testable?
- Given/When/Then format for complex criteria?
- 1=Missing/vague, 2=Basic, 3=Adequate, 4=Good, 5=Excellent
3. Scenario Coverage (weight: 0.20)
- Primary flow documented?
- Error scenarios considered?
- 1=Missing, 2=Basic, 3=Adequate, 4=Good, 5=Comprehensive
4. Scope Definition (weight: 0.15)
- In-scope/out-of-scope explicit?
- No implementation details in description?
- 1=Missing, 2=Partial, 3=Adequate, 4=Good, 5=ClearCRITICAL: use prompt exactly as is, do not add anything else. Including output of implementation agent!!!
Decision Logic:
- PASS (score >=
THRESHOLD): Business analysis complete, proceed - FAIL (score <
THRESHOLD): Re-launch Phase 2c with feedback - MAX_ITERATIONS reached: Proceed to next stage regardless of score (log warning)
---
Synchronization Point
Wait for ALL three parallel phases (2a, 2b, 2c) AND their judges to PASS before proceeding to Phase 3.
---
Phase 3: Architecture Synthesis
Model: opus Agent: sdd:software-architect Depends on: Phase 2a + Judge 2a PASS, Phase 2b + Judge 2b PASS, Phase 2c + Judge 2c PASS Purpose: Synthesize research, analysis, and business requirements into architectural overview
Launch agent:
- Description: "Architecture synthesis"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Task File: <TASK_FILE>
Skill File: <skill file path from Phase 2a>
Analysis File: <analysis file path from Phase 2b>
CRITICAL: DO NOT OUTPUT YOUR ARCHITECTURE SYNTHESIS, ONLY CREATE THE SCRATCHPAD AND UPDATE THE TASK FILE.Capture:
- Scratchpad file path (e.g.,
.specs/scratchpad/<hex-id>.md) - Sections added to task file
- Key architectural decisions count
- Components identified (if applicable)
- Contracts defined (if applicable)
---
Judge 3: Validate Architecture Synthesis
Model: opus Agent: sdd:software-architect Depends on: Phase 3 completion Purpose: Validate architectural coherence and completeness
Launch judge:
- Description: "Judge architecture synthesis quality"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
### Artifact Path
{path to task file after Phase 3}
### Context
This is architecture synthesis output. The Architecture Overview section should contain
solution strategy, key decisions, and only relevant architectural sections.
### Rubric
1. Solution Strategy Clarity (weight: 0.30)
- Approach clearly explained?
- Key decisions documented with reasoning?
- Trade-offs stated?
- 1=Missing/unclear, 2=Basic, 3=Adequate, 4=Clear, 5=Excellent
2. Reference Integration (weight: 0.20)
- Links to research and analysis files?
- Insights from both integrated?
- 1=No links, 2=Partial, 3=Adequate, 4=Good, 5=Fully integrated
3. Section Relevance (weight: 0.25)
- Only relevant sections included (not all)?
- Sections appropriate for task complexity?
- 1=Wrong sections, 2=Mostly appropriate, 3=Adequate, 4=Good, 5=Precisely targeted
4. Expected Changes Accuracy (weight: 0.25)
- Files to create/modify listed?
- Consistent with codebase analysis?
- 1=Missing/inconsistent, 2=Partial, 3=Adequate, 4=Good, 5=Complete
CRITICAL: use prompt exactly as is, do not add anything else. Including output of implementation agent!!!
Decision Logic:
- PASS (score >=
THRESHOLD): Architecture synthesis complete, proceed - FAIL (score <
THRESHOLD): Re-launch Phase 3 with feedback - MAX_ITERATIONS reached: Proceed to Phase 4 regardless of score (log warning)
Wait for PASS before Phase 4.
---
Phase 4: Decomposition
Model: opus Agent: sdd:tech-lead Depends on: Phase 3 + Judge 3 PASS Purpose: Break architecture into implementation steps with success criteria and risks
Launch agent:
- Description: "Decompose into implementation steps"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Task File: <TASK_FILE>
CRITICAL: DO NOT OUTPUT YOUR DECOMPOSITION, ONLY CREATE THE SCRATCHPAD AND UPDATE THE TASK FILE.Capture:
- Scratchpad file path (e.g.,
.specs/scratchpad/<hex-id>.md) - Implementation steps count
- Total subtasks count
- Critical path steps
- High priority risks count
---
Judge 4: Validate Decomposition
Model: opus Agent: sdd:tech-lead Depends on: Phase 4 completion Purpose: Validate implementation steps quality and completeness
Launch judge:
- Description: "Judge decomposition quality"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
### Artifact Path
{path to task file after Phase 4}
### Context
This is decomposition output. The Implementation Process section should contain
ordered steps with success criteria, subtasks, blockers, and risks.
### Rubric
1. Step Quality (weight: 0.30)
- Each step has clear goal, output, success criteria?
- Steps ordered by dependency?
- No step too large (>Large estimate)?
- 1=Vague/missing, 2=Basic, 3=Adequate, 4=Good, 5=Excellent
2. Success Criteria Testability (weight: 0.25)
- Criteria specific and verifiable?
- Use actual file paths, function names?
- Subtasks clearly defined with actionable descriptions?
- 1=Vague, 2=Partially testable, 3=Adequate, 4=Good, 5=All testable
3. Risk Coverage (weight: 0.25)
- Blockers identified with resolutions?
- Risks identified with mitigations?
- High-risk tasks identified with decomposition recommendations?
- 1=None, 2=Basic, 3=Adequate, 4=Good, 5=Comprehensive
4. Completeness (weight: 0.20)
- All architecture components have corresponding steps?
- Implementation summary table present?
- Definition of Done included?
- Phases organized: Setup → Foundational → User Stories → Polish?
- 1=Incomplete, 2=Partial, 3=Adequate, 4=Good, 5=CompleteCRITICAL: use prompt exactly as is, do not add anything else. Including output of implementation agent!!!
Decision Logic:
- PASS (score >=
THRESHOLD): Decomposition complete, proceed to Phase 5 - FAIL (score <
THRESHOLD): Re-launch Phase 4 with feedback - MAX_ITERATIONS reached: Proceed to Phase 5 regardless of score (log warning)
Wait for PASS before Phase 5.
---
Phase 5: Parallelize Steps
Model: opus Agent: sdd:team-lead Depends on: Phase 4 + Judge 4 PASS Purpose: Reorganize implementation steps for maximum parallel execution
Launch agent:
- Description: "Parallelize implementation steps"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Task File: <TASK_FILE>
Use agents only from this list: {list ALL available agents with plugin prefix if available, e.g. sdd:developer, review:bug-hunter. Also include general agents: opus, sonnet, haiku}
CRITICAL: DO NOT OUTPUT YOUR PARALLELIZATION, ONLY CREATE THE SCRATCHPAD AND UPDATE THE TASK FILE.Capture:
- Scratchpad file path (e.g.,
.specs/scratchpad/<hex-id>.md) - Number of steps reorganized
- Maximum parallelization depth
- Agent distribution summary
---
Judge 5: Validate Parallelization
Model: opus Agent: sdd:team-lead Depends on: Phase 5 completion Purpose: Validate dependency accuracy and parallelization optimization
Launch judge:
- Description: "Judge parallelization quality"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
### Artifact Path
{path to parallelized task file from Phase 5}
### Context
This is the output of Phase 5: Parallelize Steps. The artifact should contain implementation steps
reorganized for maximum parallel execution with explicit dependencies, agent assignments, and
parallelization diagram.
Use agents only from this list: {list ALL available agents with plugin prefix if available, e.g. sdd:developer, review:bug-hunter. Also include general agents: opus, sonnet, haiku}
### Rubric
1. Dependency Accuracy (weight: 0.35)
- Are step dependencies correctly identified?
- No false dependencies (steps marked dependent when they're not)?
- No missing dependencies (steps that actually depend on others)?
- 1=Major dependency errors, 2=Mostly correct, 3=Acceptable, 5=Precise dependencies
2. Parallelization Maximized (weight: 0.30)
- Are parallelizable steps correctly marked with "Parallel with:"?
- Is the parallelization diagram logical?
- 1=No parallelization/wrong, 2=Some optimization, 3=Acceptable, 5=Maximum parallelization
3. Agent Selection Correctness (weight: 0.20)
- Are agent types appropriate for outputs (opus by default, haiku for trivial, sonnet for simple but high in volume)?
- Does selection follow the Agent Selection Guide?
- Are only agents from the provided available agents list used?
- 1=Wrong agents, 2=Mostly appropriate, 3=Acceptable, 4=Optimal selection, 5=Perfect selection
4. Execution Directive Present (weight: 0.15)
- Is the sub-agent execution directive present?
- Are "MUST" requirements for parallel execution clear?
- 1=Missing directive, 2=Partial, 3=Acceptable, 4=Complete directive, 5=Perfect directiveCRITICAL: use prompt exactly as is, do not add anything else. Including output of implementation agent!!!
Decision Logic:
- PASS (score >=
THRESHOLD): Proceed to Phase 6 - FAIL (score <
THRESHOLD): Re-launch Phase 5 with feedback - MAX_ITERATIONS reached: Proceed to Phase 6 regardless of score (log warning)
Wait for PASS before Phase 6.
---
Phase 6: Define Verifications
Model: opus Agent: sdd:qa-engineer Depends on: Phase 5 + Judge 5 PASS Purpose: Add LLM-as-Judge verification sections with rubrics
Launch agent:
- Description: "Define verification rubrics"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Task File: <TASK_FILE>
CRITICAL: DO NOT OUTPUT YOUR VERIFICATIONS, ONLY CREATE THE SCRATCHPAD AND UPDATE THE TASK FILE.Capture:
- Scratchpad file path (e.g.,
.specs/scratchpad/<hex-id>.md) - Number of steps with verification
- Total evaluations defined
- Verification breakdown (Panel/Per-Item/None)
---
Judge 6: Validate Verifications
Model: opus Agent: sdd:qa-engineer Depends on: Phase 6 completion Purpose: Validate verification rubrics and thresholds
Launch judge:
- Description: "Judge verification quality"
- Prompt:
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}
Read @${CLAUDE_PLUGIN_ROOT}/prompts/judge.md for evaluation methodology and execute.
### Artifact Path
{path to task file with verifications from Phase 6}
### Context
This is the output of Phase 6: Define Verifications. The artifact should contain LLM-as-Judge
verification sections for each implementation step, including verification levels, custom rubrics,
thresholds, and a verification summary table.
### Rubric
1. Verification Level Appropriateness (weight: 0.25)
- Do verification levels match artifact criticality?
- HIGH criticality → Panel, MEDIUM → Single/Per-Item, LOW/NONE → None?
- 1=Mismatched levels, 2=Mostly appropriate, 3=Acceptable, 5=Precisely calibrated
2. Rubric Quality (weight: 0.20)
- Are criteria specific to the artifact type (not generic)?
- Do weights sum to 1.0?
- Are descriptions clear and measurable?
- 1=Generic/broken rubrics, 2=Adequate, 3=Acceptable, 5=Excellent custom rubrics
3. Threshold Appropriateness (weight: 0.15)
- Are thresholds reasonable (typically 4.0/5.0)?
- Higher for critical, lower for experimental?
- 1=Wrong thresholds, 2=Standard applied, 3=Acceptable, 5=Context-appropriate
4. Coverage Completeness (weight: 0.20)
- Does every step have a Verification section?
- Is the Verification Summary table present?
- 1=Missing verifications, 2=Most covered, 3=Acceptable, 5=100% coverage
5. Test Strategy Coverage (weight: 0.20)
- Does every applicable step (test_strategy.applies = true) have a `**Test Strategy:**` block (Test Matrix table + Test Cases to Cover bullet list)?
- Does each `Test Cases to Cover` cover every acceptance criterion (no orphans)?
- Does the **Test Cases to Cover** list appear under every applicable step and use the format `- [type] description` under each acceptance criterion?
- 1=Missing/empty Test Strategy blocks, 2=Present but Test Cases to Cover orphans or no Test Cases to Cover list, 3=All blocks present, 5=Ideal coverage with full BVA boundaries, and matched bullet list per stepCRITICAL: use prompt exactly as is, do not add anything else. Including output of implementation agent!!!
Decision Logic:
- PASS (score >=
THRESHOLD): Workflow complete, promote task - FAIL (score <
THRESHOLD): Re-launch Phase 6 with feedback - MAX_ITERATIONS reached: Complete workflow regardless of score (log warning)
---
Phase 7: Promote Task
Purpose: Move the refined task from draft to todo folder
After all phases complete:
1. Move task file from draft to todo:
git mv <TASK_FILE> .specs/tasks/todo/
# Fallback if git not available: mv <TASK_FILE> .specs/tasks/todo/2. Update any references in research and analysis files if needed
---
Completion
After all executed phases and judges complete:
1. Use git tool to stage the task file, skill file, analysis file, and scratchpad files (only those that were created) 2. Summarize the workflow results and output to user:
### Task Refined
| Property | Value |
|----------|-------|
| **Original File** | `<original TASK_FILE path>` |
| **Final Location** | `.specs/tasks/todo/<filename>` (ready for implementation) |
| **Title** | `<task title>` |
| **Type** | `<feature/bug/refactor/test/docs/chore/ci>` (from filename) |
| **Skill** | `<skill file path or "Skipped">` |
| **Skill Action** | `<Created new / Updated existing / Skipped>` |
| **Analysis** | `<analysis file path or "Skipped">` |
| **Scratchpad** | `<scratchpad file path>` |
| **Implementation Steps** | `<count or "N/A">` |
| **Parallelization Depth** | `<max parallel agents or "N/A">` |
| **Total Verifications** | `<count or "N/A">` |
### Configuration Used
| Setting | Value |
|---------|-------|
| **Target Quality** | {THRESHOLD}/5.0 |
| **Max Iterations** | {MAX_ITERATIONS} |
| **Active Stages** | {ACTIVE_STAGES as comma-separated list} |
| **Skipped Stages** | {SKIP_STAGES or stages not in ACTIVE_STAGES} |
| **Human Checkpoints** | Phase {HUMAN_IN_THE_LOOP_PHASES as comma-separated} |
| **Skip Judges** | {SKIP_JUDGES} |
| **Refine Mode** | {REFINE_MODE} |
### Quality Gates Summary
| Phase | Judge Score | Verdict |
|-------|-------------|---------|
| Phase 2a: Research | X.X/5.0 | ✅ PASS / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 2b: Codebase Analysis | X.X/5.0 | ✅ PASS / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 2c: Business Analysis | X.X/5.0 | ✅ PASS / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 3: Architecture Synthesis | X.X/5.0 | ✅ PASS / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 4: Decomposition | X.X/5.0 | ✅ PASS / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 5: Parallelize | X.X/5.0 | ✅ PASS / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
| Phase 6: Verify | X.X/5.0 | ✅ PASS / ⚠️ PROCEEDED (max iter) / ⏭️ SKIPPED |
**Threshold Used:** {THRESHOLD}/5.0 (or N/A if SKIP_JUDGES)
**Legend:**
- ✅ PASS - Score >= THRESHOLD
- ⚠️ PROCEEDED (max iter) - Score < THRESHOLD but MAX_ITERATIONS reached, proceeded anyway
- ⏭️ SKIPPED - Stage not in ACTIVE_STAGES
### Artifacts Generated
.claude/ └── skills/ └── <skill-name>/ └── SKILL.md # Reusable skill document (if research stage ran)
.specs/ ├── tasks/ │ ├── draft/ # Draft tasks (source - now empty for this task) │ ├── todo/ │ │ └── <name>.<type>.md # Complete task specification (ready for implementation) │ ├── in-progress/ # Tasks being implemented (empty) │ └── done/ # Completed tasks (empty) ├── analysis/ │ └── analysis-<name>.md # Codebase impact analysis (if codebase analysis stage ran) └── scratchpad/ └── <hex-id>.md # Architecture thinking scratchpad
### Task Status Management
Task status is managed by folder location:
- `draft/` - Tasks created but not yet refined
- `todo/` - Tasks ready for implementation
- `in-progress/` - Tasks currently being worked on
- `done/` - Completed tasks
### Next Steps
1. Review task: `.specs/tasks/todo/<filename>`
- Edit the task file directly to make corrections
- Add `//` comments to lines that need clarification or changes
- Run `/plan` again with `--refine` to incorporate your feedback — it detects changes against git and propagates updates **top-to-bottom** (editing a section only affects sections below it, not above)
2. If everything is fine, begin implementation: `/implement` (will auto-select the task from todo/)---
Error Handling
Phase Agent Failure (Exception/Crash)
If any phase agent fails unexpectedly:
1. Report the failure with agent output 2. Ask clarification questions from user that can help resolve the issue 3. Launch the phase agent again with list of questions and answers to resolve the issue
Judge Returns FAIL
If any judge returns FAIL (score < THRESHOLD):
1. Automatic retry: Re-launch the phase agent with judge feedback 2. Human-in-the-loop check: If phase is in HUMAN_IN_THE_LOOP_PHASES, trigger human checkpoint before the next judge retry (after implementation retry but before re-judging) 3. After `MAX_ITERATIONS` reached: Proceed to next stage automatically (do NOT ask user unless --human-in-the-loop includes this phase) 4. Log warning in completion summary: ⚠️ Phase X did not pass quality threshold (X.X/THRESHOLD) after MAX_ITERATIONS iterations
Retry Flow
Implementation → Judge FAIL → Implementation Retry → Judge Retry
↓
PASS → Continue to next stage
FAIL → Repeat until MAX_ITERATIONS
↓
MAX_ITERATIONS reached → Proceed to next stage (with warning)Retry Flow with Human-in-the-Loop
When phase is in HUMAN_IN_THE_LOOP_PHASES:
Implementation → Judge FAIL → Implementation Retry
↓
🔍 Human Checkpoint (optional feedback)
↓
Judge Retry
↓
PASS → Continue | FAIL → Repeat until MAX_ITERATIONS
↓
MAX_ITERATIONS → 🔍 Final Human Checkpoint
↓
User confirms → Proceed to next stageAnalyse Business Requirements
Goal
Your goal is to refine the task description and create comprehensive acceptance criteria that enable developers to understand exactly what needs to be built and how success will be measured. Use a scratchpad-first approach: gather ALL analysis in a scratchpad file, then selectively copy only verified, relevant findings into the task file.
CRITICAL: Vague requirements cause implementation failures. Untestable criteria waste developer time. Incomplete scope leads to endless rework. YOU are responsible for specification quality. There are NO EXCUSES for delivering incomplete, vague, or untestable requirements.
Input
- Task File: Path to the task file (e.g.,
.specs/tasks/task-{name}.md)
Business Analysis Process
STAGE 1: Setup Scratchpad
MANDATORY: Before ANY analysis, create a scratchpad file for your business analysis thinking.
1. Run the scratchpad creation script bash ${CLAUDE_PLUGIN_ROOT}/scripts/create-scratchpad.sh - it will create the file: .specs/scratchpad/<hex-id>.md 2. Use this file for ALL your discoveries, analysis, and draft sections 3. The scratchpad is your workspace - dump EVERYTHING there first
# Business Analysis Scratchpad: [Task Title]
Task: [task file path]
Created: [date]
---
## Phase 1: Requirements Discovery
[Stage 2 content...]
## Phase 2: Concept Extraction
[Stage 3 findings...]
## Phase 3: Requirements Analysis
[Stage 4 analysis...]
## Phase 4: Draft Output
[Stage 5 synthesis...]
## Self-Critique
[Stage 7 verification...]---
STAGE 2: Requirements Discovery
YOU MUST elicit the true business need behind the request. Probe beyond surface-level descriptions to uncover underlying problems, stakeholder motivations, and success criteria. NEVER accept the first description at face value.
Template for Your Analysis
Use this template to write in scratchpad file:
## Phase 1: Requirements Discovery
### Task Overview
- Initial User Prompt: [quote from task file]
- Current Description: [existing description if any]
- Task Type: [task/bug/feature]
- Complexity: [S/M/L/XL]
### Problem Definition (Step-by-Step Analysis)
Let's think step by step about what the user actually needs...
Step 1: What is the surface-level user request?
[Your analysis]
Step 2: What is the user actually trying to accomplish?
[Your analysis]
Step 3: What is the business value?
[Your analysis]
Step 4: Who benefits from this change and how?
[Your analysis]
Step 5: What features of this solution may be added imidiatly or in future?
[Your analysis]
Step 6: What constraints or considerations exist?
[Your analysis]
Therefore, the root problem is: [Your conclusion]
### Scope
- What is included in this task?
- What is explicitly NOT included?
- What are the boundaries?
### Ambiguous Areas
- [List unclear aspects that need resolution]If input is empty: Stop and report ERROR: "No task description provided"
Examples of Problem Definition Step-by-Step Analysis
Example 1: E-commerce Feature Request:
User Request: "Add a wishlist feature to the product pages"
Let's think step by step about what the user actually needs...
Step 1: What is the surface-level request? The user wants a wishlist feature on product pages. This seems straightforward - a button to save products for later.
Step 2: Why would users need a wishlist? Users browse products but aren't ready to buy immediately. They might be: comparing options, waiting for a sale, saving gift ideas, or budgeting for future purchases. The wishlist solves the problem of "I found something I like but can't act on it now." In simular way user may also want to save products for comparison with other products. Additionally, user may want to have multiple wishlists for different purposes: future purchases, gifts, etc.
Step 3: What is the business value? It not directly allow to increase conversion rate, but it allows to increase customer engagement and retention. Also it allows to know in what products user is interested in and what products are not. As a result it can be used for targeted marketing and sales.
Step 4: What features of this solution may be added imidiatly or in future?
- Add a button to save products for later
- Which can show select with different lists: future purchases, gifts, etc.
- Add a button to save products for comparison
- Page to see all wishlists and products in them
- Functionality to create new list
- Functionality to delete item
- Functionality to rename list
- Functionality to share list
- Functionality to delete list
- Page to see product comparision
- Functionality to subscribe for product or whole list if it will be on sale
Step 5: What constraints or considerations exist?
- Should it wor across devices (users browse on mobile, buy on desktop)
- Should lists to be thinkied between devices?
- Privacy: wishlist data not critical, untill it not allow to track exact user identity
- Guest users: Do they get wishlists? Requires account?
Therefore, the root problem is: "Users who discover products they want but aren't ready to purchase have no way to maintain that interest, leading to lost conversions." The wishlist, comparison and subscription features are a solution to this engagement retention problem.
Example 2: Bug Report Analysis:
User Request: "Fix the login timeout - users are complaining"
Let's think step by step about what the user actually needs...
Step 1: What is the reported problem? Users are experiencing timeouts during login. This is a symptom, not necessarily the root cause.
Step 2: What could cause login timeouts? Multiple possibilities: server response too slow, session configuration too aggressive, network latency issues, authentication service bottleneck, or database connection pool exhaustion. The "fix" depends entirely on the root cause.
Step 3: What is the actual user pain? Users are frustrated because they can't access the system. But why? Are they losing work? Missing deadlines? The impact determines priority and acceptable solutions.
Step 4: What does "fix" mean in this context? Could mean: eliminate timeouts entirely, extend timeout duration, provide better error messages, add retry logic, or improve login performance. Each is a different scope.
Step 5: What information is missing?
- How long is the current timeout? What's acceptable?
- How many users affected? All or specific conditions?
- When did this start? Recent change?
- What error do users see?
Therefore, the root problem requires investigation: "Users cannot reliably access the system due to login failures, causing [specific business impact]. The underlying cause and appropriate fix are not yet determined." This is a bug requiring diagnosis, not a simple feature implementation.
---
STAGE 3: Concept Extraction (in scratchpad)
Template for Your Analysis
Use this template to write in scratchpad file:
## Phase 2: Concept Extraction
### Key Concepts Identified
Let's think step by step about the core elements of this feature...
Step 1: Who are the actors?
[Your analysis]
Step 2: What actions/behaviors are involved?
[Your analysis]
Step 3: What data entities exist?
[Your analysis]
Step 4: What constraints apply?
[Your analysis]
Step 5: What's implicitly assumed?
[Your analysis]
Therefore, the key concepts are: [Summary]
### Concept Summary
- **Actors**: [Who interacts with this feature?]
- **Actions/Behaviors**: [What does the system do?]
- **Data Entities**: [What data is involved?]
- **Constraints**: [What limitations exist?]
### Implicit Assumptions
- [What is assumed but not stated?]
### Scope Analysis
- **In Scope**: [What's included]
- **Out of Scope**: [What's explicitly excluded]
- **Boundary Cases**: [Edge cases to consider]Example of Concept Extraction Step-by-Step Analysis
Example: Payment Processing Feature:
Requirement: "Allow users to pay with multiple payment methods"
Let's think step by step about the core elements...
Step 1: Who are the actors?
- End users (customers making purchases)
- Payment processors (Stripe, PayPal, etc.)
- Finance team (reconciliation, refunds)
- System administrators (configuration)
Step 2: What actions/behaviors are involved?
- Select payment method at checkout
- Enter payment details
- Process payment authorization
- Handle payment success/failure
- Store payment method for future use (optional)
- Process refunds
Step 3: What data entities exist?
- PaymentMethod (type, last4, expiry, default flag)
- Transaction (amount, status, timestamp, reference)
- User (linked payment methods)
- Order (linked transaction)
Step 4: What constraints apply?
- PCI compliance for card data handling
- Regional restrictions (some methods not available everywhere)
- Currency limitations per payment method
- Transaction limits
Step 5: What's implicitly assumed?
- Users have valid payment sources
- Payment processors are available and configured
- Currency conversion is handled (or not?)
- Tax calculation happens before payment
Therefore, the key concepts are: multi-actor payment flow with strict compliance constraints, requiring integration with external processors and careful handling of sensitive financial data.
---
STAGE 4: Requirements Analysis (in scratchpad)
YOU MUST define functional and non-functional requirements with absolute precision. Vague requirements are WORTHLESS. Establish clear acceptance criteria, success metrics, constraints, and assumptions. Structure requirements hierarchically from high-level goals to specific features.
Template for Your Analysis
Use this template to write in scratchpad file:
4.1: User Scenarios
## Phase 3: Requirements Analysis
### Functional Requirements Analysis
Let's think step by step about the each requirement systematically...
[Follow the 5-step pattern demonstrated below]
### Functional Requirements
- [Requirement 1 - specific and testable]
- [Requirement 2 - specific and testable]
...
### Non-Functional Requirements
- [Requirement 1 - with measurable target]
- [Requirement 2 - with measurable target]
...
### Constraints & Assumptions
- [Constraint 1]
- [Constraint 2]
...
### Measurable Outcomes
- How will we know this is complete?
- What can be tested?
- What are the success metrics?
### User Scenarios
#### Primary Flow (Happy Path)
1. [Step 1]
2. [Step 2]
...
#### Alternative Flows
- [Scenario A]: [Steps]
- [Scenario B]: [Steps]
#### Error Scenarios
- [Error case 1]: [Expected behavior]
- [Error case 2]: [Expected behavior]Examples of Requirements Analysis Step-by-Step Analysis:
Example: File Upload Feature:
Requirement: "Users should be able to upload documents"
Let's think step by step about making this testable...
Step 1: What does "upload documents" actually mean? Need to define: what file types, what size limits, where files go, who can upload, what happens after upload. "Documents" is vague - PDFs? Word docs? Images? All of these?
Step 2: What is the happy path? User selects file → System validates file → System uploads file → System confirms success → File is accessible. Each step needs specific criteria.
Step 3: What are the failure modes?
- File too large: What's the limit? What error message?
- Wrong file type: Which types allowed? How communicated?
- Upload interrupted: Resume? Retry? Data loss?
- Storage full: How handled?
- Duplicate file: Overwrite? Rename? Reject?
Step 4: How do we make each criterion testable? BAD: "Upload should be fast" - How fast? Under what conditions? GOOD: "Upload of a 10MB file completes within 30 seconds on standard broadband connection"
BAD: "Support common document types" - Which ones? GOOD: "System accepts PDF, DOCX, XLSX, and PNG files"
Step 5: What non-functional requirements apply?
- Performance: Upload time relative to file size
- Security: Virus scanning, file type validation (not just extension)
- Reliability: No partial uploads left in storage
- Usability: Progress indicator, clear error messages
Therefore, the acceptance criteria must specify: allowed file types (PDF, DOCX, XLSX, PNG), size limit (50MB), upload time target (< 30s for 10MB), error messages for each failure mode, and storage/retrieval confirmation.
Example: Search Functionality:
Requirement: "Add search to find orders quickly"
Let's think step by step about making this testable...
Step 1: What does "quickly" mean in measurable terms? "Quickly" is subjective. Need to define: results appear within X seconds, search covers Y fields, returns top Z results. Current pain point might give context - if users currently take 2 minutes to find orders, "quickly" means under 10 seconds.
Step 2: What should be searchable? Order ID (exact match), customer name (partial match), product name, date range, status, amount range? Each searchable field has different matching logic.
Step 3: What results should appear? List of matching orders with: order ID, date, customer, total, status. Sorted by relevance? Date? How is relevance defined?
Step 4: What are the edge cases?
- No results found: What message? Suggestions?
- Too many results: Pagination? Filter refinement prompt?
- Special characters in search: Escaped? Literal?
- Empty search: Show all? Error?
Step 5: How do we verify "quickly"?
- Database with 100,000 orders
- Search returns results in < 2 seconds
- First 20 results displayed, pagination for more
Therefore, testable criteria include: "Search by order ID returns exact match within 500ms", "Search by customer name returns partial matches within 2 seconds", "No results displays 'No orders found' with suggestion to adjust filters", "Results paginated at 20 items per page".
4.2: Acceptance Criteria Draft
For each criterion, write this in scratchpad file:
Criterion: [Description]
Let's think step by step about what makes criterion testable...
Step 1: Is this specific enough to test?
[Can a QA engineer write a test without asking questions?]
Step 2: What are the Given/When/Then components?
- Given: [Precondition that must be true]
- When: [Action that triggers the behavior]
- Then: [Observable, verifiable outcome]
Step 3: Is the outcome measurable?
[Does it have a specific value, state, or observable result?]
Therefore, this criterion is [TESTABLE/NEEDS REFINEMENT because...]Then write summary in the scratchpad file:
### Acceptance Criteria Draft
| # | Criterion | Given | When | Then | Testable? |
|---|-----------|-------|------|------|-----------|
| 1 | [Description] | [Condition] | [Action] | [Outcome] | [Yes/No + reason] |
| 2 | [Description] | [Condition] | [Action] | [Outcome] | [Yes/No + reason] |
### Non-Functional Requirements
- **Performance**: [Specific metric if applicable]
- **Security**: [Specific requirement if applicable]
- **Compatibility**: [Specific requirement if applicable]Example of Testability Check Step-by-Step Analysis:
Draft Criterion: "Users can reset their password"
Let's think step by step about testability...
Step 1: Is this specific enough? No. How do they reset it? Email link? Security questions? What if email is wrong? What's the flow?
Step 2: Refined Given/When/Then:
- Given: User has a registered account with verified email
- When: User clicks "Forgot Password" and enters their email
- Then: System sends password reset link valid for 24 hours
Step 3: Is the outcome measurable? Partially. "Sends email" is verifiable, "valid for 24 hours" is testable. But what about the reset itself?
Additional criterion needed:
- Given: User has valid password reset link
- When: User clicks link and enters new password meeting requirements
- Then: Password is updated and user can log in with new password
Therefore, original criterion needs to be split into 2-3 specific, testable criteria covering: request reset, receive link, complete reset, and edge cases (expired link, invalid email).
4.3: Ambiguity Resolution
### Ambiguity Resolution
For unclear aspects, apply industry standards and reasonable defaults
| Ambiguous Element | Reasoning | Default Applied |
|-------------------|-----------|-----------------|
| [Element 1] | [Why this is reasonable] | [Default] |
| [Element 2] | [Why this is reasonable] | [Default] |
### Needs Clarification (MAX 3)
- [Only if: significantly impacts scope, multiple interpretations, NO reasonable default]Rules for clarifications:
- Only mark with
[NEEDS CLARIFICATION: specific question]if the choice significantly impacts scope, has multiple reasonable interpretations, AND no reasonable default exists - LIMIT: Maximum 3 [NEEDS CLARIFICATION] markers total
- Prioritize: scope > security/privacy > user experience > technical details
---
STAGE 5: Synthesis
Guidance
BEFORE proceeding to draft, verify you have completed ALL discovery steps. Incomplete analysis = rejected specification.
YOU MUST deliver a comprehensive requirements specification that enables confident architectural and implementation decisions. EVERY specification MUST include:
- Business Context: Problem statement, business goals, success metrics, and ROI justification if applicable. Missing business context = specification has no foundation.
- Functional Requirements: Precise feature descriptions with acceptance criteria and examples. NEVER submit vague feature descriptions.
- Non-Functional Requirements: Performance, security, scalability, usability, and compliance needs. Ignoring NFRs = system failures in production.
- Constraints & Assumptions: Technical, business, and timeline limitations. Undocumented assumptions = guaranteed misunderstandings.
- Dependencies: External systems, APIs, data sources, and third-party integrations. Missing dependencies = blocked implementation.
- Out of Scope: Explicit boundaries to prevent scope creep. NO EXCEPTIONS - every specification needs clear boundaries.
- Open Questions: Unresolved items requiring stakeholder input.
Structure findings hierarchically - from strategic business objectives down to specific feature requirements. NEVER use vague language. Support all claims with evidence from research or stakeholder input.
The specification MUST answer three questions or it FAILS:
1. "WHY" (business value) - If missing, specification is pointless 2. "WHAT" (requirements) - If vague, implementation will be wrong 3. "WHO" (stakeholders) - If incomplete, someone's needs will be ignored
Template for Your Draft
Use this template to write in scratchpad file:
## Phase 4: Draft Output
### Synthesis Reasoning
Let's think step by step about which findings are most relevant for the specification...
Step 1: What is the core business value I identified?
[Your reasoning]
Step 2: What are the must-have vs nice-to-have requirements?
[Your reasoning]
Step 3: What acceptance criteria passed testability review?
[Your reasoning]
Step 4: What scope boundaries must be explicit?
[Your reasoning]
Step 5: What's the clearest way to communicate this?
[Your reasoning]
Therefore, my refined description will: [Summary]
### Refined Description
[2-3 paragraphs covering:
- What is being built/changed/fixed
- Why this is needed (business value)
- Who will use/benefit from this
- Key constraints or considerations]
### Scope Summary
- **Included**: [Bullet list]
- **Excluded**: [Bullet list]
### User Scenarios Summary
1. **Primary Flow**: [One sentence]
2. **Alternative Flow**: [One sentence, if applicable]
3. **Error Handling**: [One sentence]
### Acceptance Criteria (Final)
[Only criteria that passed testability check]Example: Synthesizing Step-by-Step Analysis
Task: Notification preferences feature
Let's think step by step about which findings are most relevant for the specification...
Step 1: What is the core business value I identified? Users are unsubscribing from all communications because they can't control notification frequency. Business is losing engagement. The value is: retain user engagement by giving granular control.
Step 2: What are the must-have vs nice-to-have requirements? Must-have: Toggle notifications on/off per category, Email frequency control (immediate/daily/weekly) Nice-to-have: Quiet hours, channel preferences (email vs push vs SMS) Out of scope for now: AI-powered smart notifications
Step 3: What acceptance criteria passed testability review?
- "User can disable marketing emails with single toggle" ✓
- "Changes to preferences take effect within 5 minutes" ✓
- "User sees confirmation message after saving" ✓
- "Preferences work correctly" ✗ (too vague - removed)
Step 4: What scope boundaries must be explicit? In: Email notification preferences Out: Push notifications (separate project), SMS (not currently supported), notification content changes
Step 5: What's the clearest way to communicate this? Lead with the problem (users unsubscribing), then solution (granular control), then specific requirements, then boundaries. Developer should understand WHY before WHAT.
Therefore, my refined description will: (1) State the engagement retention problem, (2) Explain how granular preferences solve it, (3) List the specific user controls needed, (4) Clearly bound scope to email only.
---
STAGE 6: Update Task File
CRITICAL: Read the current task file, then use Write tool to update with enhanced content, based on your analysis in scratchpad.
You MUST preserve frontmatter and initial user prompt in the task file. Only update the # Description section and add the ## Acceptance Criteria section.
Template for Updated Sections
# Description
[Refined description that answers:]
- What is being built/changed/fixed
- Why this is needed (business value)
- Who will use/benefit from this
- Key constraints or considerations
**Scope**:
- Included: [What's in scope]
- Excluded: [What's explicitly out of scope]
**User Scenarios**:
1. **Primary Flow**: [Main use case]
2. **Alternative Flow**: [Secondary use case, if applicable]
3. **Error Handling**: [What happens when things go wrong]
## Acceptance Criteria
Clear, testable criteria using Given/When/Then or checkbox format:
### Functional Requirements
- [ ] **[Criterion 1]**: [Specific, testable requirement]
- Given: [Initial condition]
- When: [Action taken]
- Then: [Expected outcome]
- [ ] **[Criterion 2]**: [Specific, testable requirement]
- Given: [Initial condition]
- When: [Action taken]
- Then: [Expected outcome]
### Non-Functional Requirements (if applicable)
- [ ] **Performance**: [Specific metric, e.g., "Response time < 200ms"]
- [ ] **Security**: [Specific requirement, e.g., "Input sanitized against XSS"]
- [ ] **Compatibility**: [Specific requirement, e.g., "Works in Node 18+"]
### Definition of Done
- [ ] All acceptance criteria pass
- [ ] Tests written and passing
- [ ] Documentation updated
- [ ] Code reviewed---
STAGE 7: Self-Critique Loop (in scratchpad)
YOU MUST complete this self-critique AFTER drafting output. NO EXCEPTIONS.
Step 7.1: Verification Cycle
Use this template to write in scratchpad file:
## Self-Critique
Let's think step by step about whether this specification meets quality standards...
Step 1: Requirements Completeness
[Your reasoning]
Step 2: Scope Clarity
[Your reasoning]
[continue for all verification questions...]
Conclusion: [Your conclusion]
### Verification Results
| # | Verification Question | Reasoning | Evidence | Rating |
|---|----------------------|-----------|----------|--------|
| 1 | **Requirements Completeness**: Have I captured all functional requirements, including edge cases and error scenarios, with testable acceptance criteria? | [Your step-by-step reasoning] | [Specific evidence] | COMPLETE/PARTIAL/MISSING |
| 2 | **Scope Clarity**: Are the boundaries explicitly defined, with clear 'Out of Scope' items that prevent scope creep? | [Your step-by-step reasoning] | [Specific evidence] | COMPLETE/PARTIAL/MISSING |
| 3 | **Acceptance Criteria Testability**: Can a QA engineer write test cases directly from each criterion without asking clarifying questions? | [Your step-by-step reasoning] | [Specific evidence] | COMPLETE/PARTIAL/MISSING |
| 4 | **Business Value Traceability**: Does every requirement trace back to a stated business goal or user need? | [Your step-by-step reasoning] | [Specific evidence] | COMPLETE/PARTIAL/MISSING |
| 5 | **No Implementation Details**: Is the spec free of HOW (tech stack, APIs, code structure)? | [Your step-by-step reasoning] | [Specific evidence] | COMPLETE/PARTIAL/MISSING |Example: Self-Critique Reasoning
Let's think step by step about whether this specification meets quality standards...
Step 1: Requirements Completeness Looking at my functional requirements... I have 5 criteria covering the happy path. But wait - what about the error case when the user enters an invalid file type? I mentioned it in analysis but didn't create a criterion. This is a gap.
Step 2: Scope Clarity My "Out of Scope" section says "future enhancements" - that's too vague. A developer might think feature X is in scope when I intended it out. I need to list specific features that are excluded.
Step 3: Acceptance Criteria Testability Criterion #3 says "System responds quickly" - this is not testable. I need to specify "System responds within 2 seconds" with specific conditions.
Step 4: Business Value Traceability Criterion #4 is about audit logging. But I never mentioned compliance or audit requirements in my business context. Either remove this criterion or add the business justification.
Step 5: Implementation Independence Criterion #2 mentions "using Redis cache" - this is an implementation detail that doesn't belong in acceptance criteria. I should rewrite as "System caches results for improved performance" without specifying the technology.
Conclusion:Therefore, I have 3 gaps to fix: (1) Add error handling criterion, (2) Make scope exclusions specific, (3) Remove Redis mention from criteria.
Step 7.2: Gap Analysis
Use this template to write in scratchpad file:
### Gaps Found
| Gap | Analysis | Action Needed | Priority |
|-----|----------|---------------|----------|
| [Weakness] | [What root cause of the gap is] | [Specific fix] | Critical/High/Med/Low |Step 7.3: Revision Cycle
YOU MUST address all Critical/High priority gaps BEFORE proceeding. After addressing the gap, write this in scratchpad file:
### Revisions Made
For each gap:
- Gap: [X]
- Action: [What I did]
- Result: [Evidence of resolution]Common Failure Modes (check against these):
| Failure Mode | How to Detect | Required Fix |
|---|---|---|
| Vague acceptance criteria | Contains words like "quickly", "properly", "correctly" without metrics | Add specific conditions and measurable outcomes |
| Missing error scenarios | Only happy path documented | Add at least 2 error cases with expected behavior |
| Implementation details present | Mentions specific tech, APIs, frameworks | Remove all tech stack, API, code references |
| Untestable criteria | Can't write a test case from the criterion | Rewrite with Given/When/Then format |
| Scope boundaries unclear | "Out of Scope" is empty or says "TBD" | Add explicit In Scope/Out of Scope lists |
---
File Structure After Update
The task file should have this structure after your update:
---
title: [KEEP EXISTING]
status: [KEEP EXISTING]
issue_type: [KEEP EXISTING]
complexity: [KEEP EXISTING]
---
# Initial User Prompt
[PRESERVE ORIGINAL - NEVER DELETE]
# Description
[YOUR REFINED DESCRIPTION]
---
## Acceptance Criteria
[YOUR ACCEPTANCE CRITERIA]---
Expected Output
CRITICAL: ONLY after completing analysis in scratchpad, updating the task file and self-critique loop, respond with this template:
Business Analysis Complete: [task file path]
Scratchpad: .specs/scratchpad/<hex-id>.md
Acceptance Criteria Added: X criteria
Scope Defined: [Yes/No]
User Scenarios: [Count] documented
Complexity Validation: [Confirmed/Suggest adjustment to X]
Self-Critique: 5 verification questions checked
Gaps Addressed: [Count]Related skills
FAQ
What is the scratchpad-first approach in plan-task?
plan-task collects all business analysis in a scratchpad file first, then copies only verified findings into the task file. That separation keeps exploratory notes out of the final spec while ensuring acceptance criteria are complete and testable.
When should plan-task run in a sprint?
plan-task should run before implementation when a task description is vague or success cannot be measured. The skill expands scope and writes acceptance criteria so developers know exactly what to build and how completion is verified.
Is Plan Task safe to install?
skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.