fiddlerwoaroof/improvise
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(context): condense repo-map to a digest; move gotchas and inventory to their own pages

Browse Source 
repo-map.md was 173 KB (~43k tokens), too long to be part of every new
agent's context. The full gotcha text moves verbatim to context/gotchas.md
and the per-file inventory (with the old Wasm/CLI/Testing sections) to
context/file-inventory.md; the map keeps a one-or-two-line digest per
gotcha under the same numbers, so every `gotcha N` citation still resolves.

The doc-site manifest publishes the two new pages, and `gotchas` gets the
same gotcha-N anchors as `repo-map`.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Edward Langley
2026-10-09 21:13:55 -07:00
parent b0ae354f53
commit f0119a437d
5 changed files with 671 additions and 531 deletions
Download Patch File Download Diff File Expand all files Collapse all files
context/code/doc-site.md
+8 -6
View File
@@ -43,7 +43,7 @@ Not published:
will meet, and nobody visiting a website is about to read a PR thread.
None of the three is referenced by any published document except as a row in
`repo-map.md`'s file inventory, which is inside a code fence, so leaving them
the file inventory (`file-inventory.md`), which is inside a code fence, so leaving them
out creates no dangling link. That was checked rather than assumed.
**And "not published" is now derived rather than assumed** (improvise-res9).
@@ -233,11 +233,13 @@ recorded as a decision rather than left to be rediscovered as a bug.
## 6. Navigation
`repo-map.md` is one long document whose gotcha list is numbered 1 to 48, and
splitting it per gotcha was rejected: the gotchas cross-reference each other
constantly ("see gotcha 35", "for the reason gotcha 39 watches…"), and a reader
following those wants a scroll, not 48 page loads. It stays one page, with an
id on every list item and a compact strip of numbered links under the heading.
`repo-map.md` carries a digest of the numbered gotchas and `gotchas.md` the long
form; the map was condensed because it was too long to put in every new agent's
context. Splitting per gotcha was rejected: the gotchas cross-reference each
other constantly ("see gotcha 35", "for the reason gotcha 39 watches…"), and a
reader following those wants a scroll, not one page load per number. Each of the
two stays one page, with an id on every list item and a compact strip of
numbered links under the heading.
The ids come from the list item's **own number**, not from a counter, so an
inserted gotcha renumbers the anchors exactly as it renumbers the prose that
cites them.