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

Read ## Supersedes from proposal.md.
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.
If section states "None — purely additive change": skip removal task generation; proceed to Step 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:

### 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:

- [ ] 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:

- [ ] 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:

- [ ] 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 Stripe invoice field should be used to record the payment failure date?

I persist the task plan to engram:

Call mem_save with topic_key: sdd/{change-name}/tasks, type: architecture, project: {project}, content = full tasks markdown. Do NOT write any file.

If Engram MCP is not reachable: skip persistence. Return task plan content inline only.

Content format:

# Task Plan: [change-name]

Date: [YYYY-MM-DD]
Design: engram:sdd/[name]/design

## Progress: 0/[total] tasks

## Phase 1: [Phase Name]

- [ ] 1.1 Create `src/types/auth.types.ts` with interfaces `LoginRequest`, `LoginResponse`, `JwtPayload`
- [ ] 1.2 Create `src/schemas/auth.schema.ts` with Zod schemas for login validation
- [ ] 1.3 Modify `src/config/jwt.config.ts` — add `refreshSecret` and `refreshExpiresIn`

## Phase 2: [Phase Name]

- [ ] 2.1 Create `src/services/auth.service.ts` with methods `login()`, `logout()`, `refreshToken()`
- [ ] 2.2 Modify `src/repositories/user.repository.ts` — add `findByEmail()` method
- [ ] 2.3 Create `src/middleware/auth.middleware.ts` for JWT validation on protected routes

## Phase 3: [Phase Name]

- [ ] 3.1 Create `src/controllers/auth.controller.ts` with endpoints POST /login, POST /logout, POST /refresh
- [ ] 3.2 Modify `src/routes/index.ts` — register auth routes
- [ ] 3.3 Modify `src/app.ts` — integrate auth middleware on protected routes

## Phase 4: Testing

- [ ] 4.1 Create `tests/unit/auth.service.spec.ts` — unit tests for AuthService
- [ ] 4.2 Create `tests/integration/auth.controller.spec.ts` — endpoint tests
- [ ] 4.3 Verify scenario coverage from spec (review engram:sdd/[name]/spec)

## Phase 5: Cleanup

- [ ] 5.1 Update `README.md` — document new endpoints
- [ ] 5.2 Update `ai-context/architecture.md` if there were structural changes

---

## Implementation Notes

[Design decisions the implementer must keep in mind:]

- [important note 1]
- [important note 2]

## Blockers

[Tasks that cannot start until something external is ready:]

- [blocker]: [what resolves it]

[If none: "None."]

Format of a well-written task

Well written

- [ ] 2.1 Create `src/services/payment.service.ts` with method `processPayment(dto: PaymentDto): Promise<PaymentResult>`

Poorly written

- [ ] Add payment logic

Rule: Each task must answer "which file and what specific change?"

Output to Orchestrator

Return ONLY this JSON block. Do NOT add free-form text, command suggestions, or implementation steps after it.

{
  "status": "ok|warning|blocked",
  "summary": "Plan for [change-name]: [N] phases, [M] total tasks. Estimate: [Low/Medium/High].",
  "artifacts": ["engram:sdd/{change-name}/tasks"],
  "next_recommended": ["sdd-apply"],
  "risks": ["[blocker if any]"]
}

The orchestrator will present next_recommended to the user as /sdd-apply (hyphen-separated, with slash prefix). Do not format it yourself.

Rules

HARD STOP: My only output is tasks.md + the JSON block. I NEVER implement any task, write code, or modify project files beyond creating tasks.md
Each task MUST have a concrete file path
Each task MUST be atomic (single responsibility)
Each task MUST be verifiable (can be marked done with certainty)
Tests go with their code, not all at the end
Phase order respects technical dependencies
Documentation and memory tasks (ai-context) go in the last phase
I do NOT include tasks that go beyond the proposal's scope
If I detect that the design is incomplete to generate tasks, I report it as a blocker