create-tdd-tasks

What this skill does

# Create TDD Tasks Skill

Transform existing SDD implementation tasks into test-first TDD task pairs. For each implementation task, this skill creates a paired test task that must complete first, enforcing test-first development at the pipeline level.

This skill bridges the SDD pipeline (`/create-tasks`) and TDD execution (`/execute-tdd-tasks`), converting a standard task list into one where every implementation task is preceded by a failing-test-writing task.

**CRITICAL: Complete ALL 8 phases.** The workflow is not complete until Phase 8: Report is finished. After completing each phase, immediately proceed to the next phase without waiting for user prompts.

## Core Principles

1. **Test-first at the pipeline level** -- Every implementation task gets a paired test task that blocks it. Tests are written before implementation begins.
2. **Preserve existing dependencies** -- TDD pairs are inserted into the existing SDD dependency chain without breaking any original relationships.
3. **Merge mode awareness** -- Re-running this skill on a task list that already has TDD pairs detects and skips existing pairs instead of creating duplicates.
4. **Criteria-to-tests conversion** -- Acceptance criteria from SDD tasks are converted into test descriptions for the paired test task.
5. **Minimal metadata additions** -- Only `tdd_mode`, `tdd_phase`, and `paired_task_id` are added. All existing metadata is preserved.

## Critical Rules

### AskUserQuestion is MANDATORY

**IMPORTANT**: You MUST use the `AskUserQuestion` tool for ALL questions to the user. Never ask questions through regular text output.

- Preview confirmation -> AskUserQuestion
- Anomaly resolution -> AskUserQuestion
- Error recovery options -> AskUserQuestion

Text output should only be used for:
- Presenting TDD pair previews and summaries
- Reporting completion status
- Displaying dependency chain visualizations

**NEVER do this** (asking via text output):
```
Should I proceed with creating 12 TDD task pairs?
1. Yes
2. No
```

**ALWAYS do this** (using AskUserQuestion tool):
```yaml
AskUserQuestion:
  questions:
    - header: "Confirm TDD Pair Creation"
      question: "Ready to create 12 TDD task pairs?"
      options:
        - label: "Yes, create pairs"
          description: "Create test tasks and set TDD dependencies"
        - label: "Show details"
          description: "See full list of pairs before creating"
        - label: "Cancel"
          description: "Don't create TDD pairs"
      multiSelect: false
```

### Plan Mode Behavior

**CRITICAL**: This skill transforms tasks, NOT creates an implementation plan. When invoked during Claude Code's plan mode:

- **DO NOT** create a plan for how to implement TDD
- **DO NOT** defer task transformation to an "execution phase"
- **DO** proceed with the full TDD task generation workflow immediately
- **DO** create test tasks using TaskCreate as normal

The TDD task pairs are planning artifacts themselves -- generating them IS the planning activity.

### Soft Dependency on sdd-tools

This skill is part of the `tdd-tools` plugin and works with agents in the same plugin (`tdd-executor`, `test-writer`). It bridges the SDD pipeline (`/create-tasks` from `sdd-tools`) and TDD execution (`/execute-tdd-tasks`). The `sdd-tools` plugin is expected to be installed since TDD tasks are generated from SDD tasks created by `/create-tasks`.

---

## Phase 1: Validate & Load References

**Goal:** Verify prerequisites and load reference materials.

### Step 1: Parse Arguments

Check `$ARGUMENTS` for optional `--task-group` filter:
- If `--task-group <group>` is present, extract the group name for filtering
- If no arguments provided, process all tasks

### Step 3: Load Reference Files

Read the TDD decomposition and dependency reference files:

1. `references/tdd-decomposition-patterns.md` -- Task pairing rules, naming conventions, metadata, merge mode detection
2. `references/tdd-dependency-rules.md` -- Dependency insertion algorithm, circular dependency detection and breaking

---

## Phase 2: Read Existing Tasks

**Goal:** Load the current task list and identify tasks to transform.

### Step 1: Get All Tasks

Use `TaskList` to retrieve all current tasks.

### Step 2: Apply Group Filter

If `--task-group` was specified:
- Filter to only tasks where `metadata.task_group` matches the specified group
- Tasks outside the group are not modified

If no `--task-group` specified:
- Process all tasks regardless of group

### Step 3: Validate Task List

Handle empty/missing states:

**Empty task list (no tasks at all):**
```
No tasks found. Please run /create-tasks first to generate implementation tasks from a spec.

Usage:
  /agent-alchemy-sdd:create-tasks <spec-path>
```

**No tasks matching --task-group filter:**
```
No tasks found for group "{group}".

Available task groups:
- {group1} ({n} tasks)
- {group2} ({n} tasks)

Try: /create-tdd-tasks --task-group {group1}
```

### Step 4: Classify Tasks

For each task, determine if it should receive a TDD pair:

**Eligible for TDD pairing:**
- Implementation tasks (subjects like "Create X", "Implement X", "Build X", "Add X")
- Business logic tasks
- API/endpoint tasks
- Data model tasks
- UI/frontend tasks

**Skip (no TDD pair created):**
- Tasks already marked with `tdd_mode: true` in metadata
- Test tasks (subjects like "Add tests for X", "Write tests for X", or tasks with `test` in `task_uid`)
- Configuration/setup tasks (subjects like "Configure X", "Set up X")
- Documentation tasks (subjects like "Document X", "Write docs for X")

Record the classification for each task: eligible, skipped (with reason).

---

## Phase 3: Detect Existing TDD Pairs (Merge Mode)

**Goal:** Identify tasks that already have TDD pairs to avoid duplication.

### Detection Algorithm

For each eligible task, check if it already has a TDD pair using these 4 signals (any match means paired):

1. **Metadata check**: Task has `tdd_mode: true` in metadata
2. **Paired task check**: Task has `paired_task_id` in metadata, and the paired task exists in the task list
3. **UID check**: A task exists with `task_uid` equal to this task's `task_uid` + `:red`
4. **Subject check**: A task with subject `"Write tests for {this task's subject}"` exists in the same `task_group`

### Merge Behavior

For tasks with existing TDD pairs:

| Existing Pair Status | Action |
|---------------------|--------|
| Both tasks pending | Skip -- pair already exists |
| Test completed, impl pending | Skip -- pair progressing normally |
| Test completed, impl completed | Skip -- pair fully done |
| Test completed, impl in_progress | Skip -- pair in progress |
| Test pending, impl completed | Flag as anomaly -- impl completed without tests |
| Only impl exists, test missing | Treat as unpaired -- create the test task |
| Only test exists, impl missing | Flag as orphan -- ask user |

### Report Merge Status

If any existing pairs detected:

```
TDD PAIR STATUS:
- {n} tasks already have TDD pairs (will skip)
- {m} tasks need TDD pairs (will create)
- {k} anomalies detected (need user input)
```

If anomalies exist, use AskUserQuestion to resolve each one:

```yaml
AskUserQuestion:
  questions:
    - header: "TDD Pair Anomaly"
      question: "Task #{id} '{subject}' was completed without its test task. What should I do?"
      options:
        - label: "Create test task anyway"
          description: "Add a test task for documentation/coverage purposes"
        - label: "Skip this task"
          description: "Leave it as-is without a test pair"
      multiSelect: false
```

---

## Phase 4: Generate Test Tasks

**Goal:** Create test task definitions for each eligible unpaired implementation task.

For each eligible task that needs a TDD pair, generate a paired test task.

### Step 1: Determine Test Task Subject

Follow the naming convention:
```
"Write tests for {original task subject}"
```

Examples:
- "Create User data model" -> "Write tests for Create User data model"
- "Impleme