sdd-apply

What this skill does

# sdd-apply

> Implements the plan tasks following specs and design, marking progress as it
> goes.

**Triggers**: `/sdd-apply <change-name>`, implement change, write code, apply changes, sdd apply

---

## Purpose

The implementation phase converts the task plan into real code. The implementer
follows the specs (WHAT to do) and the design (HOW to do it), marking tasks as
completed in real time.

## Skill resolution

Project-local → global, in order:

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

See `docs/SKILL-RESOLUTION.md` for the full algorithm.

---

## Process

### Step 0 — Preload

**0a. Project context** — follow `skills/_shared/sdd-phase-common.md` **Section F** (Project Context Load). Non-blocking.

**0b. Spec context preload** — follow `skills/_shared/sdd-phase-common.md` **Section G** (Spec Context Preload). Non-blocking.

**0c. Tech skill preload**:

1. **Scope guard** — read `design.md` File Change Matrix via `mem_search`/`mem_get_observation`. If every file extension is in `[.md, .yaml, .yml]` → documentation-only. Report `"Tech skill preload: skipped (documentation-only change)"` and skip the rest of Step 0c.
2. **Stack detection** — sources, in priority order:
   - Primary: `ai-context/stack.md` — extract technology keywords (case-insensitive, free text).
   - Secondary: `config.yaml` at project root — read `project.stack` keys.
   - Neither → report `"Tech skill preload: skipped (no stack source found)"` and skip.
3. **Stack-to-skill mapping** (case-insensitive substring match, top-to-bottom):

| Keyword(s)                | Skill path                                    |
|---------------------------|-----------------------------------------------|
| always (non-doc changes)  | `~/.claude/skills/solid-ddd/SKILL.md`         |
| react native, expo        | `~/.claude/skills/react-native/SKILL.md`      |
| react                     | `~/.claude/skills/react-19/SKILL.md`          |
| next, nextjs, next.js     | `~/.claude/skills/nextjs-15/SKILL.md`         |
| typescript, ts            | `~/.claude/skills/typescript/SKILL.md`        |
| zustand                   | `~/.claude/skills/zustand-5/SKILL.md`         |
| tailwind                  | `~/.claude/skills/tailwind-4/SKILL.md`        |
| go, golang                | `~/.claude/skills/go-testing/SKILL.md`        |

Order matters: `react native`/`expo` come before `react`. The `always` row is skipped when the scope guard triggered.

4. **Load** — for each matched path: file exists → read and load patterns into context; absent → skip silently with note `"<skill-name>: skipped (file not found at <path>)"`. This step MUST NOT produce `status: blocked` or `status: failed`.
5. **Report** — list loaded skills + skipped ones. Carry the list to Step 2 detection output: `"Technology skills loaded: [typescript, react-19, tailwind-4]"` (or `"none"`).

**0d. Initialize retry counter**:

- Read `apply_max_retries` from project `config.yaml` if present. Otherwise default to `3`.
- Initialize `attempt_counter = {}` (in-memory, per-invocation). Each `/sdd-apply` run starts fresh.
- When `attempt_counter[task_id] >= max_attempts` before a new attempt → task immediately `[BLOCKED]`, phase halts. User must resolve and re-run `/sdd-apply` to resume.

### Step 1 — Read full context

Read in this order:

1. Tasks artifact — `mem_search(query: "sdd/{change-name}/tasks")` → `mem_get_observation(id)`. Engram unreachable → orchestrator passes inline.
2. Spec artifact — same pattern with `sdd/{change-name}/spec`.
3. Design artifact — same pattern with `sdd/{change-name}/design`.
4. Project `config.yaml` (if present) — read `diagnosis_commands` and `rules`.
5. `ai-context/conventions.md` — code conventions.
6. Existing code files to be modified or used as pattern references.

### Step 2 — Detect implementation mode (TDD vs standard)

Check three sources in priority order:

**Source 1 — explicit config** (highest priority): read `config.yaml` for `tdd` key.

