sdd-tasks

What this skill does

# sdd-tasks

> Breaks down the design into an atomic, ordered, and verifiable task plan.

**Triggers**: `/sdd-tasks <change-name>`, task plan, break down implementation, task breakdown, sdd tasks

---

## Purpose

The task plan converts the design into an **executable work list**. Each task is atomic (one single thing), concrete (has a file path), and verifiable (can be marked as done).

It is the input for `sdd-apply`. Without an approved tasks file, nothing gets implemented.

---

## Process

### Skill Resolution

When the orchestrator launches this sub-agent, it resolves the skill path using:

```
1. .claude/skills/sdd-tasks/SKILL.md     (project-local — highest priority)
2. ~/.claude/skills/sdd-tasks/SKILL.md   (global catalog — fallback)
```

Project-local skills override the global catalog. See `docs/SKILL-RESOLUTION.md` for the full algorithm.

---

### Step 0 — Load project context + Spec context preload

Follow `skills/_shared/sdd-phase-common.md` **Section F** (Project Context Load) and **Section G** (Spec Context Preload). Both are non-blocking.

---

### Step 1 — Read prior artifacts

I must read:

- The design artifact (the file matrix and approach):
  - `mem_search(query: "sdd/{change-name}/design")` → `mem_get_observation(id)`.
  - If not found and Engram not reachable: design content passed inline from orchestrator.
- The spec artifact (the success criteria):
  - `mem_search(query: "sdd/{change-name}/spec")` → `mem_get_observation(id)`.
  - If not found and Engram not reachable: spec content passed inline from orchestrator.
- The proposal artifact — specifically the `## Supersedes` section:
  - `mem_search(query: "sdd/{change-name}/proposal")` → `mem_get_observation(id)`.
  - If not found and Engram not reachable: proposal content passed inline from orchestrator.

### Step 2 — Analyze dependencies between tasks

I identify the natural implementation order:

- Types/interfaces before their usage
- Providers/services before their consumers
- Schema/migration before the code that uses them
- Unit tests alongside the code (not at the end)
- **Removals and replacements BEFORE additions** (see Step 3 below)

### Step 3 — Generate removal tasks from Supersedes section

#### Step 3a — Check Supersedes

1. Read `## Supersedes` from proposal.md.
2. **If section is absent** (older archived change): log `INFO: no Supersedes section in proposal.md — skipping removal task generation` and proceed to Step 4 with standard phase organization.
3. **If section states "None — purely additive change"**: skip removal task generation; proceed to Step 4.
4. **If section has REMOVED or REPLACED items**: proceed to Step 3b.

#### Step 3b — Generate removal/replacement tasks

For each **REMOVED** item in Supersedes:
- Generate one task titled `Remove: [feature name]` with:
  - File paths to delete or modify
  - Acceptance criterion: "File deleted AND no runtime errors in related flows"
  - Spec reference: linked spec requirement name (if spec exists for this removal)

For each **REPLACED** item in Supersedes:
- Generate two tasks in dependency order:
  1. `Remove old: [old feature name]` — delete/unregister the old implementation
  2. `Implement new: [new feature name]` — add the replacement (link to spec requirement)
- Note explicit dependency: task 2 cannot start until task 1 is complete.

#### Step 3c — Phase 1 organization

All removal and replacement tasks (from Step 3b) MUST be grouped into **Phase 1: Removals and Replacements**. Standard addition/implementation tasks start from Phase 2 or later. Phase 2 MUST NOT begin until Phase 1 is complete — enforce this with an explicit sequencing note in tasks.md.

**Removal task format:**
```markdown
### Phase 1: Removals and Replacements

- [ ] 1.1 Remove: [feature name] from `path/to/file`
  Linked spec: [Requirement name from spec, or "N/A — no spec for this removal"]
  Files: `path/to/file` (DELETE), `path/to/other.ts` (remove registration/import)
  Acceptance: File deleted AND related flows continue without runtime errors

- [ ] 1.2 Remove old: [old feature name] from `path/to/old-file`
  Linked spec: [Requirement: Replacement requirement name]
  Files: `path/to/old-file` (DELETE or MODIFY)
  Acceptance: Old implementation fully removed; no lingering imports or references

- [ ] 1.3 Implement new: [new feature name] in `path/to/new-file`
  Linked spec: [Requirement: new feature requirement]
  Depends on: 1.2
  Files: `path/to/new-file` (CREATE or MODIFY)
  Acceptance: New implementation active; spec scenarios pass

---
⚠️ Phase 2 MUST NOT begin until all Phase 1 tasks are complete.
---
```

### Step 4 — Organize addition tasks into phases

I group addition/implementation tasks into logical phases after Phase 1 (or Phase 1 if no removals):

```
Phase 1 — Removals and Replacements [if Supersedes has items] OR Foundation [if purely additive]
Phase 2 — Foundation: types, interfaces, schemas, configuration [if Phase 1 is Removals]
Phase N — Core: main business logic
Phase N+1 — Integration: connect with the rest of the system
Phase N+2 — Testing: tests for previous phases
Phase N+3 — Cleanup: remove temporary code, update docs
```

(I adapt phase names to the context of the change)

### Step 5 — Create tasks.md

#### Step 4a — Warning Classification Rules

While analyzing each task, I MUST identify ambiguities, risks, or open decisions that could affect implementation. For each one found, I classify it as one of:

- **`MUST_RESOLVE`** — A warning that blocks implementation until the user provides an explicit answer. Use this when:
  - The task involves a business rule decision that has multiple valid interpretations
  - The task depends on an external system behavior that is ambiguous (e.g., which field to use in an API response)
  - The task cannot be implemented correctly without knowing the user's intent
  - Example reason: `"business rule decision — external system behavior is ambiguous"`

- **`ADVISORY`** — A warning that is logged for awareness but does not block implementation. Use this when:
  - The concern is a performance consideration that does not affect functional correctness
  - The concern is a style or naming preference with no impact on task completion
  - The concern is informational and the implementer can safely proceed without further input
  - Example reason: `"performance consideration — does not affect correctness"`
  - Example reason: `"style or naming preference — no impact on current task"`

Each warning classification MUST include a reason statement explaining why it belongs in its category.

#### Step 4b — Record warnings in tasks.md

Every warning identified in Step 4a MUST be recorded inline with the affected task in `tasks.md`, using the following formats:

**MUST_RESOLVE format:**

```markdown
- [ ] X.Y Task description [WARNING: MUST_RESOLVE]
  Warning: [human-readable warning text]
  Reason: [classification reason, e.g., "business rule decision — external system field ambiguous"]
  Question: [clarifying question derived from the warning]
```

**ADVISORY format:**

```markdown
- [ ] X.Y Task description [WARNING: ADVISORY]
  Warning: [human-readable warning text]
  Reason: [classification reason, e.g., "performance consideration — does not affect correctness"]
```

Placement rules:
- Warnings appear immediately below their task entry, indented with two spaces
- A task may have at most one warning entry (combine multiple concerns into one if needed)
- Tasks without warnings have no indented block below them

**Example task with MUST_RESOLVE warning:**

```markdown
- [ ] 2.1 Create `src/services/payment.service.ts` with method `processPayment(dto: PaymentDto): Promise<PaymentResult>` [WARNING: MUST_RESOLVE]
  Warning: Stripe invoice field for failure date is ambiguous — `status_transitions.marked_uncollectible_at` vs `status_transitions.voided_at` may both apply depending on invoice state.
  Reason: business rule decision — external system behavior is ambiguous
  Question: Which S