Spec Driven Task Decomposer

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.

Process

If long-running-work-planning is available, load it at the start of this phase before decomposing the work. Use it to shape phase ordering, keep progress visible, and avoid holding all task reasoning until the end.

1. Read Requirements: Read specs/changes/<slug>/requirements.md.
2. Read Design: Read specs/changes/<slug>/design.md.
3. Read Project Guidelines (if they exist): Use Glob and Read to inspect TESTING.md and STYLEGUIDE.md.
4. Retrieve Contextual Memory: Invoke the contextual-stewardship skill to retrieve workflow rules.
5. Inspect Existing Patterns: Use Grep to find similar task structures in existing specs when helpful.
6. Define Phases: Group work into a small number of phases that follow implementation dependencies.
7. Create Atomic Tasks: Break each design element into tasks that are concrete and usually completable within one focused session.
8. Add Acceptance Criteria Testing: Create a dedicated penultimate testing phase covering every acceptance criterion.
9. Add Final Checkpoint: Create a final phase that verifies all requirements and overall spec completeness.
10. Validate Tasks: Call mcp:verify_tasks_file using tasks.md and design.md content.
11. Validate Full Spec: Call mcp:verify_complete_spec for <slug>.
12. Write Before Review: Save to specs/changes/<slug>/tasks.md before asking for approval.

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. Inspect existing patterns
5. Define implementation phases
6. Create atomic tasks
7. Add acceptance criteria testing phase
8. Add final checkpoint phase
9. Validate tasks
10. Quality grade tasks
11. Save tasks.md

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

Required Document Structure

Your output must use this structure.

# Implementation Tasks

## Overview

This implementation is organized into 4 phases:

1. **Foundation** - Prepare core structures and entry points
2. **Feature Delivery** - Implement the main design elements
3. **Acceptance Criteria Testing** - Verify requirement behavior
4. **Final Checkpoint** - Validate completeness and readiness

**Estimated Effort**: Medium (3-5 sessions)

## Phase 1: Foundation

- [ ] 1.1 Add request entry point
  - Create the main request handler for protected operations.
  - _Implements: DES-1_

- [ ] 1.2 Add authorization service
  - Implement the shared authorization decision logic used by protected operations.
  - _Depends: 1.1_
  - _Implements: DES-1, REQ-1.1, REQ-1.2_

## Phase 2: Feature Delivery

- [ ] 2.1 Add denial feedback path
  - Return a user-visible denial response when authorization fails.
  - _Depends: 1.2_
  - _Implements: DES-1, REQ-2.1_

- [ ] 2.2 Add audit logging for denied actions
  - Record authorization failures when audit logging is enabled.
  - _Depends: 1.2_
  - _Implements: DES-2, REQ-3.1, REQ-3.2_

## Phase 3: Acceptance Criteria Testing

- [ ] 3.1 Test: reject non-administrator protected actions
  - Verify protected actions are rejected for non-administrator users.
  - Test type: integration
  - _Depends: 1.2_
  - _Implements: REQ-1.1_

- [ ] 3.2 Test: allow administrator protected actions
  - Verify protected actions succeed for administrator users.
  - Test type: integration
  - _Depends: 1.2_
  - _Implements: REQ-1.2_

- [ ] 3.3 Test: show denial feedback and record denied attempts
  - Verify denied protected actions display the denial response and record the denial event.
  - Test type: integration
  - _Depends: 2.1, 2.2_
  - _Implements: REQ-2.1, REQ-3.1_

## Phase 4: Final Checkpoint

- [ ] 4.1 Verify all acceptance criteria
  - REQ-1: Confirm protected actions enforce authentication and administrator authorization.
  - REQ-2: Confirm denied access returns clear feedback.
  - REQ-3: Confirm denied actions are recorded when logging is enabled.
  - Run the relevant test suite and resolve any remaining traceability gaps.
  - _Implements: All requirements_

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 in the final artifact.

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.
• Keep titles action-oriented: Add, Update, Refactor, Wire, Create, Remove.

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.
• You may group closely related acceptance criteria into one test task when a single test flow naturally verifies them together.
• If multiple criteria are grouped, the title and description must make the combined behavior explicit.

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.
• If one task depends on many earlier tasks, reconsider the phase layout.

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.
• 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
• 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.
• The scope is too broad for one coherent task plan.
• Test coverage expectations are materially unclear.

When NOT to Ask

• The design provides enough structure for a reasonable task breakdown.
• A low-risk assumption can be made and reflected in the tasks.
• The ambiguity is implementation-level rather than decomposition-level.

How to Ask

• Ask no more than 3 focused questions at a time.
• Ask about execution decisions, not implementation preferences.
• Prefer concrete options when possible.

Validation and Recovery

MCP Validation Failures

When mcp:verify_tasks_file or mcp:verify_complete_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. Reorder tasks to remove obvious dependency issues.

After 3 failed validation attempts:

1. Summarize the remaining errors.
2. Ask: "Should I proceed with best-effort corrections?"
3. If yes: make corrections and document assumptions in ordinary task prose.
4. If no: request focused guidance.

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.
4. Surface the blocking gaps if they prevent reliable decomposition.

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:
• Every DES-* from design.md is covered by implementation tasks
• Every REQ-* acceptance criterion is covered by at least one test task
• Grouped test tasks only combine naturally related criteria
• Numbering is concrete; no symbolic placeholders like N-1 remain
• 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
• Return ordinary prose summary after the file is written; do not wrap the artifact in XML

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, before decomposing the work, invoke the contextual-stewardship skill to retrieve established workflow conventions:

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

This ensures the task breakdown aligns with team processes, testing rules, and naming conventions.

Quality Grading Integration

After completing tasks and before requesting approval, invoke the quality-grading skill to assess and improve task plan quality:

Invoke: quality-grading skill
Artifact: specs/changes/<slug>/tasks.md
Mode: grade-and-fix

This ensures the tasks document meets quality standards across:

• Design Quality: Logical phase organization, task dependencies, clear structure
• Originality: Tailored task breakdown vs generic boilerplate
• Craft: Clear task descriptions, proper traceability, consistent formatting
• Functionality: Complete coverage of requirements, all acceptance criteria mapped

The quality-grading skill will auto-fix issues scoring below 4 and provide actionable suggestions for remaining gaps.

Converted and distributed by TomeVault — claim your Tome and manage your conversions.