---
name: done-certificates
description: Author a task-specific semi-formal done certificate — a structured verification protocol that a separate validating agent runs to decide whether a task is complete. For each task it restates the definition of done as proof obligations, names the exact evidence to collect and the resolution/regression checks to run, and leaves the status and verdict blank for the validator to discharge. Triggers on "create a done certificate", "add done certificates to the plan", or "generate a completion certificate". Works standalone over any task with a definition of done, and is the companion certificate-author for spec-planner task packages — one certificate per task. To run (discharge) an authored certificate, use validate-done-certificate instead.
---

# Done Certificates

A skill for writing the **verification protocol** that decides whether a task is done — not for running it. For each task it produces a task-specific **semi-formal reasoning certificate**: the definition of done restated as explicit proof obligations, each naming the evidence a validator must collect and the checks it must run, with the status and verdict left blank. A separate validating agent later opens the certificate and discharges it against the code.

The split is the whole point — **this skill authors** (the reasoning about what must be true for the task to be done and how a validator would prove it, tailored to the task's actual DoD, produces, and code surface); **a different agent validates** (collects the named evidence, runs the checks, fills in each status, derives the verdict). The result is a checkable, task-specific contract: a validator following it cannot skip an obligation or call a task done without producing the evidence the certificate demands.

## Core principle

**A definition of done is a claim; a done certificate is the protocol that proves or refutes it.** A spec-planner task ends in a `Definition of done` checklist — a list of obligations stated as boxes to tick. Ticking them by hand is an assertion. This skill turns that checklist into a semi-formal certificate where each obligation names *the evidence required* (a file location to read, a test to run, an execution trace to produce) and *the checks that apply* (function resolution to defeat name shadowing, a regression trace against named callers). The discipline is **semi-formal reasoning** — structured templates that act as certificates: the agent running them cannot skip cases or make unsupported claims. The method is vendored into this skill at [`references/semiformal-method.md`](references/semiformal-method.md).

Two rules follow:

1. **Every definition-of-done item becomes one obligation that names its own evidence.** The certificate does not say "verify the lock works"; it says "verify O1 by running `lock.test.ts › rejects wrong passphrase` and tracing `unlock()` at `src/auth/lock.ts`, confirming it returns before `vault.unlock()`." The obligation is specific enough that any validator collects the *same* evidence.
2. **The certificate is authored blank and discharged by someone else.** Status fields are `☐ unverified` and the verdict is empty when this skill hands the certificate over. Filling them is the validator's job, governed by the rubric the certificate carries. This skill never fabricates evidence or pre-decides the verdict.

## Relationship to spec-planner

This skill is a companion to **spec-planner**, which produces task packages each carrying a `Definition of done` checklist ending in a `Reviewable:` line. Read [`spec-planner`'s `SKILL.md`](../spec-planner/SKILL.md) first if you have not — this skill inherits its `NN-` numbering, append-only rule, and kanban-subfolder layout. done-certificates consumes that checklist and writes the certificate a validator later discharges: **spec-planner** writes *what done means*, **done-certificates** writes *the protocol to prove it*, and a *validating agent* (subagent, reviewer, later session) *runs* it.

The **semi-formal reasoning method** — the premise/claim/evidence/verdict structure and the function-resolution and regression checkpoints — is vendored at [`references/semiformal-method.md`](references/semiformal-method.md), so the skill is self-contained when installed. A done certificate is that method instantiated for one task's DoD.

It is not limited to spec-planner output. Any task with a definition of done — an issue with acceptance criteria, a PRD feature with a "done when" list, a ticket checklist — can have a certificate authored for it; the source shapes how the obligations are read, the certificate structure is the same.

## When to apply this skill

- The user asks to **create, write, or generate a done certificate** for one or more tasks — "create a certificate of done for each of these tasks", "add done certificates to the plan", "make a completion certificate for task 04".
- spec-planner has produced (or is producing) a plan and the user wants **done certificates added** to its task packages so each task ships with the protocol that will later validate it.
- A team wants a **task-specific verification contract** a reviewer or validating agent can run, rather than re-deriving "what does done mean here" each time.

Skip when:

- There is **no definition of done** to build a certificate from — the task has no acceptance criteria and none can be inferred. Ask for them (or, for a spec-planner task, that is a defect in the plan — flag it).
- The task is **trivial and local** — a one-line doc fix whose DoD is "the typo is gone". A certificate adds ceremony without rigor. Say so.
- The request is to *write* the definition of done (that is spec-planner) or to *validate* a task right now (that is the downstream validating agent running an already-authored certificate — this skill writes the certificate, it does not run it). If the user wants you to *both* author and then validate, author the certificate first, then validate it as a separate, explicit step.

## What the certificate is — and who fills it in

A done certificate is a **blank verification protocol specific to one task**. When this skill finishes, the certificate contains:

- a precise **definition** of what done means for this task;
- **premises** about the task's goal, obligations, and invariants;
- one **obligation per definition-of-done item**, each naming the **evidence to collect** and the **checks to run** — but with the **status left `☐ unverified`**;
- a **regression check** naming the downstream callers a validator must trace — left blank;
- a **conclusion** block with the **verdict rubric** spelled out but the **verdict empty**.

See [`references/certificate-template.md`](references/certificate-template.md) for the skeleton and the field conventions.

## Workflow

Three phases. All three are about *authoring* — collecting live evidence and reaching a verdict is the validator's job, downstream and out of scope here.

### Phase 1 — Read the obligations

1. **Locate the definition of done.** For a spec-planner task, read its `NN-snake_case_task.md`: the `Produces` line (the goal), `Depends on` and `Pointers` (the surface), and the `## Definition of done` checklist (the obligations). For any other source, find the acceptance criteria / "done when" list.
2. **Map the task's surface.** From `Pointers`, the steps, and (if the code exists) the files involved, identify the scope-crossing calls and the downstream callers — these become the resolution and regression checks the certificate will tell the validator to run. If the code does not exist yet (planning time), reference the planned entry points from `Pointers`.
3. **Confirm there is something to certify.** If the DoD is empty or absent, stop and flag it (a spec-planner task without a DoD is a defect, per that skill's own checklist).

### Phase 2 — Derive the proof obligations

This is where the reasoning lives — translating a DoD checklist into a protocol a validator can run without re-deriving intent. Following [`references/certificate-template.md`](references/certificate-template.md):

1. **Definition.** State what `DONE` means for *this* task: every obligation below holds, each backed by the evidence the obligation names — not by assertion.
2. **Premises.** `P1` the goal (one sentence, from `Produces`); `P2` the obligation set (one obligation `Oi` per DoD item, in DoD order, the last always the `Reviewable:` item); `P3` the invariants (existing behavior that must not break — the regression surface from Phase 1).
3. **Obligations.** One block per DoD item. Each carries:
   - a **Claim** — the checkable condition the item asserts;
   - **Evidence to collect** — the *specific* artifact a validator must produce: which file:line to read, which named test to run and the result to expect, which execution trace with which input. Specific enough that two validators collect the same evidence. For the **"Meets the repo definition of done"** obligation, draw the concrete commands (the test, lint, and format invocations) from the repo's development guidelines — `.specs/development-guidelines.md` §Definition of done, named in the plan's DoD baseline — **not** from the task's `Pointers`, which carry code entry points rather than build commands. When the commands are not yet pinned down at planning time, name them by role ("the repo's test command", "the lint gate") so the validator resolves them from the guidelines.
   - **Checks** — the task-specific resolution and regression checks that apply (e.g., "resolve `verify()` at `lock.ts:34` — confirm it is the imported crypto `verify`, not the global `crypto.subtle.verify`"). Omit for an obligation with no scope-crossing calls (e.g. "lint passes").
   - a **Status** field, left `☐ unverified` for the validator.

### Phase 3 — Write the validator's rubric and hand off

1. **Regression check.** Name the downstream callers the validator must trace and the expected outcome, left blank for `PRESERVED`/`REGRESSION`. If the task touches no existing code, say so.
2. **Conclusion block.** Spell out the **verdict rubric** (below) so the validator derives, not declares, the verdict — and leave `VERDICT`, `CONFIDENCE`, and `SUMMARY` empty.
3. **Hand off.** State plainly that the certificate is authored and unverified, and that a validating agent discharges it. Do not fill it in yourself unless the user explicitly asks you to also validate — and if so, do that as a separate, clearly-marked step.

The verdict rubric the certificate carries, for the validator to apply:

- **NOT_DONE** — any load-bearing obligation is `UNSATISFIED`, **or** the regression check found a `REGRESSION`.
- **PARTIAL** — every obligation is `SATISFIED` except one or more that are `UNVERIFIED` (the available context could not prove them), and no regression.
- **DONE** — every obligation `SATISFIED`, regression check `PRESERVED`, and the evidence sufficient to verify each (including the `Reviewable:` obligation). A `DONE` verdict with any non-`SATISFIED` obligation is malformed.

## Where the certificate lives

- **For a spec-planner plan:** one certificate per task **co-located beside its task**, named `NN-snake_case_task-certificate.md` (the `-certificate` suffix avoids colliding with the task's own `NN-snake_case_task.md` in the same folder). It is authored into `backlog/` alongside its still-unbuilt task and moves with the task through `in-progress/` (or `blocked/`) and into `done/` as a single unit — there is **no** dedicated `certificates/` subfolder. Because the certificate and task always share a directory, their cross-links are same-directory and survive every move unchanged: the certificate links to its task as `[NN-…md](NN-…md)` and to the plan as `[plan.md](../plan.md)`; the task file carries a `**Certificate:** [NN-…-certificate.md](NN-…-certificate.md)` line in its header so the link is two-way.
- **Standalone (no plan folder):** write to `.specs/certificates/<snake_case_task>.md`, or alongside the artifact the task lives in if the user names a location. Link to whatever defines the task's DoD.

Numbers are append-only, exactly as in spec-planner: a certificate keeps its task's number, and a task added later takes the next free number — the next-free-`NN` scan spans the **union of `backlog/`, `in-progress/`, `blocked/`, and `done/`** (everywhere a task can sit), not a single folder.

## When invoked by spec-planner

spec-planner may delegate here after Phase 4, when done certificates are part of the plan. The DoD baseline, owner, and task numbering are already established — do not re-derive them. Write one certificate per task file **beside its task in `backlog/`** (see [§Where the certificate lives](#where-the-certificate-lives)), add the two-way `**Certificate:**` link to each task header, and leave every certificate unverified. spec-planner owns the plan and its cross-link pass; done-certificates authors certificates into `backlog/` and owns their content; spec-builder owns moving them (with their tasks) between subfolders as the build runs.

## What NOT to do

- **Don't validate from this skill.** Authoring the certificate and running it are different jobs done by different agents. This skill writes the protocol; it leaves status and verdict blank. Validate only if the user explicitly asks, and then as a separate, marked step.
- **Don't write vague obligations.** "Verify it works" is not an obligation. Name the file, the test, the trace, the caller. A second validator must be able to collect the same evidence from your obligation alone.
- **Don't fabricate or pre-fill evidence.** Evidence is collected by the validator against real code. The certificate names *what* to collect, not a guessed result.
- **Don't restate the task or the spec.** The certificate references the task file and names the DoD items; it does not reproduce the steps. A reader opens the task alongside the certificate.
- **Don't author beyond the definition of done.** The certificate's obligations are exactly the DoD items, one to one. Quality concerns outside the DoD belong in `Residue` as notes, not as new obligations — the DoD is the contract.
- **Don't renumber certificates.** They mirror the task numbers, which are append-only.
- **Don't write a certificate for a trivial change.** Ceremony without rigor.

## Reference files

- [`references/semiformal-method.md`](references/semiformal-method.md) — The vendored semi-formal reasoning method: the certificate shape (definition / premises / claims / evidence / conclusion), the function-resolution checkpoint (the 5-step name-resolution sequence), the execution-trace and regression checks, and the verdict rubric. The self-contained basis for everything this skill writes. Read first.
- [`references/certificate-template.md`](references/certificate-template.md) — The done-certificate skeleton (definition, premises, obligations with evidence/checks/status, regression check, residue, conclusion with the verdict rubric), the blank-field conventions for hand-off to a validator, and a worked example of an authored (unverified) certificate. Read before Phase 2.