---
name: apply-spec-deltas
description: Apply triaged spec deltas (from spike findings, defect-scan corrections, post-implementation discoveries, or any source proposing changes to a finished reimplementation spec) without rubber-stamping. Use this skill after the pipeline has produced a complete reimplementation-spec and a separate source has surfaced changes the spec should absorb. The skill enforces triage discipline (apply blockers, defer nice-to-haves, reject what doesn't fit), preserves traceability via [revised per <source> §<delta-id>] citations, and produces a DELTAS-APPLIED.md audit table.
---

# Apply Spec Deltas

Use this skill when:

- The pipeline has produced a complete `findings/reimplementation-spec/reimplementation-spec.md` (the spec is `complete` in status.yaml).
- A separate source has surfaced changes the spec should absorb. Common sources:
  - **Spike reports** (`scratch/spikes/<spike-id>/<scenario>.md`, written from `templates/spike-report.md`, plus an optional `CONSOLIDATED-DELTA.md` when several scenarios merge).
  - **Defect-scan re-runs** that find corrections to spec text.
  - **Implementation discoveries** that contradict spec assumptions (e.g., a wire format the spec misread).
  - **Maintainer rulings** that close prior open questions.

This is a **post-pipeline** activity. `current_phase` stays `complete`. The spec is updated in place; no phase status changes.

## Core posture: triage, do not rubber-stamp

The single rule of this skill: **don't apply deltas verbatim without thinking.** Every delta gets categorized, and only some get applied. Rubber-stamping a delta list produces an incorrect spec — the discipline is the value.

Triage every delta into one of four buckets:

| Bucket | Definition | Action |
|---|---|---|
| **APPLY** | Delta is a real correction or required addition; the spec is wrong without it. | Edit the spec body. Add a `[revised per <source> §<delta-id>]` marker at the changed section. Record in DELTAS-APPLIED.md. |
| **CLARIFY** | Delta proposes wording change; the spec's *meaning* is correct but the language is ambiguous. | Edit the spec wording (not the rule). Record in DELTAS-APPLIED.md as a clarification. |
| **DEFER** | Delta is a real improvement but not load-bearing for the next implementation step. | Add to BACKLOG.md with rationale and a back-reference. Do NOT edit the spec. |
| **REJECT** | Delta is wrong on close reading (premise was incorrect, scope was misread, the rule it proposes already exists, etc.). | Document in DELTAS-APPLIED.md with a one-line rationale. Do NOT edit the spec. |

The previous wisdom: any delta you can't decisively bucket should default to DEFER. The cost of a missed correction is one re-application pass; the cost of a bad correction is shipped.

## Citation convention

Every applied or clarified delta leaves a citation marker in the spec body so a future reader can trace the change back to its source.

```
<original spec text>  [revised per spike-3-cancellation.md §Δ7]
<revised spec text>   [revised per spike-3-cancellation.md §Δ7]
```

The marker form is **canonical**, not per-session: `[revised per <source-filename> §<delta-id>]`. The citation convention list at the front-matter of the spec (or the project's `CONVENTIONS.md`) should include `[revised per ...]` as a recognized form.

## Step-by-step

### 1. Pre-flight

- Confirm `findings/reimplementation-spec/reimplementation-spec.md` is complete (PASS or PASS WITH GAPS validation block).
- Read every delta source named in the session prompt (the spike reports, the defect-scan addendum, the maintainer-decision file).
- Read the spec once end-to-end if you haven't recently. The spec's structure determines where deltas land.
- Read the project's `CONVENTIONS.md` if present — some deltas may be moved into convention entries instead of the spec body.

### 2. Triage every delta

For each delta from each source:

- **Read the delta carefully.** Is the premise correct? Does the affected spec section actually say what the delta claims it says?
- **Categorize: APPLY / CLARIFY / DEFER / REJECT.** Put each delta in exactly one bucket.
- If APPLY or CLARIFY: identify the exact spec section to edit. Note line numbers (or section anchors) for the audit table.
- If DEFER: write a one-line BACKLOG.md entry now, don't wait.
- If REJECT: write a one-paragraph rationale now, don't wait.

### 3. Apply changes (in spec-source order, not delta-order)

- Group APPLY/CLARIFY deltas by the spec section they touch.
- Edit each section once (not once per delta), even if multiple deltas converge on the same section.
- Add the `[revised per <source> §<delta-id>]` citation marker at the changed paragraph.
- After edits in a section, re-read the section in full to confirm it still hangs together — neighboring claims may need adjustment.

### 4. Re-run validation on the spec

Re-run validation per `workflow/VALIDATE.md` against the spec's `completion_criteria`. The spec was PASS or PASS WITH GAPS before; it must remain PASS or PASS WITH GAPS after. If the validation block degrades, the deltas weren't applied carefully — fix the spec body, do NOT soften the validation criteria. (This rule is load-bearing — see the discipline notes in the source feedback.)

### 5. Write DELTAS-APPLIED.md

Use `templates/deltas-applied.md`. The audit table records every delta from every source — APPLY, CLARIFY, DEFER, REJECT — with one row per delta. Future revision passes read this file to know which deltas have already been processed.

### 6. Update the spec's front-matter citation conventions list

If the spec has a "Citation Conventions" section (or similar), confirm `[revised per ...]` is listed as a recognized citation form. If not, add it.

### 7. Closeout

Per the standard closeout ritual:

- Append a one-line entry to `THREAD_LOG.md` pointing at the closeout file.
- Write `closeouts/<YYYY-MM-DD>-spec-deltas.md` using `templates/closeout-template.md`.
- If a delta resolved an `open_questions` entry (or finished a `post_pipeline` backlog item), apply it: write `scratch/amendments/<slug>.yaml` (see `templates/amendment.yaml`) listing the closures, then run `codecarto_amend`. It updates `status.yaml` under the completion lock and writes the amendment closeout — never hand-edit `status.yaml`, which is framework-owned. Without the MCP server, record the intended amendment file in the closeout for the next MCP-capable session to apply.
- Append numbered entries to `DECISIONS.md` for any decisions made during triage that weren't already in the deltas (e.g., "rejected Δ7 because the spec already covered the case at §X").

## What to avoid

- **Don't rubber-stamp.** A delta list is a *proposal*. The spec-delta session decides.
- **Don't soften the spec's validation criteria** to make the post-edit spec pass. If the validation degrades, the spec body is wrong, not the criteria.
- **Don't edit deltas in the source files.** The spike report (or defect addendum, or wherever the delta came from) is read-only. DELTAS-APPLIED.md is the audit; the spike report is the evidence.
- **Don't change status.yaml's current_phase.** This is post-pipeline work; the pipeline is `complete`.
- **Don't apply deltas across spec sections without reading the neighbors.** A claim in §3.2 may depend on a claim in §3.1; editing one without the other produces silent contradictions.

## Output template

Use `templates/deltas-applied.md` for the audit table.