From 0afe48df3d4fa49da889fbeaeaa38e8f971e030a Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Fri, 22 May 2026 15:13:05 -0500 Subject: docs(rules): add an unable-to-verify reporting standard verification.md required running tests/lint/typecheck/build before claiming done, but said nothing about what to do when a command can't run. A new "When You Cannot Verify" section requires a four-part report (command attempted, why it couldn't run, risk left unverified, and the smallest next command for the user) and states the principle that a check that didn't run is never reported as a pass. --- claude-rules/verification.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) (limited to 'claude-rules') diff --git a/claude-rules/verification.md b/claude-rules/verification.md index 8993736..673a54d 100644 --- a/claude-rules/verification.md +++ b/claude-rules/verification.md @@ -31,6 +31,19 @@ If you find yourself using these words, you haven't verified: Replace beliefs with evidence. Run the command. +## When You Cannot Verify + +Sometimes the verification command cannot run: the tool is absent, there is no network, a sandbox blocks it, or the environment is missing a dependency. A check that did not run must never be reported as a pass. "Unable to verify" is an honest, required outcome — not silence, and not an optimistic "should work." + +When a check cannot run, report it in this order: + +1. **Command attempted** — the exact command you tried to run. +2. **Why it could not run** — tool absent, no network, sandbox limit, missing environment, etc. +3. **Risk left unverified** — what might be broken that you would not know about, given the check did not run. +4. **Next command to close the gap** — the smallest command the user can run to verify themselves. + +Do not let an unverifiable check vanish into a confident summary. State it plainly and hand the gap to the user. + ## Before Committing Before any commit: -- cgit v1.2.3