sdd-apply git:20260510.dd1c313A

Immutable. This exact content is served forever at /api/v1/blob/41b9e3824d962ce8.

---
name: sdd-apply
description: |-
  Use when implementing tasks from a change's tasks.md. Triggers: "apply tasks", "implement the change", "work through tasks", "start implementing", "continue implementing", "apply the change".
---

# SDD Apply

Implement tasks from `SPECS_ROOT/changes/<name>/tasks.md`.
Check off each task as it completes.

> `SPECS_ROOT` is resolved by the `sdd` router before this skill runs.
> Replace `.specs/` with your project's actual specs root in all paths below.

## Invocation Notice

- Inform the user when this skill is being invoked by name: `sdd-apply`.

## Hard Gate

**If `tasks.md` does not exist for the active change: STOP.**

> "No tasks to implement. Run `sdd-propose` first to create the change artifacts."

Do not proceed without tasks.md.

## Critical Constraints

**Never reference ephemeral scaffolding in any persisted artifact.**

Ephemeral scaffolding includes:

- Task IDs and task numbers (e.g. `Task 7.4`, `T12`)
- Group names and group numbers (e.g. `Group 8`, `G3`)
- Design-section IDs (e.g. `D12`, `design §4.2`)
- Other planning-artifact identifiers that won't outlive the change

These must not appear in:

- Code, symbols, or filenames
- Comments or docstrings
- Commit messages (subject, body, or footer)
- PR titles or descriptions
- Any other artifact that persists after the change is archived

Tasks, groups, and design-section IDs are scaffolding for the current change.
Once archived, only the spec name persists — references to ephemeral IDs become meaningless noise to future readers.
Name things after _what they do_, not where they came from in `tasks.md` or `design.md`.
If you catch yourself writing "D12 wiring" or "Task 7.4 implementation," restate it in terms of the behavior or component being changed.

**This applies whether or not the `commit-message` skill is available.**
When drafting a commit message during apply:

- Prefer invoking `commit-message` if it is loadable in this environment.
- Otherwise, draft a Conventional Commit (`type(scope): subject`) that describes _what changed and why_, and apply the constraints above.
- Do not paste design or task identifiers into the message even if they appear in the surrounding tasks/design files.

## When to Use

- A change has `tasks.md` and implementation should begin or continue
- Resuming implementation after a pause

## When Not to Use

- No `tasks.md` exists — run `sdd-propose` first
- All tasks complete — run `sdd-verify`, then `sdd-sync`, then `sdd-archive`

## Process

### Phase 1: Load Context

1. Confirm which change to apply (ask if multiple active changes exist)
2. Read `.specs/changes/<name>/tasks.md` — full task list
3. Read `.specs/changes/<name>/design.md` — architectural decisions to follow
4. Read `.specs/changes/<name>/specs/` — delta specs for behavioral requirements
5. Read `.specs/specs/` — baseline specs for full context
6. Check task ordering against `references/sdd-change-formats.md` § 4 — each task should depend only on capabilities built by earlier tasks.
   The schema-config rule below is the named instance: if `.specs/.sdd/schema-config.yaml` exists, identify tasks that define schema contracts (endpoint definitions, model schemas, DDL changes) and confirm they are sequenced before any tasks that consume them.
   Surface any ordering gaps to the user before implementing (advisory — the user may decide the order is intentional).

### Phase 2: Identify Starting Point

Check tasks.md for already-completed tasks (`- [x]`).
Start from the first unchecked task.

If all tasks are complete:

> "All tasks are already complete. Run `sdd-verify` to confirm the implementation, then `sdd-sync` and `sdd-archive`."

Stop.

### Phase 3: Implement Task-by-Task

For each unchecked task:

1. **Read the task** — understand what it requires
2. **Check dependencies** — are earlier tasks complete?
   If not, implement them first
3. **Implement** — write the code
4. **Check for newly-emerged write-sites** — see § Write-site emergence below
5. **Test** — run the project's standard test command at its broadest reasonable scope (e.g. `pytest` with no `--ignore` / `--deselect` / `-m` filters).
   Inner-loop iteration may use a narrower scope, but the verification you act on — and any pass/fail count you report — must come from a broad-scope run.
   If you exclude any path, marker, or file, name the exclusion and justify it in the same message.
   "Not part of this change" is not a valid justification for a class or module rewrite — every test that imports the rewritten symbol is part of the change by definition.
   If a test fails, stop and resolve the failure before proceeding to the next step.
