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:

What needs to be implemented?

• Feature description

• Problem it solves

• Primary user/beneficiary

What defines "done"?

• Testable outcomes

• Acceptance criteria (2-5 specific criteria)

• Edge cases to consider

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:

Always-required files (coding standards):

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

Architecture documentation:

• Read documentation.architecture files

• Extract: System design, patterns, conventions

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:

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

Create subtasks for each task:

• Specific implementation steps

• Test writing requirements

• Validation checkpoints

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)

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

• Context Embedding is Critical - Implementation should never need architecture docs

• Be Specific, Not Generic - Exact file paths, schemas, API specs

• Source Everything - Cite [Source: filename#section] for all technical details

• 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