CLAUDE.md is too long #7

New issue

Closed

opened 2026-08-01 17:55:59 +00:00 by art · 2 comments

art commented

2026-08-01 17:55:59 +00:00

Owner

It's read in on every session and eats tokens we could better spend on something else. Clean up and compact as much as possible.

For example the Iceland geopackages can be inferred from the iceland configuration, no need to list them there. In fact, group country specific knowledge into per-country files under docs/ that are read when needed.

Historic projects (like the unification) that are done belong to either the commit log or per-project files under docs/ . This is the big one and I guess it also deserves another sweep to see if any other documentation needs updating with relation to the unification project.

Most TODO items probably belong as separate issues in Forgejo.

It's read in on every session and eats tokens we could better spend on something else. Clean up and compact as much as possible. For example the Iceland geopackages can be inferred from the iceland configuration, no need to list them there. In fact, group country specific knowledge into per-country files under docs/ that are read when needed. Historic projects (like the unification) that are done belong to either the commit log or per-project files under docs/ . This is the big one and I guess it also deserves another sweep to see if any other documentation needs updating with relation to the unification project. Most TODO items probably belong as separate issues in Forgejo.

art-bot was assigned by art

2026-08-01 18:08:02 +00:00

art-bot commented

2026-08-01 19:15:32 +00:00

Collaborator

Done on branch night/issue-7-compact-claude-md (commit 2145cc9, not pushed).

CLAUDE.md: 2118 lines / 149 kB → 649 / 42 kB (−72%). Nothing was deleted for being uninteresting; it moved to where you look it up on demand. The file now states the rule about itself: durable architecture stays, finished work goes to the commit log or docs/, things still to do go to the issue tracker.

Per-country docs, which is where most of the removed text went — docs/country-iceland.md, -sweden.md, -poland.md. Sources, credentialed providers, class mappings and quirks per country. A side effect worth having: the cross-country comparisons are legible for the first time, e.g. Sweden's deliberately ELSE-less landcover CASE against Poland's deliberately total ones, which is a real design decision that was previously spread across four sections.

I did not move the per-class reasoning out of the configs — it is already next to the query it justifies, which is the right review surface, and the country docs point at it rather than copying it.

docs/unification-plan.md → docs/unification.md, since it documents a finished project rather than a plan. The six phase writeups folded into the phase sections that already summarised them, minus the country-specific mapping detail. That duplication is most of why the merge shrank rather than grew.

docs/performance.md takes the tile-serving investigation and the landcover absorption record.

docs/geo-primer.md gained a "Maintaining this document" footer listing what rots in it — which is what CLAUDE.md's "Onboarding doc" section was actually for.

15 issues filed: #9–#23. All unassigned, deliberately: the night shift treats assignment as your ready/draft signal, so assign the ones you actually want worked. #4 and #5 already covered two items. Where the old list had grouped items I split them (railways thinning #9 and roads z5–z6 #10 are separate work) and where it had scattered them I merged (the three Iceland buildings items are one pass, #23). Two are the standing workstreams: #16 catalogue, #17 add a neighbour.

Also swept for post-unification staleness, since you asked: README described the three maps as parallel stacks with unification "planned"; the geo-primer said Sweden and Poland still used plain text landcover classes and pointed at the TODO list twice.

One factual fix while rewriting: the style is 50 map-sourced layers + 10 Iceland-only + the sourceless background, not "51 + 10" as both CLAUDE.md and the old text claimed.

Verified: make build, mapsrv go test, zero broken relative links across all markdown, and the one-water-colour invariant still greps to exactly 4.

Two things I left alone and you may disagree with. The docs/unification.md "Where we are" snapshot and the pre-phase plan text are still there in full — it is a finished project's record and the argument is why the code looks the way it does, but if you want it shorter the plan-as-written blocks are the obvious cut. And SPEC.md is untouched; it is the original Iceland-only spec and predates the reframing, so it may want the same treatment.

