proof-before-done

proof-before-done

A reusable skill that gates "done" claims with an eight-question verification protocol. The operational implementation of incremental engineering at the agent layer.

When an AI engineering agent (Claude Code, Codex, or any agent that consumes skill files) is about to claim work is "done," this skill fires and forces the agent to answer a specific set of questions in writing before the claim propagates downstream. Each question targets a recurring failure mode of agent-generated work.

The gate fires on every done-claim — there is no opt-out. What scales is depth: routine work passes with a short written statement, while risky surfaces (auth, migrations, deploy config, cross-service contracts, money paths) get the full eight questions. An agent that has mis-assessed its work will also mis-assess whether it needs a gate, so the decision to run it is not the agent's to make.

The eight questions

1. Does my count match my list? Recount from ground truth, never from memory or from what the previous step said.
2. Did I test what I asserted, or did I assert it? An unverified claim is fine when labeled unverified. Silent assertion is not.
3. Are my magic numbers justified at the call site? Why 24h and not 12h, one line away from the constant.
4. Are my string-encoded keys schemaed? One encoder, one decoder — not eighteen callers composing the same identifier inline.
5. What does my work NOT solve? Written before the "what landed" section, or you don't know the boundary of what you fixed.
6. Does my verification floor match my claim? A type-check proves syntax. If the claim is about runtime behavior, downgrade the claim or raise the floor.
7. Is my framing honest about what I did? Re-read the opening sentence. Does it claim more than the floor proves?
8. Did the verification's inputs come from reality, or from me? ← the one most teams are missing

Question 8 is the one that catches what the other seven structurally cannot. The first seven test whether the work was executed correctly; none of them tests whether the premise was right. If you wrote the artifact and also wrote its test fixtures, a green suite proves the two agree with each other — both can encode the same wrong assumption, so the suite cannot fail. For anything whose job is checking other work (a hook, a linter, a validator, a parser, an audit script), an invented fixture is an automatic block: capture at least one real input first.

The upstream companion

proof-before-done is the downstream half of a two-gate discipline:

Together they bracket every deliberate change: one gate at the moment you decide to change something, one at the moment you claim it's finished. Each stands alone — installing this skill does not require the other.

What's in this repo

Two files, both useful on their own, more useful together:

• SKILL.md — the portable skill. Copy it into your project's .claude/skills/ directory (or your agent's equivalent), fill in four placeholders, and the gate is installed.

• INCREMENTAL-ENGINEERING.md — the longer methodology document that explains why the skill produces the results it does. Read this if you want to understand the discipline; skip it if you just want the tool.

Why this exists

Agents reach the bar the human holds, not the bar they state. Without an explicit gate at every step of the work, agents propagate plausible-looking "done" claims that don't survive contact with production. The cost compounds: each unverified step becomes a foundation that subsequent steps build on, and the bugs you find later are exponentially more expensive than the bugs you would have caught at the gate.

This skill is the gate. It is small, deliberate, and load-bearing. It was developed inside a multi-repository production codebase (ComOS — an AI-native commerce platform) and validated when a single afternoon's worth of work, run through the discipline, compressed roughly three weeks of architectural design into four hours across four repositories.

The QC series — what the gate produces at scale

The emergent behaviors this gate creates when run without exception — a corpus that converges instead of drifting, hunts its own flaws before symptoms appear, and learns its own shape — are documented in an eight-part series written from the production system the skill governs. Start at Part 1:

1. The Skill That Grew a Mind
2. Why "Done" Is the Most Dangerous Word in Software
3. The Cure Is Cheap Because the Cause Is Close
4. Self-Healing Is Search
5. Question Everything — Especially Your Own Thoughts
6. The Gate Binds Its Own Builders
7. The Corpus Is a Neural Network
8. The Quality of Your Aim — The Honesty Ratio Is the Loss Curve

Parts 1–5 make the case for why the gate works. Parts 6–8 show what it does at scale, including the constraints that bind the gate's own authors (Part 6) and the persisted loss curve the whole discipline optimizes (Part 8). If the README's neural-network framing below reads as metaphor, Part 7 is the article that argues it is structure.

What the skill is, structurally

The skill is not a checklist. It is a small neural network for high-quality coding, operating at the agent layer:

• Activation function — the eight questions act as a per-step gate that decides whether "done" signals propagate forward to downstream work. Below the threshold (any question fails or is silent), work is reworked. At the threshold (all pass at the depth the work warrants), downstream work can safely depend on this step.

• Backpropagation — when the gate catches a failure, the correction signal flows backward through the layers of work that produced it. The specific assertion, the reasoning chain, the missing convention, the discipline that didn't fire — each gets a credit-assigned update. Your team's documentation is the weight matrix; failures caught by the gate update the weights.

• Bounded iteration — question 5 (what does my work NOT solve?) forces explicit scope declarations. This is what makes the methodology converge rather than thrash. Each iteration's contribution is scoped; future iterations land against a clear seam.

That mapping isn't decorative. The skill behaves like a network: forward pass produces the work, the activation function gates the "done" signal, the loss function (your judgment) fires when work falls short, backprop credit-assigns the correction, the weights (your docs) update permanently. Over many iterations, the network learns to catch its own failures before the human has to.

What you actually get when you install

The skill is the architecture of a quality-coding network. The weights — your team's accumulated documentation, conventions, decision logs, contributor docs — are what make the network produce your team's quality, not generic quality. Installing the template gives you the architecture. The firs