agent-skills/skills/converge-implementation-to-spec/SKILL.md

---
name: converge-implementation-to-spec
description: Use when implementation exists and must be compared against its specification, plan, and task ledger to classify remaining intent gaps and append remediation work. Pairs with verification-before-completion but does not replace or duplicate its independent evidence checks.
---

# Converge Implementation to Specification

Convergence answers “what specified intent is still not represented correctly in the codebase?” It is not a generic final verification pass. Use `verification-before-completion` separately to independently prove completion claims and test results after convergence work is implemented.

## 1. Establish authoritative scope

Read the complete specification, technical plan, current task ledger, and mandatory project principles. Refuse to infer a larger feature from nearby code or conversation history.

Extract named file/component touch-points from the plan and tasks. Expand scope only through repository searches for the exact domain concepts and public interfaces named by the artifacts. Record why each additional file belongs.

If code is sparse or absent, continue: specified obligations are `missing`, not an analysis failure.

## 2. Build an intent inventory

Create one row per:

- functional requirement;
- buildable success criterion;
- user-story acceptance scenario;
- binding plan decision;
- mandatory project principle relevant to this feature;
- existing task whose unchecked intent is not fully represented elsewhere.

```text
Intent key | Source | Obligation | Expected code surface | Evidence sought
FR-008     | spec   | revoke active challenge | recovery service + public entry | state guard and observable outcome
US1/AC2    | spec   | expired challenge cannot mutate credentials | validation path | negative path before mutation
```

Do not count a task checkbox as evidence. The ledger records intent and work history; code and observable tests show realization.

## 3. Inspect implementation by intent

For every row:

1. locate the public entry path and relevant internal owner;
2. read implementation, tests, migrations/configuration, and wiring;
3. compare observable behavior and constraints with the source wording;
4. record concrete evidence by file and symbol or section;
5. create a finding only when intent is not fully represented.

Classify each gap:

- **missing:** no implementation exists;
- **partial:** some path or case exists but the obligation is incomplete;
- **incorrect:** implementation contradicts the intended behavior, constraint, or principle;
- **obsolete:** code or a task represents intent that has been removed or superseded.

Use `obsolete` for awareness and remediation, not as authorization to delete. First determine whether compatibility, migration, or historical data still depends on it.

## 4. Assign severity

- **CRITICAL:** violates a mandatory principle or makes baseline P1 behavior unsafe or impossible.
- **HIGH:** missing/incorrect core requirement or acceptance scenario.
- **MEDIUM:** partial secondary behavior, plan drift with material maintenance cost, or obsolete work of unclear consequence.
- **LOW:** bounded polish gap or low-risk stale surface.

Severity measures consequence, not estimated effort.

## 5. Present findings before writing

```markdown
| ID | Gap | Severity | Source | Evidence | Remediation |
|----|-----|----------|--------|----------|-------------|
| F001 | partial | HIGH | US1/AC2 | `src/recovery.ts` rejects expiry after credential mutation | Move expiry guard before mutation and add a public-path regression test. |
```

Include counts of requirements, acceptance scenarios, plan decisions, and principles inspected, plus findings by gap and severity. Distinguish “no evidence found” from “evidence disproves intent.”

## 6. Append concrete remediation tasks

Do not rewrite settled spec/plan text and do not renumber or edit prior tasks. Append a new `Convergence` phase only when actionable findings exist.

1. find the largest existing task number and phase number;
2. create the next phase at the end;
3. order CRITICAL, HIGH, MEDIUM, LOW;
4. emit one independently completable task per finding;
5. cite the source and gap class;
6. name exact files/symbols when known and observable acceptance evidence.

```markdown
## Phase 7: Convergence

- [ ] T042 **CRITICAL** Enforce the project isolation principle in `src/jobs/dispatch.ts` and cover the public submission path; reject cross-tenant job IDs without reading their payload. (Principle II; incorrect)
- [ ] T043 Move the expiry guard before credential mutation in `src/recovery.ts` and add a real-entry regression test for US1/AC2. (US1/AC2; partial)
```

For an obsolete surface, phrase the task as “review and justify, migrate, or remove,” with explicit compatibility checks. Do not prejudge deletion.

Never add an empty convergence phase. If a prior convergence phase exists, append a newly numbered phase; its old checkboxes are history, not scratch space.

## 7. Repeat until genuinely converged

After remediation is implemented, rebuild the inventory from current artifacts and inspect again. Do not merely check whether appended tasks are marked done. A follow-up may expose a deeper partial or an obsolete workaround.

Stop only when:

- every inventory row has concrete implementation evidence;
- no missing, partial, incorrect, or actionable obsolete finding remains;
- no new out-of-scope behavior requires owner review;
- task ledger has no unchecked convergence work;
- mandatory principles are represented in code and appropriate tests.

Then leave the ledger unchanged and report the counts inspected. Phrase the result as convergence against the defined artifact scope, not proof that the whole product is bug-free.

## 8. Hand off to independent verification

Run the repository’s relevant checks and actual entry paths under `verification-before-completion`. That skill owns the rule that test claims and delegate reports must be independently rechecked. This skill owns intent enumeration, semantic code comparison, gap classification, and remediation-ledger maintenance; do not duplicate generic “run tests and trust the output” guidance here.