Done on branch `night/issue-7-compact-claude-md` (commit 2145cc9, not pushed). **CLAUDE.md: 2118 lines / 149 kB → 649 / 42 kB (−72%).** Nothing was deleted for being uninteresting; it moved to where you look it up on demand. The file now states the rule about itself: durable architecture stays, finished work goes to the commit log or `docs/`, things still to do go to the issue tracker. **Per-country docs**, which is where most of the removed text went — `docs/country-iceland.md`, `-sweden.md`, `-poland.md`. Sources, credentialed providers, class mappings and quirks per country. A side effect worth having: the cross-country comparisons are legible for the first time, e.g. Sweden's deliberately `ELSE`-less landcover `CASE` against Poland's deliberately total ones, which is a real design decision that was previously spread across four sections. I did **not** move the per-class reasoning out of the configs — it is already next to the query it justifies, which is the right review surface, and the country docs point at it rather than copying it. **`docs/unification-plan.md` → `docs/unification.md`**, since it documents a finished project rather than a plan. The six phase writeups folded into the phase sections that already summarised them, minus the country-specific mapping detail. That duplication is most of why the merge shrank rather than grew. **`docs/performance.md`** takes the tile-serving investigation and the landcover absorption record. **`docs/geo-primer.md`** gained a "Maintaining this document" footer listing what rots in it — which is what CLAUDE.md's "Onboarding doc" section was actually for. **15 issues filed: #9–#23.** All **unassigned**, deliberately: the night shift treats assignment as your ready/draft signal, so assign the ones you actually want worked. #4 and #5 already covered two items. Where the old list had grouped items I split them (`railways` thinning #9 and `roads` z5–z6 #10 are separate work) and where it had scattered them I merged (the three Iceland buildings items are one pass, #23). Two are the standing workstreams: #16 catalogue, #17 add a neighbour. **Also swept for post-unification staleness**, since you asked: README described the three maps as parallel stacks with unification "planned"; the geo-primer said Sweden and Poland still used plain `text` landcover classes and pointed at the TODO list twice. **One factual fix while rewriting:** the style is 50 map-sourced layers + 10 Iceland-only + the sourceless `background`, not "51 + 10" as both CLAUDE.md and the old text claimed. Verified: `make build`, `mapsrv go test`, zero broken relative links across all markdown, and the one-water-colour invariant still greps to exactly 4. **Two things I left alone and you may disagree with.** The `docs/unification.md` "Where we are" snapshot and the pre-phase plan text are still there in full — it is a finished project's record and the argument is why the code looks the way it does, but if you want it shorter the plan-as-written blocks are the obvious cut. And `SPEC.md` is untouched; it is the original Iceland-only spec and predates the reframing, so it may want the same treatment.

art-bot referenced this issue from a commit

2026-08-01 20:14:53 +00:00

docs: compact CLAUDE.md, split knowledge into docs/, move TODOs to Forgejo

art-bot closed this issue

2026-08-01 20:14:53 +00:00

art-bot commented

2026-08-01 20:15:05 +00:00

Collaborator

Merged to main and pushed (fast-forward, 15c3429..77d3c9d).

Two commits: 2145cc9 the restructure, 77d3c9d retiring SPEC.md — which turned out to be documenting one real gap, not just history: filter_only is a generalization strategy used by ten layers across four configs including two shared contracts, and only SPEC.md said what it does.

Note the push also published two commits that were already sitting unpushed on main — 91df17a (night shift) and f596d9f (-regeneralize + absorption) — since they were ancestors.

Follow-up work is #9–#23, all unassigned so they stay drafts until you pick them.

Merged to `main` and pushed (fast-forward, `15c3429..77d3c9d`). Two commits: `2145cc9` the restructure, `77d3c9d` retiring `SPEC.md` — which turned out to be documenting one real gap, not just history: `filter_only` is a generalization strategy used by ten layers across four configs including two shared contracts, and only SPEC.md said what it does. Note the push also published two commits that were already sitting unpushed on `main` — `91df17a` (night shift) and `f596d9f` (`-regeneralize` + absorption) — since they were ancestors. Follow-up work is #9–#23, all unassigned so they stay drafts until you pick them.