Create Task Specification Skill

Purpose

Create hyper-detailed task specifications that embed ALL context needed for implementation, eliminating the need for developers to search for information during coding.

Core Capabilities:

• •Requirement gathering and clarification
• •Architecture context extraction with source references
• •Component analysis (data models, APIs, UI)
• •Sequential task breakdown with validation checkpoints
• •Self-contained specifications

BMAD Pattern (Key Innovation):

• •SM reads PRD + Architecture + Previous task notes
• •Creates detailed task spec with embedded context
• •Dev reads ONLY task spec (no architecture lookup)
• •Result: Context never lost, implementation never blocked

Prerequisites

• •Configuration file (.claude/config.yaml) with task settings
• •Task template (.claude/templates/task-spec.md)
• •Architecture documentation (optional but recommended)
• •Project coding standards

Workflow

Step 0: Load Configuration and Validate Prerequisites

Action: Load configuration and verify prerequisites.

Execute:

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path .claude/config.yaml \
  --output json

Extract: documentation.architecture, development.alwaysLoadFiles, development.taskLocation, templates.taskSpec

Verify: Task location exists, template exists, determine next task ID

Halt if: Config missing, template missing, cannot determine task ID

See: references/templates.md for configuration format and references/requirements-gathering-guide.md for requirement clarification

Step 1: Gather Requirements from User

Action: Clarify requirement, acceptance criteria, and priority.

Ask user:

1. •

   What needs to be implemented?

   • •Feature description
   • •Problem it solves
   • •Primary user/beneficiary
2. •

   What defines "done"?

   • •Testable outcomes
   • •Acceptance criteria (2-5 specific criteria)
   • •Edge cases to consider
3. •

   Priority and complexity?

   • •Priority: P0 (Critical) | P1 (High) | P2 (Medium) | P3 (Low)
   • •Complexity: Simple | Medium | Complex
   • •Related epic/feature

Confirm understanding:

• •Restate as user story: As a [role], I want [action], so that [benefit]
• •Verify acceptance criteria
• •Get approval to proceed

Halt if:

• •User cannot articulate requirement clearly
• •Acceptance criteria are ambiguous
• •User does not approve proceeding

See: references/requirements-gathering-guide.md for detailed gathering techniques

Step 2: Load Architecture Context

Action: Load architecture documentation and previous task learnings.

Load files:

1. •

   Always-required files (coding standards):

   bash

   python .claude/skills/bmad-commands/scripts/read_file.py \
     --path {always_load_file} \
     --output json
   

2. •

   Architecture documentation:

   • •Read documentation.architecture files
   • •Extract: System design, patterns, conventions
3. •

   Previous task insights:

   • •Read most recent task file from taskLocation
   • •Extract: Completion notes, lessons learned, patterns

Context categories: Tech stack, project structure, coding standards, testing strategy, data models, API specs, component specs, patterns

CRITICAL RULES: ONLY use information from source documents, NEVER invent details, ALWAYS cite sources, note when info missing

See: references/context-extraction-guide.md for detailed extraction strategies and references/templates.md for context format examples

Step 3: Analyze Relevant Components

Action: Identify affected components and extract specific technical details.

Identify components:

• •What data models are involved?
• •What API endpoints need creation/modification?
• •What UI components are affected?
• •What external services are used?

Extract details: Data models (schemas, validation, relationships), API specs (endpoints, request/response, auth, errors), component specs (location, props, state, styling), file locations (exact paths), constraints (performance, security, reliability, testing)

