From b3a3230b8a5ba3c2024c1a2826896bb3a4b55122 Mon Sep 17 00:00:00 2001 From: Dennison Date: Tue, 8 Sep 2026 10:00:22 -0400 Subject: [PATCH] docs(process): CLAUDE.md requires worked tickets, real-run proof, delegation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Three practices this session kept proving necessary were missing, so each had to be re-established by instruction every time. Issues are tickets to work. The discipline required an issue before implementation but never said to then work it, and the predictable failure — stopping after filing to ask whether to proceed — happened twice. Also added: a wrong diagnosis must be corrected on the issue before implementing, and an issue whose cause was never confirmed must not be closed as if it were. Green tests are not proof. The file already said merging is not shipping; it said nothing about driving the real thing. Three green-and-wrong cases from this session are recorded as evidence: a spinner label that ate the cancel hint at 40 columns, colour detection that never coloured stdout because the check ran inside a command substitution, and a persistence change whose test suite wrote into the developer's real config. /efficient-fable is named as the default for token-heavy work, with the split written down and the reminder that subagent reports are leads to verify rather than facts to repeat. Docs-only: no rebuild required. Closes #1428 Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01WJGxhoFhA8JjkwZFcLGdS5 --- CLAUDE.md | 55 ++++++++++++++++++++++++++++++++++++ docs/logs/engineering-log.md | 35 +++++++++++++++++++++++ 2 files changed, 90 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index 95d1323e..7d73a7c5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -28,6 +28,20 @@ This repository is a Go coding harness with a streamed run API, a CLI smoke-test - **Merge at the end of a unit of work — do not leave branches sitting.** This repo's `main` moves fast (many concurrent squash-merged PRs) and subsystems get reimplemented in parallel, so a branch left unmerged drifts behind quickly and turns into a conflict-heavy, duplicated-work mess to reconcile. It gets messy if you don't. - When a unit of work is reviewable: open the PR, get CI green (re-run known-flaky checks rather than merging red), and squash-merge to `main` promptly. Then delete the branch. - Prefer small, scoped PRs that merge quickly over long-lived branches that accumulate multiple units of work. Always branch from the latest `origin/main`, not an older base. +- **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. Having filed one, implement + it, verify it, open the PR, get CI green, merge, and close it in the same + stretch of work. Stopping after filing to ask whether to proceed turns a + ticket into a question and leaves the work undone. The only exception is when + the user asked for the issue alone. +- If a problem is discovered mid-task and is genuinely separate, file it as its + own ticket, say so, and finish the task in hand — then work the new ticket + unless the user redirects. Discovering work is not a reason to stop doing + work. +- 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. ## Current Source Of Truth @@ -109,6 +123,27 @@ the SQLite conversation store persists the latest plan content per conversation. - Shell smoke: `bash scripts/run-bench-smoke.sh` (builds harnessd, uses `HARNESS_PROVIDER=fake`). - Full benchmark runbook (smokes, result schema, comparison harness, Python paths, honesty caveats): `docs/runbooks/benchmark-smoke.md`. +## Delegation + +- **Use `/efficient-fable` for token-heavy work.** Delegate the parts that + consume context without needing judgment: broad repo or docs searches, full + regression sweeps and log reduction, documentation drafting from a settled + design, and live browser or pty capture runs. Keep the decision layer — + architecture, diagnosis, resolving conflicting reports, the final diff review, + and what to tell the user — with the primary agent. +- Write a handoff packet as if the subagent has no context: repo path, exact + objective, files in and out of scope, the evidence format to return, the + commands to run and what success looks like, and stop conditions. Tell it to + stop and report rather than improvise when the code does not match the prompt. +- **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. Subagents have reported + confidently wrong results in this repo, including a build failure that was + pre-existing and unrelated, and a test failure caused by another session's + processes rather than the change under review. +- Run independent slices in parallel; keep coupled or delicate work local. Small + tasks stay direct — a subagent that costs more to brief than to do is waste. + ## Operational Reminder - Respond concisely but educationally: explain what changed and why it matters. @@ -116,6 +151,26 @@ the SQLite conversation store persists the latest plan content per conversation. symptom, cause, and fix in the relevant durable log or plan note. - Keep `docs/logs/long-term-thinking-log.md` in sync with any durable intent or success-criteria changes. - Keep `docs/runbooks/` aligned with the current CLI and server behavior. +- **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. + - What counts: launching the rebuilt binary and using the feature; driving the + TUI in a pty and reading the rendered frames; running the CLI end to end and + inspecting its output and exit code; checking the file or database the + change was supposed to write. `docs/runbooks/harnesscli-live-testing.md` and + `docs/runbooks/benchmark-smoke.md` describe how; the fake provider makes + most of it key-free. + - What does not count: a passing unit test, a successful build, or a + subagent's assurance that it worked. + - 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. + - This is not ceremony. Real cases from this repo: a spinner label that passed + every test and still ate the cancel hint at 40 columns; colour detection that + passed its tests while never colouring stdout, because the check ran inside + a command substitution; a persistence change that passed unit tests while + the suite quietly wrote into the developer's real config file. Each was + green and wrong, and each was caught only by looking at the real output. - **Rebuild the apps after changing them — merging is not shipping.** The installed binaries are build artifacts and a running process holds its code in memory, so a merged fix stays invisible until it is rebuilt and the app is diff --git a/docs/logs/engineering-log.md b/docs/logs/engineering-log.md index 479d09d1..7dba2d52 100644 --- a/docs/logs/engineering-log.md +++ b/docs/logs/engineering-log.md @@ -1,5 +1,40 @@ # Engineering Log +## 2026-09-08 — Issue #1428 CLAUDE.md: tickets, real-run proof, delegation + +- Three practices this session kept proving necessary were absent from + `CLAUDE.md`, so each had to be re-established by instruction every time. +- **Issues are tickets to work, not places to park problems.** The existing + discipline required an issue before implementation but never said the issue + must then be worked. The predictable failure, observed twice this session, is + stopping after filing to ask whether to proceed. Added: file, implement, + verify, merge, close, in the same stretch of work; discovering separate work + means filing it and finishing the task in hand, not stopping; and a diagnosis + that turns out wrong must be corrected on the issue before implementing, + never built against. +- **Green tests are not proof a change works.** `CLAUDE.md` already warned that + merging is not shipping and binaries must be rebuilt; it said nothing about + driving the real thing. Three green-and-wrong cases from this session are + recorded in the file as evidence rather than exhortation: + - #1415's truthful spinner label passed every test and still ate the cancel + hint at 40 columns. Found by rendering the line. + - #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. + - #1424's model memory passed unit tests while the suite wrote into the + developer's real `~/.config/harnesscli/config.json`. Found by reading the + file. + The requirement includes stating plainly what could *not* be exercised: an + honest gap is a result, a silent one is a false claim. +- **`/efficient-fable` is now named as the default for token-heavy work**, with + the split written down — searches, sweeps, log reduction, docs drafting and + live captures delegated; architecture, diagnosis, final diff review and what + to tell the user kept local. Also recorded: subagent reports are leads to + verify, not facts to repeat, with the two real cases from this session where a + confident subagent finding was wrong (a pre-existing unrelated build failure, + and a test failure caused by another session's processes). +- Docs-only change: no rebuild required. + ## 2026-09-08 — Issue #1426 --tui -model reaches the TUI - Symptom: `harnesscli --tui -model X` parsed the flag and threw it away. The