docs: regenerate WALKTHROUGH.md as plain markdown, and declare prettier - #81
Merged
Merged
Conversation
The `code-walkthrough` skill no longer builds this file with showboat, so WALKTHROUGH.md is ordinary markdown. Regenerating it surfaced a formatting gap this repo had been living with invisibly, which is why both changes land together. **The document.** 1429 -> 1096 lines, 94 fenced blocks -> 41. The old form paired every snippet with a captured `output` block, so 39 of its 47 commands were `sed` ranges whose only assertion was that text still matched a file; captured output ran 1.8x the prose. Snippets are now quoted inline and labelled `file` -- `symbol` rather than by line range. Dropping showboat also removed constraints that had been shaping content rather than formatting. "What the tests cover" shows real `bun test` output instead of a `grep` of test names, which was a workaround for verify breaking on non-deterministic output. The architecture table is a table instead of a shell loop, which was a workaround for verify breaking on repo-tracking output. Fidelity is checked rather than assumed: each labelled `ts` block was diffed against the source file it names, 271 substantive lines, 0 mismatches. **Prettier.** That check initially failed. The user-level auto-format hook runs prettier on any markdown it sees, and this repo declared no prettier config, so it used defaults -- including `embeddedLanguageFormatting: "auto"`, which rewrote quoted TypeScript to double quotes at width 80 against this repo's Biome style of single quotes at 100. Three snippets stopped matching their source. Biome 2.5 does not process markdown at all, so prettier is not a redundant second formatter here; it is the only one that can do this job. It is now a declared devDependency wired into `check`, `check:ci` and `format`, scoped to `**/*.md` so it never fights Biome over TypeScript or JSON. Markdown drift now fails the pre-push hook like any other formatting -- verified by pushing bad whitespace through the gate and watching it block. `.prettierrc.json` sets `embeddedLanguageFormatting: "off"`, which is load-bearing rather than stylistic. `.prettierignore` excludes `.issues/`: it is ignored through the global core.excludesfile rather than this repo's .gitignore, so git hides it and prettier does not. THEORY.md changes are prettier normalizing `*emphasis*` to `_emphasis_`, nothing else. CLAUDE.md gains a Formatting section recording the split. Co-Authored-By: Claude
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
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.
Two coupled changes: regenerating the walkthrough without showboat is what exposed the formatting gap, so they land together.
The document
code-walkthroughno longer builds this file with showboat, so it is ordinary markdown now.The old form paired every snippet with a captured
outputblock, and 39 of its 47 commands weresedranges whose only assertion was that some text still matched a file. Snippets are now quoted inline and labelled`file` — `symbol`rather than by line range.Dropping showboat also removed constraints that were shaping content, not just formatting:
bun testoutput instead of agrepof test names — that was a workaround for verify breaking on non-deterministic output.Since nothing checks this document any more, fidelity was verified rather than assumed: every labelled
tsblock was diffed against the source file it names — 271 substantive lines, 0 mismatches.Prettier
That check initially failed, which is why this PR also adds prettier.
The user-level auto-format hook runs prettier on any markdown it sees. This repo declared no prettier config, so prettier used its defaults — including
embeddedLanguageFormatting: "auto", which rewrote quoted TypeScript into double quotes at width 80, against this repo's Biome style of single quotes at width 100. Three snippets stopped matching their source.Biome 2.5 does not process markdown at all (
Checked 0 files), so this is not a redundant second formatter — it is the only tool that can do this job. Prettier is now a declared devDependency wired intocheck,check:ciandformat, scoped to**/*.mdso it never fights Biome over TypeScript or JSON..prettierrc.json—proseWrap: preserve,embeddedLanguageFormatting: off. The second is load-bearing, not stylistic..prettierignore— excludes.issues/, which is ignored through the globalcore.excludesfilerather than this repo's.gitignore, so git hides it and prettier does not. Without this,check:cifails on agent working notes that never ship.Markdown drift now fails the pre-push hook like any other formatting. Verified by appending bad whitespace to
README.mdand confirmingcheck:ciblocked, then restoring it.The same gap exists across the workspace and is now tracked: 14 repos with no prettier at all, and 7 that run it with no config.
Noise in the diff
THEORY.md's 50 changed lines are prettier normalizing*emphasis*to_emphasis_— nothing else.CLAUDE.mdgains a Formatting section recording the split and why the config settings matter.Checks
bun run check:cigreen — Biome clean, prettier clean,tsc --noEmitclean, 82 tests pass. No source changes.