sdd-verify

What this skill does

# sdd-verify

> Verifies that the implementation complies with the specs, design, and task
> plan. The quality gate before archiving.

**Triggers**: `/sdd-verify <change-name>`, verify implementation, quality gate, validate change, sdd verify

---

## Purpose

Verification objectively validates that what was implemented meets what was
specified. It fixes nothing — it only reports.

## Sibling reference file

- `REPORT_TEMPLATE.md` — persisted compact format + conversational detail blocks.

## Skill resolution

Project-local → global, in order:

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

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

---

## Process

### Step 0 — Preload

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

### Step 1 — Load all artifacts

Read in this order:

- Tasks — `mem_search(query: "sdd/{change-name}/tasks")` → `mem_get_observation(id)`. Engram unreachable → orchestrator passes inline.
- Spec — same pattern with `sdd/{change-name}/spec`.
- Design — same pattern with `sdd/{change-name}/design`.
- Code files created/modified.

### Step 2 — Completeness check

Count total tasks vs completed. Emit Completeness block from
`REPORT_TEMPLATE.md`.

**Severity:**
- Incomplete core logic tasks → CRITICAL.
- Incomplete cleanup/docs tasks → WARNING.

### Step 3 — Correctness check (specs)

For each requirement in the spec:
1. Look for evidence in the code that it is implemented.
2. For each Given/When/Then scenario:
   - GIVEN handled (precondition/guard)?
   - WHEN implemented (action/endpoint)?
   - THEN verifiable (correct result)?

Emit Correctness + Scenario Coverage blocks from `REPORT_TEMPLATE.md`.

### Step 4 — Coherence check (design)

Verify design decisions were followed. Emit Coherence block from
`REPORT_TEMPLATE.md`.

### Step 5 — Testing check

Verify test presence and scenario coverage. Emit Testing block from
`REPORT_TEMPLATE.md`.

### Step 6 — Run tests

Three-level priority model. Check `config.yaml` at project root in order:

**Level 1 — `verify_commands`** (highest priority, checked first):

- Present → use the listed commands in order; do NOT check levels 2–3; for each command run via Bash, capture exit code + stdout/stderr; record in `## Tool Execution` with source label `"verify_commands (config level 1)"`.
- Absent → proceed to Level 2.

`verify_commands` is NOT additive — it overrides all lower levels. Commands
are assumed non-destructive; the user is responsible for this.

**Level 2 — `verify.test_commands`** (when Level 1 is absent):

| `verify.test_commands` shape       | Behavior |
|------------------------------------|----------|
| Not a list                         | WARNING: `"verify.test_commands is not a list — treating as absent"`. Fall through to Level 3. |
| Empty list `[]`                    | Treat as absent. Fall through to Level 3 (prevents silent zero-command success). |
| Non-empty list                     | Use commands in order; record source label `"verify.test_commands (config level 2)"`. Skip Level 3. |

**Level 3 — auto-detection** (only when 1 and 2 are absent or invalid).
First match wins:

| Priority | File                                          | Condition                 | Command                                                                                |
|----------|-----------------------------------------------|---------------------------|----------------------------------------------------------------------------------------|
| 1        | `package.json`                                | `scripts.test` exists     | `npm test` (or `yarn test` if `yarn.lock`, `pnpm test` if `pnpm-lock.yaml`)            |
| 2        | `pyproject.toml` / `pytest.ini` / `setup.cfg` | pytest indicators present | `pytest`                                                                               |
| 3        | `Makefile`                                    | `test` target exists      | `make test`                                                                            |
| 4        | `build.gradle` / `gradlew`                    | file exists               | `./gradlew test`                                                                       |
| 5        | `mix.exs`                                     | file exists               | `mix test`                                                                             |
| —        | none of the above                             | —                         | **Skip** with WARNING                                                                  |

**Execution**: run via Bash, capture exit code (0 = pass) + stdout/stderr,
record runner name + command + exit + failure summary.

**Error handling:**

| Condition                                  | Report                                                            | Status  |
|--------------------------------------------|-------------------------------------------------------------------|---------|
| Command not executable (deps missing, etc.) | `"Test Execution: ERROR — [error message]"`                       | WARNING |
| Tests run but some fail                    | Report failure count + failing test names if parseable            | (varies) |
| No test runner detected                    | `"Test Execution: SKIPPED — no test runner detected"`             | WARNING |

Save the full test output for Steps 8 and 9.

### Step 7 — Build & type check

Detect and execute build/type-check command.

**Config overrides** (checked before auto-detection):

| Key                              | Behavior |
|----------------------------------|----------|
| `verify.build_command` (string)  | Use as build/type-check command. Skip auto-detection for build. |
| `verify.build_command` (non-string) | WARNING `"verify.build_command is not a string — treating as absent"`. Fall back to auto-detection. |
| `verify.type_check_command` (string) | Use as type-check command. Skip auto-detection for type check. |
| `verify.type_check_command` (non-string) | WARNING. Fall back to auto-detection. |

Both overrides are independent — one can be set without the other.

**Build command auto-detection** (when override absent or invalid). First
match wins:

| Priority | File                       | Condition                                   | Command                              |
|----------|----------------------------|---------------------------------------------|--------------------------------------|
| 1        | `package.json`             | `scripts.typecheck` exists                  | `npm run typecheck`                  |
| 2        | `package.json`             | `scripts.build` exists                      | `npm run build`                      |
| 3        | `tsconfig.json`            | file exists + TypeScript in devDependencies | `npx tsc --noEmit`                   |
| 4        | `Makefile`                 | `build` target exists                       | `make build`                         |
| 5        | `build.gradle` / `gradlew` | file exists                                 | `./gradlew build`                    |
| 6        | `mix.exs`                  | file exists                                 | `mix compile --warnings-as-errors`   |
| —        | none of the above          | —                                           | **Skip** with INFO                   |

**Execution**: run via Bash, capture exit code, capture error output.

**Error handling:**

| Condition                  | Report                                                      | Status   |
|----------------------------|-------------------------------------------------------------|----------|
| Command not executable     | `"Build/Type Check: ERROR — [error message]"`               | WARNING  |
| Build fails                | `"Build/Type Check: FAILING"