spec-driven-task-decomposer

name	spec-driven-task-decomposer
description	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.

1. Read requirements.md and design.md
2. Read project guidelines
3. Retrieve contextual memory (workflow)
4. Execute non-exhaustive Code Anatomy Discovery Targets and record evidence
5. Define implementation phases
6. Create atomic tasks
7. Add per-phase test tasks
8. Add acceptance criteria testing phase
9. Add final checkpoint phase
10. Save tasks.md
11. Run CLI validation (sds validate tasks + sds validate spec)
12. Complete quality bar self-check
13. Fix validation failures (if any)
14. 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.
• Keep titles action-oriented: Add, Update, Refactor, Wire, Create, Remove.

Phase 3 Discovery Evidence

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:

1. Follow TESTING.md if present
2. Follow the design document's Testing Requirements section if present
3. 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:

1. Add missing required sections or phases
2. Fix task numbering and checkbox formatting
3. Add missing _Implements: lines to non-checkpoint tasks
4. Add or fix DES-* references so they match design.md
5. Add or fix test tasks so every acceptance criterion is covered
6. Add or fix Phase 3 Discovery Evidence required by non-exhaustive Code Anatomy

After 3 failed validation attempts:

1. Summarize remaining errors
2. Ask: "Should I proceed with best-effort corrections?"

Incomplete Design or Requirement Inputs

If requirements.md or design.md is incomplete but still usable:

1. Preserve valid traceability that already exists
2. Infer the smallest reasonable task plan from available structure
3. 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:

Invoke: contextual-stewardship skill
Action: retrieve
Query: workflow

Things To Avoid

• Creating additional files in .specs/changes/<slug>/. Only write tasks.md for this phase.