From 84081b2bd874807ecc8f34bed7176650f065edb5 Mon Sep 17 00:00:00 2001 From: Dai Ha Date: Sun, 9 Aug 2026 19:38:34 +0200 Subject: [PATCH] CB-526: make a shipped capability undocumentable-by-accident MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CLAUDE.md already carries a mandatory before-done checklist ("the prompt is part of the product"). It covered the instruction surface but not the operator-facing one, and the result was measurable: CB-506 through CB-525 shipped without a single wiki mention, while the Roadmap went on claiming Stage 5 was finished. Discipline is what already failed, so this rides the existing gate rather than adding a new habit to remember: one more row, firing when a change touches anything an operator can use, configure, or observe. The row names where the other two kinds of change go too (contracts to Implementation, coverage to the Roadmap), so "nothing to document" is a decision the table makes rather than a default you fall into. Addendum-only — the canonical block is untouched and still byte-identical to the wiki template (verified). --- CLAUDE.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CLAUDE.md b/CLAUDE.md index bc9bfa7..2b10caf 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -168,6 +168,15 @@ Before you call any work done, check the row that matches what you touched: | worktree provisioning or the parity overlay | the "both roles read this file" premise — it rests on the worker's worktree being a checkout of this repo | | `.claude/skills/**` | the addendum's skill list, and the "name the playbook" rule | | a new peer kind (non-Claude adapter) | what that peer can read — anything it must obey belongs in its charter, not in the block | +| **anything an operator can use, configure, or observe** — an MCP tool, a `bridged.yaml` knob, an endpoint, a visible behaviour | **[Features](wiki/11-Features.md)** — one entry: what it does · the knob that turns it on · **why it exists** · the gotcha | + +That last row is not bookkeeping. Chapters 1–10 answer *how is this built* and *why this way*; +none of them has a home for *what can it do and how do I turn it on*, so for twenty tickets a +shipped capability landed nowhere and the Roadmap went on claiming the stage was finished. The +*why* line is the one that matters — without it a decision gets re-litigated from scratch a month +later. Internal contract changes go to `wiki/9-Implementation.md` instead; test and coverage work +is a Roadmap line. A change that touches none of the three earns no entry, and that is a normal +outcome rather than an omission. Then **propagate**: the block in this file and the template in the wiki ([Use Cases](https://git.ltms.dev/lms/claude-bridge/wiki/7-Use-Cases) → *The portable `CLAUDE.md`