coilyco-gaming/galaxy-gen

Watch

docs: 41 docs to 20, 27 oversized docs, 4 skill files #88

New issue

Open

opened 2026-08-17 00:49:01 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-17 00:49:01 +00:00

Member

Part of coilysiren/inbox#374. The cap landed in coilyco-flight-deck/agentic-os#1108.

What this repo needs

Merge 41 docs down to 20. docs/ currently holds 41 files against the small-band cap of 20, totalling 3286 lines. The ceiling at the cap is 800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out.
27 docs over the per-file cap of 40 lines / 3,000 chars.
4 skill files over the cap, and this part is blocked. documentation-layout applies the band cap to SKILL.md and COMPOSED.md, while check-skills allows 500 lines / 10,000 bytes for the same file. See the blocker on coilysiren/inbox#374 and do not trim these until it is settled.
3 other Markdown files over the cap, outside docs/ and outside the skill roots.

What agentic-os learned migrating first

Merging costs lines rather than saving them, measured at 3.7 per fold: each adds a heading and its spacing. Budget a trimming pass rather than expecting consolidation to shrink the total.

Rephrasing prose to be tighter does not reduce line count, because reflowed text occupies the same rows. What works is deleting whole restatements, and folding a small trailing section into the paragraph above it, which drops a heading and a blank line without touching a word.

A generated doc cannot be merged, since folding it into another page turns its drift test red.

Acceptance

pre-commit run --all-files clean, with documentation-layout passing.
No live capability loses its reference material.

Part of coilysiren/inbox#374. The cap landed in coilyco-flight-deck/agentic-os#1108. ## What this repo needs 1. **Merge 41 docs down to 20.** `docs/` currently holds 41 files against the small-band cap of 20, totalling 3286 lines. The ceiling at the cap is 800 lines, so the arithmetic decides whether this is merging alone or merging plus trimming: it does not fit at any packing, so content has to come out. 2. **27 docs over the per-file cap** of 40 lines / 3,000 chars. 3. **4 skill files over the cap, and this part is blocked.** `documentation-layout` applies the band cap to `SKILL.md` and `COMPOSED.md`, while `check-skills` allows 500 lines / 10,000 bytes for the same file. See the blocker on coilysiren/inbox#374 and do not trim these until it is settled. 4. **3 other Markdown files over the cap**, outside `docs/` and outside the skill roots. ## What agentic-os learned migrating first **Merging costs lines rather than saving them**, measured at 3.7 per fold: each adds a heading and its spacing. Budget a trimming pass rather than expecting consolidation to shrink the total. **Rephrasing prose to be tighter does not reduce line count**, because reflowed text occupies the same rows. What works is deleting whole restatements, and folding a small trailing section into the paragraph above it, which drops a heading and a blank line without touching a word. **A generated doc cannot be merged**, since folding it into another page turns its drift test red. ## Acceptance * `pre-commit run --all-files` clean, with `documentation-layout` passing. * No live capability loses its reference material.

coilyco-ops commented

2026-08-17 01:12:00 +00:00

Author

Member

Two corrections and a decision, all after this was filed.

Nothing is urgent. This repo pins aos-precommit-v0.18.0, so the new caps do not apply here until that pin advances. aos-precommit-v0.24.0 carries them. The bump is the trigger, so the sequencing is migrate first then bump, or both in one change. Bumping first turns this repo's own commits red.

Skills are out of scope. documentation-layout was applying the band cap to SKILL.md and COMPOSED.md while check-skills allows 500 lines for the same file. Kai's call is to ignore skills, and the exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count above is struck from the work.

Epic: coilysiren/inbox#374.

Two corrections and a decision, all after this was filed. **Nothing is urgent.** This repo pins `aos-precommit-v0.18.0`, so the new caps do not apply here until that pin advances. `aos-precommit-v0.24.0` carries them. The bump is the trigger, so the sequencing is migrate first then bump, or both in one change. Bumping first turns this repo's own commits red. **Skills are out of scope.** `documentation-layout` was applying the band cap to `SKILL.md` and `COMPOSED.md` while `check-skills` allows 500 lines for the same file. Kai's call is to ignore skills, and the exemption is in coilyco-flight-deck/agentic-os#1110. Any skill-file count above is struck from the work. Epic: coilysiren/inbox#374.