- `tdd: true` or `tdd.enabled: true` → TDD **ON**. Report `"TDD mode: ON (source: config)"`. Skip Sources 2 and 3.
- `tdd: false` or `tdd.enabled: false` → TDD **OFF**. Report `"TDD mode: OFF (explicitly disabled in config)"`. Skip Sources 2 and 3.
- Key absent → continue.

**Source 2** — testing skills in project CLAUDE.md (`playwright`, `pytest`, `vitest`, `jest`, etc.) → `signal_count++`.

**Source 3** — test file patterns in codebase (`*.test.*`, `*.spec.*`, `test_*`, `*_test.*`) → `signal_count++`.

| `signal_count` | TDD | Report                                                  |
|----------------|-----|---------------------------------------------------------|
| ≥ 2            | ON  | `"TDD mode: ON (source: testing skill + test files)"`   |
| 1              | OFF | `"TDD mode: OFF ([signal found] but insufficient signals)"` |
| 0              | OFF | `"TDD mode: OFF"`                                       |

This step MUST NOT install frameworks, create test files, or modify config.

### Step 3 — Verify work scope

The orchestrator specifies which tasks to implement (e.g. "Phase 1, tasks 1.1–1.3").
Implement ONLY those. Do not advance to the next ones without confirmation.

### Step 4 — Diagnosis

Before any file change for an assigned task: a `DIAGNOSIS` block MUST be written.
No file write or edit is permitted until then.

**4.1** Read every file to be modified in its current state. For file-creation tasks, read related files used as pattern references.

**4.2** Run diagnostic commands from `config.yaml` `diagnosis_commands` if present (read-only expected). Non-zero exit recorded as failure in the Risk field but does NOT block. Absent → use auto-detected read-only commands relevant to the task or none. Note `"diagnosis_commands: not configured"`.

**4.3** Write the `DIAGNOSIS` block in the task output:

```
DIAGNOSIS — Task X.Y:
  1. Files to be modified: [list of paths]
  2. Diagnostic command outputs:
     - [command]: [output summary]
     (or "none applicable" / "diagnosis_commands: not configured")
  3. Current behavior observation: [what the code actually does now]
  4. Relevant data/state: [key data values, config, environment state]
  5. Hypothesis: "The bug/issue is [X] because [Y].
     Changing [Z] will achieve [expected behavior] because [rationale]."
  6. Risk: [what could go wrong with this change]
```

For file-creation tasks: field 3 describes the gap (what is absent); field 5 describes what the new file is intended to do and why.

**4.4 Contradiction check** — if diagnosis reveals the current state contradicts task assumptions, produce a `MUST_RESOLVE` warning and pause:

```
⚠️ MUST_RESOLVE — Diagnosis finding:
  Task X.Y assumes [A], but current state shows [B].

  This may indicate the task description is based on incorrect assumptions.

  Confirm how to proceed:
  Option 1: [proceed with updated understanding]
  Option 2: [revise task description]
```

Multiple contradictions → list each in the same `MUST_RESOLVE` block and wait for one combined confirmation. No contradictions → proceed to Step 5.

### Step 5 — Implement task by task

**5a. Warning check before each task** — inspect the task entry in `tasks.md`.

| Marker                                  | Behavior |
|-----------------------------------------|----------|
| `[WARNING: MUST_RESOLVE]` no `Answer:`  | STOP. Present blocking gate (template below). Wait for user. Record answer + ISO timestamp. NEVER offer "Ready to continue?" or any bypass. |
| `[WARNING: MUST_RESOLVE]` + `Answer:`   | Already resolved. Proceed. |
| `[WARNING: ADVISORY]`                   | Log `"ℹ️ ADVISORY — Task X.Y: [text]"` and proceed. NEVER request user input. |

Blocking gate template:

```
⛔ BLOCKED — Task X.Y has an unresolved MUST_RESOLVE warning:
  [warning text from tasks.md]

You must answer before implementation can proceed:
  → [Question from tasks.md or derived from warning]

Ty