Docs single-sourcing: slug/id lists, the orphan set and the route-axis tables each have three owners #9

New issue

Open

opened 2026-09-19 20:26:55 +00:00 by gabogg · 0 comments

gabogg commented

2026-09-19 20:26:55 +00:00

Owner

PR #6 de-duplicated the frozen-route list successfully: ADR-0002
owns it, and CLAUDE.md rule 5 and docs/routes.md link to it instead of restating it. That is the
pattern to apply to the three sets below.

1. Brochure slugs and topic ids are stated three times

General + school slugs: CONTEXT.md:17-19, README.md:15, docs/routes.md:35-36 — and the four
school slugs a fourth time at docs/routes.md:13.
Topic ids: CONTEXT.md:25-26, README.md:16, docs/routes.md:37.

This was raised in round 1 of the PR #6 review and reported closed in rounds 3 and 4, but only the
frozen-route half of that finding was actually done. CONTEXT.md is the natural owner (it is the
domain glossary); README.md and docs/routes.md should link to it.

2. The orphan / carve-out set is stated three times

docs/routes.md:20, docs/routes.md:27-29 and docs/adr/0002-frozen-legacy-routes.md:37-41 each
state which routes are orphaned and therefore outside the freeze. ADR-0002 already owns the frozen
list; it is the natural owner of the inverse too.

3. The mode / style axes are stated twice inside one file

docs/routes.md:31-36 ("Parameter values") and docs/routes.md:56-61 ("Style / reading variants")
give the same two axes and the same value sets, and CONTEXT.md:34-40 is a third statement.

Also, while touching these files

README.md:3 says /general "is currently not linked from the home page", which implies something
else links it. Nothing does — docs/routes.md:12 says "not linked from any page (orphaned)" and the
build confirms zero inbound links. Match the README to that wording.

Acceptance

Each of the three facts above has exactly one owner file; every other mention is a link. The
README.md:3 wording matches docs/routes.md:12.

Relation to #2

The docs-drift CI check in #2 compares route counts against getStaticPaths. It would not catch
any of the above, since every copy is currently correct — these drift only after someone edits one
copy. Worth doing before that check gives a false sense of coverage.

Carried over from the PR #6 review (round 5). None of this blocks anything today — every affected statement is factually correct as written. The problem is that each fact has several owners, so the next correction has to find all of them, and the last two rounds of that PR each had to touch three files to fix one fact. PR #6 de-duplicated the frozen-route list successfully: [ADR-0002](../src/branch/master/docs/adr/0002-frozen-legacy-routes.md) owns it, and `CLAUDE.md` rule 5 and `docs/routes.md` link to it instead of restating it. That is the pattern to apply to the three sets below. ### 1. Brochure slugs and topic ids are stated three times - General + school slugs: `CONTEXT.md:17-19`, `README.md:15`, `docs/routes.md:35-36` — and the four school slugs a fourth time at `docs/routes.md:13`. - Topic ids: `CONTEXT.md:25-26`, `README.md:16`, `docs/routes.md:37`. This was raised in round 1 of the PR #6 review and reported closed in rounds 3 and 4, but only the frozen-route half of that finding was actually done. `CONTEXT.md` is the natural owner (it is the domain glossary); `README.md` and `docs/routes.md` should link to it. ### 2. The orphan / carve-out set is stated three times `docs/routes.md:20`, `docs/routes.md:27-29` and `docs/adr/0002-frozen-legacy-routes.md:37-41` each state which routes are orphaned and therefore outside the freeze. ADR-0002 already owns the frozen list; it is the natural owner of the inverse too. ### 3. The mode / style axes are stated twice inside one file `docs/routes.md:31-36` ("Parameter values") and `docs/routes.md:56-61` ("Style / reading variants") give the same two axes and the same value sets, and `CONTEXT.md:34-40` is a third statement. ### Also, while touching these files `README.md:3` says `/general` "is currently not linked from the home page", which implies something else links it. Nothing does — `docs/routes.md:12` says "not linked from any page (orphaned)" and the build confirms zero inbound links. Match the README to that wording. ### Acceptance Each of the three facts above has exactly one owner file; every other mention is a link. The `README.md:3` wording matches `docs/routes.md:12`. ### Relation to #2 The docs-drift CI check in #2 compares route *counts* against `getStaticPaths`. It would not catch any of the above, since every copy is currently correct — these drift only after someone edits one copy. Worth doing before that check gives a false sense of coverage.

gabogg added the

needs-triage

label

2026-09-19 20:26:55 +00:00

gabogg referenced this issue

2026-09-19 20:27:42 +00:00

docs: standardize repo docs and scaffold agentic-coding config #6