coilyco-ops commented

2026-08-17 03:21:21 +00:00

Author

Member

Band landed on main, and it takes 38 of the 40 violations with it. Two remain, and one of them uncovered a sequencing problem worth naming.

The band

small here came from the chore(docs): declare the small documentation band sweep, not from a decision. Kai hand-assigned four bands and this repo was not among them, so per her call on coilysiren/inbox#374 I re-picked it. Large is right: 41 docs against a 20-doc cap meant deleting half of them, and the per-subsystem docs run to 80 lines against the large cap of 120. No doc was edited.

Remaining, and blocked on the pin

41 docs against the 40-doc cap. One merge. I tried it, folding metric-calibration.md into star-metrics.md, which is where it already pointed and the only file that linked it. It works and reads better. The currently-pinned hook rejects it: catalog-doc-size at this repo's pin caps a doc at 4,000 chars, and the merged file lands at 4,848.

That is the sequencing problem. The old cap forbids exactly the merge the new count cap requires. And it is not a matter of picking a better pair, because no two docs here sum under 4,000: the two smallest are 2,214 and 2,544. So the merge cannot land before the pin advances, and the epic's "migrate first, then bump" ordering is impossible for this repo. It has to be one change, or the bump first.

I reverted the merge rather than leave the repo red against its own pinned hook.
docs/perf-rewrite.md, 1,589 lines and 56,863 chars. Thirteen times the large cap, and a genuine outlier: it is a session journal of a performance rewrite, with a before/after table, a method section, and eight numbered levers, then a second journal of four more appended to it. Splitting it needs about fourteen files, which the 40-doc cap forbids outright.

It is not reference documentation, which is what a docs/ band is shaped for. My recommendation is to keep the TL;DR table, the method, and a one-line summary per lever as a ~100-line performance.md, and let the narrative stay in git history where the rewrite already lives. That is a content decision and a real deletion, so I have not made it.

Nothing is enforced here until the pin advances.

Band landed on `main`, and it takes 38 of the 40 violations with it. Two remain, and one of them uncovered a sequencing problem worth naming. ## The band `small` here came from the `chore(docs): declare the small documentation band` sweep, not from a decision. Kai hand-assigned four bands and this repo was not among them, so per her call on coilysiren/inbox#374 I re-picked it. Large is right: 41 docs against a 20-doc cap meant deleting half of them, and the per-subsystem docs run to 80 lines against the large cap of 120. No doc was edited. ## Remaining, and blocked on the pin 1. **41 docs against the 40-doc cap.** One merge. I tried it, folding `metric-calibration.md` into `star-metrics.md`, which is where it already pointed and the only file that linked it. It works and reads better. **The currently-pinned hook rejects it**: `catalog-doc-size` at this repo's pin caps a doc at 4,000 chars, and the merged file lands at 4,848. That is the sequencing problem. The old cap forbids exactly the merge the new count cap requires. And it is not a matter of picking a better pair, because no two docs here sum under 4,000: the two smallest are 2,214 and 2,544. So the merge cannot land before the pin advances, and the epic's "migrate first, then bump" ordering is impossible for this repo. It has to be one change, or the bump first. I reverted the merge rather than leave the repo red against its own pinned hook. 2. **`docs/perf-rewrite.md`, 1,589 lines and 56,863 chars.** Thirteen times the large cap, and a genuine outlier: it is a session journal of a performance rewrite, with a before/after table, a method section, and eight numbered levers, then a second journal of four more appended to it. Splitting it needs about fourteen files, which the 40-doc cap forbids outright. It is not reference documentation, which is what a `docs/` band is shaped for. My recommendation is to keep the TL;DR table, the method, and a one-line summary per lever as a ~100-line `performance.md`, and let the narrative stay in git history where the rewrite already lives. That is a content decision and a real deletion, so I have not made it. Nothing is enforced here until the pin advances.

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

coilyco-gaming/galaxy-gen#88

No description provided.

Rows
Columns