docs: 28 docs to 20, 19 oversized docs #92

New issue

Closed

opened 2026-08-17 00:48:59 +00:00 by coilyco-ops · 2 comments

coilyco-ops commented

2026-08-17 00:48:59 +00:00

Member

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

What this repo needs

Merge 28 docs down to 20. docs/ currently holds 28 files against the small-band cap of 20, totalling 1450 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.
19 docs over the per-file cap of 40 lines / 3,000 chars.

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 28 docs down to 20.** `docs/` currently holds 28 files against the small-band cap of 20, totalling 1450 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. **19 docs over the per-file cap** of 40 lines / 3,000 chars. ## 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:11:55 +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:17:54 +00:00

Author

Member

Done and landed on main. pre-commit run --all-files is clean, and the layout check passes with no doc edited.

The whole thing was a band. This repo carries 28 docs, which already exceeds the small band's 20-doc cap, so "migrate to small" was never reachable without deleting eight of them. The longest doc is 80 lines against the large cap of 120, and the tree totals 1,450 lines. At large every file and the count both pass as they stand.

The small here came from a sweep commit, chore(docs): declare the small documentation band, that stamped the same value on every repo that had not declared one during the agentic-os#1108 rollout. That is the default the band rule was written to prevent, in its own words: "there is no default to fall into: an undeclared repo and a deliberately small one would otherwise be the same file." Kai hand-assigned four bands (ward large, umbra small, scoop-bucket small, website small) and this repo was not among them.

Kai's call on coilysiren/inbox#374 was to re-pick per repo and report each one, so this is that report. Nothing is enforced here until the pin advances.

Done and landed on `main`. `pre-commit run --all-files` is clean, and the layout check passes with **no doc edited**. The whole thing was a band. This repo carries 28 docs, which already exceeds the small band's 20-doc cap, so "migrate to small" was never reachable without deleting eight of them. The longest doc is 80 lines against the large cap of 120, and the tree totals 1,450 lines. At large every file and the count both pass as they stand. The `small` here came from a sweep commit, `chore(docs): declare the small documentation band`, that stamped the same value on every repo that had not declared one during the agentic-os#1108 rollout. That is the default the band rule was written to prevent, in its own words: "there is no default to fall into: an undeclared repo and a deliberately small one would otherwise be the same file." Kai hand-assigned four bands (ward large, umbra small, scoop-bucket small, website small) and this repo was not among them. Kai's call on coilysiren/inbox#374 was to re-pick per repo and report each one, so this is that report. Nothing is enforced here until the pin advances.

coilyco-ops closed this issue

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