Use this skill when approved requirements and design need to be decomposed into tasks.md for Phase 3 of a Spec-Driven change. It creates atomic, traceable implementation and testing tasks, validates the plan, and should not be used to design architecture or write implementation code.
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.
A direct command skips the review prompt. Inspect the source before running it.
Use this skill when approved requirements and design need to be decomposed into tasks.md for Phase 3 of a Spec-Driven change. It creates atomic, traceable implementation and testing tasks, validates the plan, and should not be used to design architecture or write implementation code.
Spec-Driven Task Decomposer Skill
Write a tasks.md document that turns approved requirements and design elements into an ordered, traceable implementation plan.
Your job is to produce a task artifact that:
is easy for an implementation agent to execute in sequence
keeps tasks small, concrete, and dependency-aware
preserves traceability from tasks to DES-* and REQ-*
includes explicit acceptance-criteria test coverage before final verification
Default path: read approved requirements and design, group work into practical phases, create atomic tasks, add acceptance-criteria testing, validate tasks.md, and return a short review-ready summary.
Read references/task-patterns.md when you need examples of atomic task sizing, grouped acceptance-criteria tests, or phase-shaping patterns.
Shared Protocol
Follow the Context Preflight and Phase Gate protocols in the spec-driven-shared-protocol skill's references/shared-protocol.md.
Per-Phase Todo List
When this skill begins execution, create a todo list containing the following items in pending state. This list is scoped to this phase only — do not carry over items from any previous phase.
Read requirements.md and design.md
Read project guidelines
Retrieve contextual memory (workflow)
Execute non-exhaustive Code Anatomy Discovery Targets and record evidence
Define implementation phases
Create atomic tasks
Add per-phase test tasks
Add acceptance criteria testing phase
Add final checkpoint phase
Save tasks.md
Run CLI validation (sds validate tasks + sds validate spec)
Complete quality bar self-check
Fix validation failures (if any)
Declare verdict
Progress Rules
Mark an item in_progress when starting that work step.
Mark an item completed only after the work step has been verified.
Do not mark an item completed until verification passes.
Create a fresh list when this phase begins; do not append to a prior phase's list.
Output File
.specs/changes/<slug>/tasks.md
IMPORTANT: Only tasks.md is a valid spec document name for tasks. The spec-driven workflow strictly requires exactly three document types: requirements.md, design.md, and tasks.md.
Required Document Structure
See the spec-driven-shared-protocol skill's references/document-templates.md for the tasks document template.
Task Rules
Use checkbox task format: - [ ] N.M Task title.
Number phases sequentially as ## Phase 1: ..., ## Phase 2: ..., and so on.
Number tasks sequentially inside each phase using the phase number (1.1, 1.2, 2.1, etc.).
Every non-checkpoint task must include an _Implements: line.
Use _Depends: only when the dependency is real and useful.
Resolve all placeholders before returning output.
Do not include HTML comments, TODO markers, or drafting notes.
Include ## Repository Constraints when guidelines, contextual memory, or design evidence affects task ordering, test placement, naming, package boundaries, or verification commands.
If design.md Code Anatomy uses Coverage: Representative or Coverage: Initial Discovery Only, execute every Discovery Target before writing tasks and include ## Discovery Evidence.
Task Types
Implementation Tasks
Use implementation tasks for building or modifying design elements:
- [ ] 2.1 Add authorization middleware
- Implement the request guard used by protected endpoints.
-_Depends: 1.2_ -_Implements: DES-1, REQ-1.1_
Rules:
Every implementation task must reference at least one DES-* element.
Add REQ-* references when the task clearly delivers a specific requirement behavior.
Every REQ-X.Y acceptance criterion must be referenced in the _Implements: line of at least one implementation or test task.
For non-exhaustive Code Anatomy, discovery is decomposition work, not an implementation task. Execute every design Discovery Target and record one evidence block per target before the first implementation phase:
## Discovery Evidence- Target: `Grep for request handlers and exports` - Result: `src/example/handler.ts` and `src/example/index.ts` - Plan impact: Tasks 1.1 and 2.1 cover the discovered touchpoints
Rules:
Record explicit results, including No additional touchpoints when a search finds none.
Map each result to task IDs or state No plan change.
If findings change approved design boundaries or risk, stop and return to design review.
Do not emit a discovery/inventory checkbox task in new task plans.
Test Tasks
Use test tasks in the dedicated Acceptance Criteria Testing phase:
- [ ] 3.1 Test: reject unauthorized access
- Verify requests without the required role are rejected.
- Test type: integration
-_Depends: 2.1_ -_Implements: REQ-1.1_
Rules:
Prefix test tasks with Test:.
Use behavior-focused titles; do not include REQ-* IDs in the title.
Every test task must include Test type: unit, Test type: integration, or Test type: e2e.
Every test task must include _Implements: with one or more REQ-* acceptance criteria.
Every acceptance criterion from requirements.md must be covered by at least one test task.
Group closely related acceptance criteria into one test task when a single test flow naturally verifies them together.
Per-Phase Test Tasks
Test tasks may be placed in any phase to verify the work just completed. Any phase that contains one or more implementation tasks must include at least one Test: task. The dedicated Acceptance Criteria Testing phase remains the penultimate cross-cutting verification.
Testing Guidance
Choose test type in this order:
Follow TESTING.md if present
Follow the design document's Testing Requirements section if present
Otherwise default by scope:
unit for isolated logic
integration for cross-component or service-boundary behavior
e2e for user-visible end-to-end flows
The Acceptance Criteria Testing phase must be the penultimate phase. The Final Checkpoint phase must be the last phase.
Phase Design Guidance
Use phases to create a practical execution order. Good phase patterns include:
foundation or setup
core feature delivery
supporting integrations or error handling
acceptance criteria testing
final checkpoint
Prefer 3-6 phases for most changes.
Sizing and Dependency Rules
Prefer tasks that fit within one focused session.
Split tasks that cover multiple unrelated concerns.
Split tasks that touch too many files or systems without a clear reason.
Avoid dependency chains longer than necessary.
If a task title naturally contains and, consider splitting it.
Traceability Rules
Every DES-* element from design.md should be implemented by at least one implementation task.
Every REQ-* acceptance criterion from requirements.md must be covered by at least one test task.
Every REQ-* acceptance criterion from requirements.md must be referenced in the _Implements: line of at least one implementation or test task.
Use _Implements: DES-X_ or _Implements: DES-X, REQ-Y.Z_ for implementation tasks.
Use _Implements: REQ-Y.Z_ or grouped _Implements: REQ-Y.Z, REQ-A.B_ for test tasks.
Use _Implements: All requirements_ only for the Final Checkpoint task.
Clarification Policy
Ask a clarifying question only if the ambiguity would materially change task sequencing, dependency structure, test strategy, or how requirements map to design elements.
When to Ask
The design is missing key DES-* details needed for decomposition
The requirements and design appear inconsistent
Scope is too broad for one coherent task plan
When NOT to Ask
Design provides enough structure for a reasonable task breakdown
Low-risk assumption can be made and reflected in the tasks
Validation and Recovery
When sds validate tasks or sds validate spec returns errors:
Add missing required sections or phases
Fix task numbering and checkbox formatting
Add missing _Implements: lines to non-checkpoint tasks
Add or fix DES-* references so they match design.md
Add or fix test tasks so every acceptance criterion is covered
Add or fix Phase 3 Discovery Evidence required by non-exhaustive Code Anatomy
After 3 failed validation attempts:
Summarize remaining errors
Ask: "Should I proceed with best-effort corrections?"
Incomplete Design or Requirement Inputs
If requirements.md or design.md is incomplete but still usable:
Preserve valid traceability that already exists
Infer the smallest reasonable task plan from available structure
Avoid inventing major new architecture
Quality Bar (Self-Check)
Before returning the tasks, verify:
Document starts with # Implementation Tasks
## Overview is present
Phase headers use ## Phase N: Title
Acceptance Criteria Testing is the penultimate phase
Final Checkpoint is the last phase
Every task uses checkbox format
Every non-checkpoint task includes _Implements:
Each implementation-bearing phase contains at least one Test: task
Non-exhaustive Code Anatomy has complete Phase 3 Discovery Evidence and no discovery/inventory implementation task
Every DES-* from design.md is covered by implementation tasks
Every REQ-* acceptance criterion is covered by at least one test task
No HTML comments or drafting notes remain
Output Requirements
Write .specs/changes/<slug>/tasks.md before requesting review. Prefer validator-compatible structure over decorative formatting. Keep the plan concise but complete enough for direct implementation.
Response Behavior
If enough information is available, produce the full tasks.md content directly.
If material ambiguity blocks a sound task plan, ask a short clarification first. Do not produce a low-confidence decomposition.
Contextual Stewardship Integration
At the start of this phase, invoke the contextual-stewardship skill to retrieve established workflow conventions:
