diff options
Diffstat (limited to 'claude-rules/verification.md')
| -rw-r--r-- | claude-rules/verification.md | 16 |
1 files changed, 15 insertions, 1 deletions
diff --git a/claude-rules/verification.md b/claude-rules/verification.md index 1bbd8dd..2c2088e 100644 --- a/claude-rules/verification.md +++ b/claude-rules/verification.md @@ -13,6 +13,18 @@ This applies to every completion claim: - "Bug is fixed" → Run the reproduction steps. Confirm the bug is gone. - "No regressions" → Run the full test suite, not just the tests you added. +## Green Baseline Before Starting Work + +Run the test suite before you start work, not only before you finish. A clean run at the start confirms the tree is in the known-good state you assume it is, so the baseline you build on and measure your changes against is actually green. + +If the suite is red before you touch anything, fix or explicitly triage the failure first. A pre-existing failure left in place poisons every later "did I break this?" check: you can't separate your own regressions from the noise, and the end-of-work run stops being readable as pass/fail at a glance. Work that assumes a known-good base may also be built on a broken assumption you never saw. + +When a pre-existing failure genuinely can't be fixed before the work begins (out of scope, or it needs a decision), record it as a tracked task with the diagnosis and carry its name forward. The green bar for the rest of the work is then explicitly "only this known failure remains," not a silent tolerance for red. + +Two cases are not failures of this rule. A project with no suite has nothing to baseline — note that and proceed. A suite that can't run (no network, a missing dependency, a sandbox limit) is the "When You Cannot Verify" case below, not a work-blocker — record what you couldn't run and proceed with the risk named. + +This is the start-of-work counterpart to the Before Committing gate below: one confirms the ground is solid before you build, the other confirms you didn't crack it. + ## What Fresh Means - Run the verification command **now**, in the current session @@ -56,6 +68,8 @@ Do not let an unverifiable check vanish into a confident summary. State it plain Some checks can only be run by the user: interactive UI a script can't drive, a live external service, visual rendering (colors, layout, faces), a real device, or anything where the verification *is* a human looking at the result. When the gap needs the user's hands or eyes — not just a command they could paste — don't bury the steps in prose. Write them as a structured, runnable checklist in the project's task file. +When *you* need a window on the user's live desktop to verify something visually — render a panel, grab a screenshot — keep it off the workspace they're actively using. Capture on an off-screen output and tear it down; when showing the user something, open it on a separate workspace and name it. See `desktop-capture.md` for the rule and the Hyprland recipe. + Create (or append to) a single parent task named **"Manual testing and validation"** in the project's todo file (`todo.org`, or the project's equivalent). Under it, write **one org sub-header per test**: - **Title** — descriptive, naming the behavior under test (not "test 1"). @@ -92,7 +106,7 @@ Use this whenever the verification gap from "When You Cannot Verify" above is a ## Before Committing Before any commit: -1. Run the test suite — confirm all tests pass +1. Run the full test suite as its own command, read the result, and commit only when failures are zero — never bundle the run with the commit (e.g. `make test; git commit`), where a red suite can't stop the commit. Run the whole suite, not just the touched file: a change can break a test elsewhere. If the suite can't run, that's "unable to verify" (see When You Cannot Verify above) — surface it, don't commit silently. 2. Run the linter — confirm no new warnings 3. Run the type checker — confirm no new errors 4. Review the diff — confirm only intended changes are staged |