principle-prove-it-works ยท diff
git:20260827.f7b391a to git:20260907.b1269d9
10 added, 24 removed. Audit A to A.
---
name: principle-prove-it-works
- description: "Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'"
+ description: Choose evidence that verifies the changed behavior and supports the completion claim.
disable-model-invocation: true
---
- # Prove It Works
-
- Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or "it compiles."
-
- **Why:** Unverified work has unknown correctness. Indirect verification (file mtimes, output freshness, agent self-reports, cached screenshots) feels cheaper than direct observation. Acting on a wrong inference costs far more than checking the source.
-
- **Pattern:** After completing any task, ask: "how do I prove this actually works?"
-
- Check the real thing, not a proxy:
- - Check process liveness directly, not indirectly through derived state
- - Read the actual value, not a cached or derived representation
- - When verification fails, suspect the observation method before suspecting the system
-
- Code and features:
- 1. Build it (necessary but not sufficient)
- 2. Run it and exercise the actual feature path
- 3. Check the full chain: does data flow from input to output?
- 4. For integrations, test the full communication path end-to-end
+ # Prove it works
- Delegation: trust artifacts, not self-reports.
- When verifying delegated work, inspect the actual output artifact (git diff, file contents, runtime behavior), not the delegate's summary. Agents report what they intended, not always what happened.
+ Match verification to the claim and the risk. Complete required project checks and reuse existing tests before creating new infrastructure.
- ## Script the check when you can
+ - For prose or a mechanical edit, inspect the diff and relevant references.
+ - For code behavior, exercise affected cases with the closest meaningful tests.
+ - For UI and integration claims, inspect the corresponding runtime path when available.
+ - For performance, compare measured results under a representative workload.
+ - For delegated work, inspect artifacts and evidence, not only the summary.
- The strongest proof is a deterministic script that re-runs the same comparison, not a one-time eyeball. Write the script, run it, and keep its output as an artifact a reviewer can re-run instead of trusting your word. A script comparing the old and new compiled output catches what a glance misses.
+ Distinguish compilation, unit tests, mocks, and real infrastructure checks. Report missing coverage without inventing a pass. Use a reusable verification script when its benefit justifies the cost.
- Keep the artifact visible for the human. Commit it only for large or complex work where the trail has to be auditable later, like a big port or migration (the **show-me-your-work** skill). Most work just needs it visible, not committed.
+ Once checks pass, repeat or broaden them only after further changes, failures, or unresolved concerns. Verification does not authorize production access, external writes, or commits.