delivery-discipline
Use when preparing or writing any committable deliverable (phase closeout, status report, skill file, wave spec, README section, summary document, CHANGELOG entry, or any markdown file declaring completion or pass/fail status). Applies before the write happens, not after. Without this discipline, agents ship 60% deliverables and declare closure prematurely.
th3vib3coder · AI review on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add th3vib3coder/vibe-science --skill delivery-disciplineAbout this skill
name: delivery-discipline description: Use when preparing or writing any committable deliverable (phase closeout, status report, skill file, wave spec, README section, summary document, CHANGELOG entry, or any markdown file declaring completion or pass/fail status). Applies before the write happens, not after. Without this discipline, agents ship 60% deliverables and declare closure prematurely.
Delivery Discipline
Overview
Agents trained to optimize for completion will ship 60% of what's needed and declare the work closed. The pattern is reproducible. Scientific truth is protected by the existing hooks (confounder harness, R2 review gate, Salvagente Rule). Delivery completeness is not. This skill closes that gap.
You (the agent) must apply the 4 rules below BEFORE writing any deliverable that will declare anything CLOSED, PASS, DONE, SHIPPED, COMPLETE, FINALIZED, or READY in a commit-relevant markdown file. A PreToolUse hook will block your write if you skip the attestation block defined below. A CI validator will catch bypasses.
When To Use
Activate before writing:
- Any
*closeout*.md,*status*.md,*summary*.md,*verdict*.md - Any
phase*-*.md,wave*-*.md,sprint*-*.md - Any
skill*.md, SKILL.md updates - Any
README.mdorCHANGELOG.mdentry that declares a version/release/completion - Any document declaring a gate PASS, a phase CLOSED, a release SHIPPED
Do NOT activate for:
- Normal prose that mentions "done" in casual context ("I closed the file")
- Code files (
.js,.py, etc.) — the skill governs deliverables, not source - Exploratory notes that do NOT declare closure
The 4 Non-Negotiable Rules
Rule 1 — Surface mapping before writing
Before you write a deliverable that will declare anything CLOSED / PASS / DONE / SHIPPED / COMPLETE, you MUST have a mechanical inventory of what should be covered.
- If the inventory was produced by a subagent (Explore, general-purpose, etc.), you verify at least the critical claims directly before trusting it. Read the actual files the subagent describes. API signatures, file paths, function exports get verified first-hand, not assumed.
- Optimistic sampling is failure. "I covered the main cases" means you haven't looked at the edge cases.
Rule 2 — Explicit scope cuts
Every deliverable MUST declare, in its own body, what was LEFT OUT and why.
- A scope-cut list of 0 items is suspicious by default. If your solution covers "everything", you probably haven't looked hard enough.
- Force yourself to name at least one cut. If you genuinely cannot find one, state that explicitly and pass self-review (Rule 4) first.
Rule 3 — Completeness proof by enumeration
When you declare closure, list the concrete items verified. Not "all tests pass" but "26 items in the surface map, 22 verified directly with Read tool, 4 delegated to subagent report and cross-checked". Enumeration beats summary.
Rule 4 — Adversarial self-review before closure
Before you write "CLOSED" / "PASS" / "DONE", ask yourself: "What would a skeptical reviewer attack?" List at least 3 findings. If you find 0, assume you haven't looked hard enough and go back to Rule 1.
The Attestation Block (MUST appear in every deliverable declaring closure)
Format: a ## Delivery Attestation section (case-insensitive, ## or
###) containing a fenced json block. The hook extracts the first
fenced json block under that heading and validates it against
skills/vibe/assets/schemas/delivery-attestation.schema.json.
## Delivery Attestation
```json
{
"covered": [
"Concrete item 1 verified (not a summary)",
"Concrete item 2 verified",
"..."
],
"scope_cuts": [
{
"item": "Thing left out of this deliverable",
"reason": "Why it is outside this deliverable (not 'no time')"
}
],
"self_review_findings": [
"Adversarial finding 1 (a skeptical reviewer would attack X because...)",
"Adversarial finding 2",
"Adversarial finding 3"
],
"external_review_status": "pending"
}
```
Field semantics:
covered: array of strings, ≥1 item, each ≥3 chars. Concrete items, not summaries.scope_cuts: array of{item, reason}objects. Empty array allowed but suspicious.self_review_findings: array of strings, ≥3 items required, each ≥20 chars.external_review_status: enum"pending" | "cleared" | "blocked".
Quick Reference
| Intent | Action |
|---|---|
| Writing a phase closeout | Include the ## Delivery Attestation section with filled JSON block |
| Writing a skill file | Include attestation even if short skill — the skill itself is a deliverable |
| Updating CHANGELOG | Attestation required when declaring a release / version |
| Updating README status section | Attestation required when declaring pass/fail or coverage |
| Exempting a file legitimately | Add <!-- delivery-discipline: exempt --> comment near the top. Wave 4 will log this as a delivery_discipline_exemption_used governance event; frequent use becomes an audit target at that point. |
Rationalization Table — DO NOT fall for these
| Excuse | Counter |
|---|---|
| "This is just a small doc, discipline is overkill" | Small docs are where premature closure starts. The attestation takes 60 seconds. |
| "I don't have time for scope cuts" | The cut list takes 30 seconds. Skipping it costs 30 minutes when user pushes back. |
| "Self-review feels self-indulgent" | It's the cheap version of R2. Skip it and you pay in R2 corrections later |