All extractions must cite: [Source: filename#section]

See: references/context-extraction-guide.md for analysis patterns and references/templates.md for extraction format examples

Step 4: Create Sequential Task Breakdown

Action: Break requirement into 3-15 sequential tasks with subtasks.

Task breakdown:

1. •

   Break into 3-15 tasks:

   • •Each task implements specific functionality
   • •Tasks build on each other logically
   • •Each task maps to one or more acceptance criteria
2. •

   Create subtasks for each task:

   • •Specific implementation steps
   • •Test writing requirements
   • •Validation checkpoints
3. •

   Structure in implementation order:

   • •Data layer first (models, migrations)
   • •Business logic second (services, utilities)
   • •API layer third (routes, controllers)
   • •UI layer fourth (components, pages)
   • •Integration last (E2E tests, documentation)
4. •

   Link to acceptance criteria: Example: "Task 1: Create user model (AC: 1, 2)"

Halt if: Cannot break down coherently, >15 tasks (too complex), <3 tasks (too simple)

See: references/task-breakdown-guide.md for detailed strategies and references/templates.md for task structure examples

Step 5: Populate Task Specification Template

Action: Generate task file from template with all context embedded.

Load template:

python .claude/skills/bmad-commands/scripts/read_file.py \
  --path .claude/templates/task-spec.md \
  --output json

Replace placeholders: task_id, title, date, priority, status, user_story, acceptance_criteria, context, tasks, validation

Context must include: Previous insights, data models, API specs, component specs, file locations, testing requirements, constraints - ALL with [Source: filename#section] references

See: references/templates.md for placeholder examples and formats

Step 6: Validate Task Specification Completeness

Action: Verify all required elements are present and properly formatted.

Validation checklist:

Required Sections:

• • Status (Draft)
• • Objective (clear user story)
• • Acceptance Criteria (2-5 specific criteria)
• • Context section with embedded details
• • Tasks / Subtasks (3-15 tasks)
• • Implementation Record (empty placeholder)

Context Completeness:

• • Previous insights referenced
• • Data models included (if applicable)
• • API specs included (if applicable)
• • Component specs included (if applicable)
• • File locations specified
• • Testing requirements documented
• • All context has [Source: ...] references

Task Quality:

• • Tasks in logical implementation order
• • Each task linked to acceptance criteria
• • Subtasks include test writing steps
• • Validation checkpoints included
• • File paths are specific, not generic

Halt if:

• •Critical sections missing
• •Context lacks source references
• •Tasks are ambiguous or generic
• •No validation checkpoints

See: references/validation-approval-guide.md for validation details

Step 7: Save Task Specification and Get User Approval

Action: Save task file and present summary for approval.

Save file:

python .claude/skills/bmad-commands/scripts/write_file.py \
  --path {taskLocation}/{task_id}.md \
  --content "{task_spec}" \
  --output json

Present summary: Show task ID, objective, acceptance criteria, task breakdown, embedded context sources, and request approval.

Update status if approved: Change from "Draft" to "Approved"

See: references/templates.md for complete summary format and references/validation-approval-guide.md for approval workflow

Output

Return structured output with task file path, task ID, task count, status, and telemetry metrics.

See: references/templates.md for complete output format

Best Practices

1. •Context Embedding is Critical - Implementation should never need architecture docs
2. •Be Specific, Not Generic - Exact file paths, schemas, API specs
3. •Source Everything - Cite [Source: filename#section] for all technical details
4. •Task Granularity - 3-15 tasks (>15 too complex, <3 too simple)

See: references/task-breakdown-guide.md for detailed practices

Routing Guidance

Use this skill when:

• •Breaking features into implementable tasks
• •Creating detailed specifications for development
• •Embedding architectural context for implementation
• •Need clear, unambiguous work items

Always use before:

• •execute-task skill (implementation)
• •Task must be "Approved" status

Do not use for:

• •Quick bug fixes (too much overhead)
• •Urgent hotfixes (too structured)
• •Exploratory coding (too constrained)

Reference Files

• •references/requirements-gathering-guide.md - Clarifying requirements, acceptance criteria, user stories
• •references/context-extraction-guide.md - Loading architecture, extracting technical details, sourcing
• •references/task-breakdown-guide.md - Creating sequential tasks, granularity, validation checkpoints
• •references/validation-approval-guide.md - Completeness validation, saving, approval workflow
• •references/templates.md - Task spec template, output format, placeholder examples, configuration format

Using This Skill

Invoked with requirement input (feature description) and optional priority (P0-P3)

Part of BMAD Enhanced Planning Suite