docs: stop offering a console deleted at #541, and pin the rule - #766
Merged
Conversation
`keel tui` went at #541 with ~10k lines of curses. The docs kept sending operators to it, in the present tense, for months. FIVE STALE CLAIMS, ONE OF THEM DOUBLY FALSE README.md "the browser view and the TUI answer" -- listed as a current way to read keel. docs/glossary.md "the TUI's Help menu renders this file directly". Wrong twice: the menu went at #541 and `render_glossary` went at #540. The file's whole claim to authority was that something rendered it, and nothing had for two releases. Replaced with what is true -- since #539 a term becomes an OUTBOUND link to the published copy, built from `TERMS` in `web/static/js/docs.js`, so a term added here is not linked until it is added there too. docs/mcp-server.md two present-tense references. operator-runbook.md:215 pointed at "the Account menu's `update` entry in the TUI console (see 'The TUI console' for the ceremony)" -- a menu that does not exist, cross-referencing a section that does not exist. `keel update` has ONE front-end now; it had two until #541, and the browser's "newer build is ready" button reloads the service worker rather than replacing the binary. None of it was catchable. Every statement was prose, and prose has no compiler. THE RULE PERMITS THE HISTORY A retired surface may be NAMED, provided the paragraph naming it cites the issue that retired it. Mention it, date it. A repo that scrubbed its own deletions would be worse off than one carrying a stale line: `keel update` really did have two front-ends, and the runbook explaining why it now has one is doing its job. PER PARAGRAPH, NOT PER LINE, AND THAT MATTERS The first cut required the LINE naming the surface to cite the issue, and failed on a sentence whose wrap put "`keel tui`, a command that no longer exists" two lines below its own "Until #541". Prose wraps at 100 characters here, so a line boundary carries no meaning and a rule keyed to one is a rule about the reflow -- the same trap that broke a runbook block locator earlier in this series when its introducing sentence was reworded. A paragraph is the unit a reader takes the claim from. The scan also asserts its own glob still matches the four documents it names; a glob that matched nothing would pass over any wording at all. 6,426 passed / 3 skipped, ruff clean. Two mutants killed: the README offering the TUI again, and the doc glob going blind. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01KZZxmspQXe5qJ9FAsG13s6
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
keel tuiwent at #541 with ~10k lines of curses. The docs kept sending operators to it, in the present tense, for months. Five stale claims, and one of them was doubly false.README.mddocs/glossary.mddocs/mcp-server.mddocs/operator-runbook.md:215updateentry in the TUI console (see 'The TUI console' for the ceremony)"The glossary was wrong twice over. The Help menu went at #541 and
render_glossarywent at #540 — so the file's entire claim to authority ("defined HERE and nowhere else, because something renders it") had been hollow for two releases. It now says what's true: since #539 a term becomes an outbound link to the published copy, built fromTERMSinweb/static/js/docs.js— so a term added here isn't linked until it's added there too.The runbook line was worse than stale: it cross-referenced a section "The TUI console" that doesn't exist, telling an operator to use a menu that doesn't exist.
keel updatehas one front-end now; it had two until #541. (The browser's "A newer build is ready" button reloads the service worker — it does not replace the binary.)None of this was catchable. Every statement was prose, and prose has no compiler.
The rule permits the history
A retired surface may be named, provided the paragraph naming it cites the issue that retired it. Mention it, date it.
A repo that scrubbed its own deletions would be worse off than one carrying a stale line —
keel updatereally did have two front-ends, and the runbook explaining why it now has one is doing its job. So all six remaining mentions stay; each is now dated.Per paragraph, not per line
The first cut required the line naming the surface to cite the issue, and failed on a sentence whose wrap put
`keel tui`, a command that no longer existstwo lines below its own "Until #541".Prose wraps at 100 characters here, so a line boundary carries no meaning and a rule keyed to one is a rule about the reflow — the same trap that broke a runbook block locator earlier in this series when its introducing sentence was reworded. A paragraph is the unit a reader takes the claim from.
The scan also asserts its own glob still matches the four documents it names; a glob matching nothing would pass over any wording at all.
Checks
6,426 passed / 3 skipped, ruff clean. Two mutants killed: the README offering the TUI again, and the doc glob going blind.
🤖 Generated with Claude Code
https://claude.ai/code/session_01KZZxmspQXe5qJ9FAsG13s6