fearovex/sdd-apply

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]

Type your answer to continue.

After answer received, append to the task in tasks.md:

  Answer: [exact text of the user's answer]
  Answered: [ISO 8601 timestamp, e.g., 2026-03-10T14:35:00Z]

5b. Standard flow (TDD not active) — per task:

1. Check warnings per 5a.
2. Read task in tasks.md → extract task_id (e.g., 1.1).
3. Check attempt counter BEFORE attempting:
   • attempt_counter[task_id] undefined → set to 0.
   • attempt_counter[task_id] >= max_attempts → mark [BLOCKED], halt phase, report, STOP.
4. Increment: attempt_counter[task_id]++. Record file_snapshot (files this attempt will modify).
5. Consult specs (success criteria), design (interfaces/decisions), existing code (patterns).
6. Implement the task.
7. Check success:
   • Success (all ops complete, no errors): mark [x] in tasks.md, optionally reset counter to 0, next task.
   • Failure: capture file_snapshot_after and error output.
     • Same-strategy detection vs. previous attempt:
       • Same files modified + identical content changes → [BLOCKED] with "Identical strategy attempted twice — manual intervention required". Halt, report, STOP.
       • Different strategy → counter already incremented; if >= max_attempts → [BLOCKED], halt, report, STOP. Otherwise re-attempt with a different approach (loop to step 6).

Same-Strategy Detection — two attempts are the same strategy when modified-file sets are identical AND content changes per file are identical:

def is_same_strategy(previous, current):
    if set(previous.files) != set(current.files): return False
    for path in previous.files:
        if previous.files[path] != current.files[path]: return False
    return True

If unsure → count as different (conservative default).

5c. TDD flow (TDD active) — per task:

1. Check warnings per 5a.
2. Read task, extract task_id.
3. Check attempt counter (same logic as 5b step 3).
4. Increment counter.
5. Consult specs — identify Given/When/Then scenarios this task covers.
6. Consult design + read existing code.
7. RED — write a failing test capturing the spec scenario. Test name SHOULD reference the scenario. Run the test to confirm it fails. Unexpected pass → report DEVIATION: behavior was already implemented.
8. GREEN — write the minimum code to make the test pass. No extra features, optimizations, or abstractions. Run to confirm pass.
9. REFACTOR — clean up while tests stay green. Run tests after each refactor. If a test breaks during refactor: fix the code (NOT the test).
10. Mark [x] only after REFACTOR is done.

BLOCKED — marking tasks.md (before halting or reporting):

Change - [ ] X.Y description to - [BLOCKED] X.Y description and append:

- [BLOCKED] Task X.Y — description
  - Attempts: N/max_attempts
  - Tried:
    1. [files modified + error]
    2. [files modified + error]
    3. [files modified + error]
  - Last error: [error message from the final attempt]
  - Resolution required: [specific, actionable instruction for the user]

Same-strategy blocks MUST note "Identical strategy detected" in the relevant attempt summary.

BLOCKED — reporting to user (after tasks.md update):

⛔ Task X.Y BLOCKED after N attempts.

What was tried:
  1. [attempt 1 summary]
  2. [attempt 2 summary]
  3. [attempt 3 summary]

Last error: [error from final attempt]

tasks.md updated. Manual intervention required.
Resume after resolving: /sdd-apply <change-name>

After this report, NEVER continue to the next task or phase.

Step 6 — Respect the design

If implementation reveals a design problem:

• Do NOT fix it silently.
• Note it as "DEVIATION: [what and why]".
• If it is a blocker → stop and report status: blocked.

Step 7 — Update tasks.md progress

## Progress: [completed]/[total] tasks

Mark each completed task:

- [x] 1.1 Create `src/types/auth.types.ts` ✓
- [x] 1.2 Create `src/schemas/auth.schema.ts` ✓
- [ ] 1.3 Modify `src/config/jwt.config.ts`

---

Quality Gate

Apply ai-context/conventions.md strictly when present; otherwise follow existing code patterns. Technology skills + solid-ddd are loaded automatically in Step 0c.

Before marking any code task [x], evaluate each criterion. Mark one of: ✅ (satisfied) | ❌ VIOLATION | N/A — [reason].

1. Single Responsibility (SRP) — each new or modified class/function/module has exactly one reason to change. Signal: describe it in one sentence without "and". Otherwise → QUALITY_VIOLATION: SRP — <description>.
2. Abstraction (OCP) — new behavior via extension, not modification. Abstractions justified by current reuse/testability, not speculation. Premature abstraction → QUALITY_VIOLATION: OCP — <description>.
3. Dependency direction (DIP) — high-level modules depend on abstractions (interfaces/ports), not concrete implementations. Outward dependencies on volatile implementations → QUALITY_VIOLATION: DIP — <description>.
4. Domain model integrity — business logic inside domain objects (entities, aggregates, value objects), not leaked into services/controllers. Anemic domain model → QUALITY_VIOLATION: Domain model — <description>. N/A if task does not touch domain code.
5. Layer separation — code respects architectural layers from design. Cross-layer leakage → QUALITY_VIOLATION: Layer separation — <description>.
6. No scope creep — implementation strictly within task scope (tasks.md + design.md). Files/features outside scope → QUALITY_VIOLATION: Scope creep — <description>. Escalate to DEVIATION if it contradicts a spec scenario.
7. Naming clarity — names reveal intent without explanatory comments. If a name needs a comment to be understood, rename it → QUALITY_VIOLATION: Naming — <description>.

Reporting rules:

• N/A — [one-line reason] — criterion does not apply.
• QUALITY_VIOLATION: <principle> — <description> — fix BEFORE marking [x]. If the fix requires scope outside this task → DEVIATION + status: warning.
• Non-contradicting violations do NOT block apply. Orchestrator MUST surface all QUALITY_VIOLATION notes in the phase summary.
• A violation that contradicts a spec scenario MUST be escalated to DEVIATION and MUST set status: warning.

No over-engineering: implement the minimum to pass spec scenarios; do not add features not in the proposal; do not refactor code outside the change.

---

Output to orchestrator

{
  "status": "ok|warning|blocked|failed",
  "summary": "Implemented [N] tasks of [total]. Phase [X] complete. [TDD mode: active — RED/GREEN/REFACTOR cycle used per task.]",
  "tdd_mode": true,
  "artifacts": [
    "src/services/auth.service.ts — created",
    "src/types/auth.types.ts — created",
    "engram:sdd/{change-name}/tasks — updated"
  ],
  "deviations": ["DEVIATION in task 2.1: [description and reason]"],
  "next_recommended": ["sdd-apply (Phase 2) — if more phases remain", "/sdd-verify <change-name> — verify against specs before committing"],
  "risks": []
}

tdd_mode is true when TDD was active, false otherwise. When true, the summary mentions TDD.

Implementation complete — next step: when all phases are done, the only permitted next-step suggestion is:

Continue with verification? Reply **yes** to proceed or **no** to pause.
_(Manual: `/sdd-verify <change-name>`)_

The summary MUST NOT suggest /commit or git commit at any phase.

---

Rules

• Read specs BEFORE writing code — they are the acceptance criteria.
• Follow design decisions — do NOT ignore or silently "improve" them.
• Follow existing project patterns — do NOT introduce new ones without justification.
• Mark tasks completed AT THE MOMENT they finish.
• If a task is blocked, stop and report. Never skip.
• Do NOT implement tasks outside assigned scope.
• Do NOT modify specs or design during implementation.
• If a spec is ambiguous, ask before assuming.
• MUST_RESOLVE warnings MUST block execution until an explicit user answer is received. No skip option.
• ADVISORY warnings MUST be logged but MUST NOT interrupt flow or request input.