6. **Check off** — update `tasks.md`: `- [ ]` → `- [x]`

Follow design decisions in `design.md` — don't diverge without reason.
Follow behavioral requirements in delta specs — these define what "correct" means.
Apply the **Critical Constraints** above to every artifact you produce — code, comments, and commit messages alike.

If `.specs/.sdd/schema-config.yaml` exists and a task consumes a schema contract that is not yet defined, pause before implementing it.
Surface the dependency gap and confirm with the user whether to reorder tasks in `tasks.md` first.

### Write-site emergence

A SHALL requirement may end up with multiple code paths that produce or modify the contract-asserted value during implementation — not just the canonical path.
Common examples: deduplication shortcuts, cache fast-paths, retry/fallback branches, idempotency early-returns, merge or composition steps that write the same fields.

When implementing a task introduces such a path for an existing SHALL:

1. **Pause before checking off** the implementation task.
2. **Add a paired test task** to `tasks.md` that exercises the contract _through the new path_.
   The new test task must produce runnable evidence (test, schema check, or captured output) — same standard as the original SHALL coverage rule.
3. **Implement the test** as part of the same work, or sequence it as the immediately-following task.
4. **Then** check off the original implementation task.

A test exercising only the canonical path does not stand in for evidence on a shortcut, retry, or composition path.
This rule is what `sdd-verify`'s write-site enumeration is checking; cover it at apply time and verify has nothing to flag.

When unsure whether a path is contract-relevant, surface it to the user rather than skipping the test task silently.

### Phase 4: After All Tasks

**Before checking off the final task** (hard gate):

1. Run the full suite as CI would — no programmatic exclusions unless they appear in the project's CI config.
2. `rg`/`grep` for tests that import any symbol you changed and confirm they ran in step 1.
   The blast-radius check is what catches tests pinned to rewritten classes or modules that a marker filter would silently skip.
3. Tests rendered obsolete by the change must be deleted or updated with reasoning recorded in the diff — not silently skipped.
4. Report results with scope alongside counts (e.g. "407 passed, 1 file excluded because…").
   Pass/fail counts without an exclusion list are not a verification report.

When the gate passes and all tasks are checked off:

> "All tasks complete. Recommended next steps:
>
> 1. Run `sdd-verify` to confirm implementation matches the change artifacts
> 2. Run `sdd-sync` to merge delta specs into main specs
> 3. Run `sdd-archive` to complete the change"

## Fluid Workflow

This skill can be invoked at any point after `tasks.md` exists — not only when all artifacts are complete.

- If implementation reveals a design issue, pause and suggest updating `design.md` or delta specs before continuing.
- If scope changes mid-implementation, suggest updating `proposal.md` and `tasks.md`.
- Don't treat the artifact set as frozen — work fluidly, but document changes.

## Common Mistakes

- Implementing without reading design.md (misses architectural decisions)
- Not checking off tasks as they complete
- Implementing tasks out of order when dependencies exist
- Continuing past a failed task without resolving it
- Diverging from design decisions without documenting why
- Treating artifacts as frozen when implementation reveals issues (update them)
- Adding a deduplication shortcut, cache fast-path, retry branch, or composition step for a SHALL-covered value without adding a paired test task that exercises the new write-site (see § Write-site emergence)
- Checking off the implementation task before the paired test task for a newly-emerged write-site is added and runnable
- Referencing ephemeral scaffolding — task IDs, group names, design-section IDs (e.g. `D12`) — in code, comments, commit messages, or PR descriptions (see **Critical Constraints**)
- Drafting a commit message inline without invoking `commit-message` when it is available, or without applying the **Critical Constraints** when it is not
- Excluding a test file, path, or marker from a verification run without naming the exclusion and justifying it in the same message — especially fatal when the change rewrites a class or module that the excluded tests pin
- Reporting "N passed, 0 failed" without also reporting what was excluded and why — scope must travel with the counts

## References

- `references/sdd-schema.md` — schema config format (§ 3) and lifecycle policy (§ 4)