docs(process): CLAUDE.md requires worked tickets, real-run proof, and delegation

[dennisonbertram]

Closes #1428

Three practices this session kept proving necessary were absent from CLAUDE.md, so each had to be re-established by instruction every time.

1. An issue is a ticket to work, not a place to park a problem

The existing discipline requires an issue before implementation but never says the issue must then be worked. The predictable failure happened twice this session: file the issue, then stop and ask whether to proceed — which turns a ticket into a question and leaves the work undone.

Added, quoting the file:

An issue is a ticket to work, not a place to park a problem. Filing it is the first step of the job, not the deliverable.

If a diagnosis turns out to be wrong after the issue is filed, correct the issue before implementing. Never build a fix against a story the evidence has already contradicted, and never close an issue whose stated cause was never confirmed — say what remains unproven and leave it open.

That last clause is written from #1422, where I filed a confident diagnosis, disproved it twice by measuring, and had to correct the issue mid-flight.

2. Green tests are not proof the change works

CLAUDE.md already warned that merging is not shipping and that binaries must be rebuilt. It said nothing about driving the real thing — which is the same class of mistake one step earlier.

Green tests are not proof the change works — drive the real thing. A change is not done until the actual binary, TUI, or CLI has been exercised on the path the user takes, and the observed result reported. Report what you saw, not that you ran something.

State plainly what you could not exercise and what therefore rests on unit tests alone. An honest gap is a result; a silent one is a false claim.

It names what counts (rebuilt binary, pty capture, end-to-end CLI, inspecting the file the change writes) and what does not (a passing test, a successful build, a subagent's assurance), and points at the existing runbooks rather than duplicating them.

The section closes with three cases from this session, so it reads as evidence rather than exhortation — every one was green and wrong:

• feat(tui): spinner should say something true instead of rotating fifteen synonyms for thinking #1415's spinner label passed every test and still ate the cancel hint at 40 columns. Found by rendering the line.
• feat(tui): spinner should breathe — slower cycle with easing instead of a flat 120ms tick #1420's colour detection passed its tests while never colouring stdout, because style runs inside command substitution where -t 1 is false. Found by a pty capture.
• feat(tui): remember the last used model across restarts #1424's model memory passed unit tests while the suite wrote into my real ~/.config/harnesscli/config.json. Found by reading the file.

3. /efficient-fable as the default for token-heavy work

New short section naming what to delegate (searches, regression sweeps, log reduction, docs drafting, live captures) and what to keep (architecture, diagnosis, resolving conflicting reports, final diff review, what to tell the user), plus:

Treat subagent reports as leads, not facts. Before acting on a finding, opening a PR, or telling the user something is done, reopen the cited files and confirm the line references and failures yourself.

Also from this session: one subagent reported a build failure that was pre-existing and unrelated to the branch, and another reported test failures caused by my own concurrent processes rather than the change under review.

Verification

Docs-only. No rebuild required — stated explicitly per the repo's own rule about not silently skipping that.

All seven pre-existing sections confirmed intact by diff: Session rewind, Git & Merge Discipline, Current Source Of Truth, Workflow Engine, Provider Note, Benchmarks, Operational Reminder. The additions extend two existing sections and add one new one; nothing was removed or reworded.

Both referenced runbooks confirmed to exist: docs/runbooks/harnesscli-live-testing.md, docs/runbooks/benchmark-smoke.md.

Each addition was checked against "what would an agent do differently tomorrow because of this line?" — anything that could not be answered concretely was cut rather than softened.

Note

CLAUDE.md is not in the minor-change form's allowed paths (docs/**/*.md plus the root README/CONTRIBUTING/SECURITY/CHANGELOG/LICENSE), so this used the full form. Whether it should be included there is a reasonable question, deliberately left out of scope.

🤖 Generated with Claude Code

https://claude.ai/code/session_01WJGxhoFhA8JjkwZFcLGdS5

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.