From e8d1640dcb853fc71be4df7e3f149ec19f4b4fe0 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sat, 13 Jun 2026 00:40:25 -0500 Subject: docs(rules): manual-verification code steps go in org src blocks A checklist step that is code the user runs (verification setup, bug repro, walkthrough wiring) now goes in an org src block instead of a list bullet, so the user executes it in place with C-c C-c and reads the result in the buffer rather than copy-pasting. Manual actions, prose context, and Expected lines stay as bullets between the blocks. I scoped the Steps bullet in the same edit: it had said "one action per item" with the command as a bullet, which the new rule would contradict. It now names manual actions as the bullet case and points code steps at the src block. From the smoke handoff 2026-06-12, worked out on its manual-verification walkthroughs. --- claude-rules/verification.md | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) (limited to 'claude-rules') diff --git a/claude-rules/verification.md b/claude-rules/verification.md index 0b0fda4..1bbd8dd 100644 --- a/claude-rules/verification.md +++ b/claude-rules/verification.md @@ -60,18 +60,28 @@ Create (or append to) a single parent task named **"Manual testing and validatio - **Title** — descriptive, naming the behavior under test (not "test 1"). - **"What we're verifying:"** — one line on the intent, so a failed test explains itself. -- **Steps** — a bullet list, **one action per item**, in order. Concrete: the exact command to run, key to press, or file to open. +- **Steps** — **one action per item**, in order. Manual actions (a key to press, a phone step, a file to open, the `M-x` command under test) are list bullets, stated concretely. A step that *is* code the user will execute goes in an org src block, not a bullet — see below. - **"Expected:"** — the observable result after the last step. One outcome, stated plainly, so a mismatch is unambiguous. +**Executable steps go in src blocks.** When a step is code the user runs — verification setup, bug-reproduction steps, walkthrough wiring — put it in an org src block so the user can execute it in place (`C-c C-c`) and read the result in the buffer, rather than copy-pasting a bullet: + +- Use the correct language tag (`emacs-lisp`, `sh`, `python`, …). +- Let results land in the buffer: `emacs-lisp` default-value results are fine; shell blocks get `:results output`. +- Group statements into logical blocks (setup, action, restore) so each block is one `C-c C-c`. +- Prose context, manual actions (phone steps, key presses, the UI actions under test), and `Expected:` lines stay as list items between the blocks. + Format: ``` ** TODO Manual testing and validation *** What we're verifying: . -- -- -- +- +#+begin_src emacs-lisp +(setup-form) +(action-form) +#+end_src +- Expected: . ``` -- cgit v1.2.3