ProofBuild

The problem

“code was written” ≠ “the outcome happened”

You ask for password reset. Twenty minutes later you get working-looking code and a fluent paragraph explaining it. Whether the feature actually works is still your problem, and the only ways to find out are reading the diff or shipping it.

That is a structural failure, not a matter of the agent trying harder: two different claims are being made, and one is reported as the other.

What ProofBuild does instead

intent  →  outcome contract  →  proof plan  →  implementation
   →  verification  →  failure analysis  →  repair  →  re-verification
   →  ✓ verified  /  ⚠ review required  /  ✗ blocked

When it activates

No slash command needed. Installed, it is loaded when a request needs it and stays out of the way otherwise — and when it does shape the work, one ⚡ line says so. How the skills work together →

What you actually see

The entire response for a change touching six files:

✓ VERIFIED

Password reset

Requirements   8/8
Tests          47/47
Regression     pass
Changed        6 files

When a decision is genuinely yours, you get the decision — not the narrative:

⚠ REVIEW REQUIRED

Bulk upload · 13/14 requirements verified

Decision required:
A duplicate filename inside one upload batch —

  [overwrite]   [reject the duplicate]   [keep both, suffix the name]

And when it does not work, you get a diagnosis instead of another attempt:

✗ BLOCKED

Checkout · 11/12 requirements verified

CHECKOUT-009  Session expires on wall-clock time, not idle time — an active
              user is signed out mid-checkout.
Cause         expiry derives from session.createdAt; no activity timestamp
              exists on the session record.
Attempts      3 (refresh-on-request, sliding expiry, lastSeenAt column)
Blocker       lastSeenAt changes a schema shared with the mobile token contract.

Decision required: extend the session record, or scope expiry to web only?

The outcome contract

Every meaningful task becomes numbered, individually observable requirements — written before the implementation, because the implementation is built to satisfy them.

objective: "Users can securely reset their password by email"
risk: high
requirements:
  - AUTH-001  A user can request a reset for their email          integration
  - AUTH-003  An unknown email returns the same response          security
  - AUTH-004  A token past its expiry is rejected                 security
  - AUTH-005  A token already used once is rejected on reuse      security
  - AUTH-007  After reset, the old password no longer works       integration
  - AUTH-008  Existing email/password login is unchanged          regression

Five of those eight were never in the request. A requirement is observable — someone outside the codebase could tell whether it holds. “Token handling is secure” is not a requirement; “a reset token is rejected after its first successful use” is.

Contradiction detection

The check that separates a system that verifies from one that narrates. When the agent’s model of the code and the executed output disagree, the output wins — every time.

Reasoning   "the token is invalidated after use — consumeToken() sets used_at"
Observed    the same token reset the password twice, both returning 200

✗ CONTRADICTION — AUTH-005 is not satisfied

A confident, articulate, wrong claim of success is the most damaging thing an AI agent produces. This is the rule that prevents it.

Not a test generator, not a code reviewer

Tests are one proof mechanism among several — chosen after the contract and before the implementation. A suite written afterwards tends to assert what the code does rather than what was wanted.

The repair loop

A failing check is classified before any code changes:

IMPLEMENTATION_ERROR   the code does not do what the requirement says
TEST_ERROR             the check is wrong — and you must show why
CONTRACT_ERROR         the requirement was wrong; amend it visibly
ENVIRONMENT_ERROR      missing service or credential — do not touch the code
EXISTING_REGRESSION    it was already failing; the baseline proves it
UNRELATED_FAILURE      report it, do not absorb it
UNKNOWN                never a final state, and never repaired

A missing dependency is not a broken implementation. Misattribution is how an agent starts rewriting working code to satisfy a failure it never understood. Repair is budgeted — three attempts per requirement, two at high risk, one at critical — and running out produces ✗ BLOCKED with a diagnosis, not a fourth attempt. Weakening a test to make it pass is never a repair.

Risk-based depth

Evidence proportional to risk, in both directions.

A typo does not get a 40-test suite. A payment path does not get a typecheck and a shrug.

Human judgment is a real answer

Some requirements no check can settle. Saying so is what keeps the rest credible — so subjective requests get decomposed into the part that can be proven and the part that cannot.

"Make the settings page feel premium"

  ✓ Level A   Every control reachable by keyboard
  ✓ Level A   Contrast meets WCAG AA            (axe: 0 violations)
  ✓ Level A   Layout holds at 320 / 768 / 1440  (screenshots attached)
  ✓ Level B   Interaction states for every control
  ⚠ Level D   Whether it reads as "premium"     ← yours

Four levels: A an executed check demonstrates it · B several independent checks support it · C partly unreachable in this environment · D human judgment. A Level C or D requirement means ⚠ review required — it never rounds up to verified.

Evidence that outlives the conversation

For substantial work, proof is written down:

.proofbuild/
├── contract.yml            objective, risk, assumptions, requirements
├── proof-plan.yml          the mechanism chosen per requirement
├── evidence/AUTH-005.json  command, expected, actual, status, level
├── reports/latest.md       the full result
└── history/                superseded contracts

{
  "requirement": "AUTH-005",
  "command": "npm test -- reset-password.test.ts -t \"rejects reused token\"",
  "expected": "Second use of a consumed token is rejected",
  "actual":   "PASS — 1 passed. Response: 400 {\"error\":\"token_invalid\"}",
  "status":   "PASS",
  "level":    "A"
}

Never in evidence: tokens, keys, cookies, connection strings, or real customer data — redacted by shape, so the record stays meaningful and safe to commit. A later session, another agent, or you in six weeks can read the contract plus the evidence and know exactly what was claimed, what ran, and what was never verified.

Six worked examples ship with the skill: feature development, bug fix, refactoring, performance, security, and an ambiguous request.

Install

Any Agent Skills-compatible agent

Claude Code

Using it

• “Use proof-driven development for this task.”
• “Implement password reset and prove the acceptance criteria.”
• “Fix this bug — don’t mark it complete until the behavior is verified.”
• “Refactor this service without changing behavior, and show me the proof.”
• “Show the contract.” · “Show evidence.” · “Why is this verified?”

Safety

ProofBuild runs your project’s own checks — its test framework, its commands, its conventions. It does not install a testing stack you did not ask for, and it establishes a baseline first so a pre-existing failure is never blamed on the change.

It will not git reset --hard, git clean -fd, check out over your uncommitted work, force push, commit or push automatically, drop databases, or touch production — unless you explicitly ask for that operation.

Pairs with the other skills

ticket  →  impact-map  →  proof-driven-dev  →  production-guard  →  ship

Impact Map maps what a change will touch before it is written. ProofBuild defines and proves the outcome while it is written. Production Guard asks whether the result is safe to ship. None requires the others.

Limitations

ProofBuild raises the evidence available before you trust a change. It does not guarantee correctness, and no tool that writes your code can.

• It does not replace your tests — it orchestrates the verification your project already has around explicit outcomes
• It cannot verify what the environment cannot run; no database, credential or browser means BLOCKED, not passed
• It cannot verify taste — visual quality, API elegance and architectural fit are Level D by construction
• It is not a security audit; it proves the properties it tested, and that set is always smaller than “secure”
• Contract quality bounds everything — which is why the contract is reviewable before implementation starts
• It costs more than “just write the code”. On a typo that is overhead; on a payments change it is the cheapest part of the week
• Verification systems, testing agents and review agents already exist. The combination here is the contribution, not the category