coilyco-gaming/sirens-echo

Watch

docs/ is full at its maximum band, so features are being written into whichever page has room and main pays for it #1111

New issue

Open

opened 2026-08-22 22:31:15 +00:00 by coilyco-ops · 1 comment

coilyco-ops commented

2026-08-22 22:31:15 +00:00

Member

Filed by Darren (director seat), 2026-08-22. Raised by the engineer in the last paragraph of #1109, which ended "it wants its own issue if anyone agrees it is due." I agree it is due, and a paragraph inside a closed incident is not a tracker.

The condition

docs/ is at its 40-page ceiling for the large band, which is the maximum band, and most pages sit within a few hundred characters of the 8000-character page cap.

The consequence is not theoretical and it is not about tidiness:

Four issues in milestone 17 needed a documentation page and none could have one. Each was merged into a crowded neighbour instead, and paid for by trimming existing prose to make room.
Two separate main breakages in four days came out of that pressure. #1081 cut docs/sirens-echo-turn-stages.md back under the cap after #1077 and #1079 both landed content in it. #1109 and #1110 did the same for docs/sirens-echo-admission.md after #1104 and #1106, at 8574 against 8000.

So the caps are now shaping what gets written, where it gets written, and how often main goes red. That is a documentation-architecture problem wearing a CI failure as a symptom.

What is deliberately not being proposed

Not raising the caps. The bands are deliberate, large is already the maximum, and the caps exist because an unbounded page is one nobody reads. The intended remedy for a repository that outgrows its band is to merge two related pages and free a slot, which is what the hook's own message advises.

What this asks for

An editorial pass rather than a feature change:

Find the merge candidates. Which pairs of pages are one subject split across two files, and which single page is really two subjects that would each be under the cap alone.
Merge enough to free real headroom, not exactly one slot, since the next four features already want pages.
Say in the docs layout guidance what a contributor should do when their change needs a page and none is free, so the answer is not rediscovered by each agent under deadline.

Why it is a design call rather than an engineering one

Deciding which pages are one subject is an editorial judgement about a reader, and doing it as a side effect of shipping a feature is how both breakages happened. It should be nobody's second task inside a change about something else.

#1109 - the second breakage and where this was raised
#1081 - the first one, on a different page, same shape
#1110 - the trim that unblocks main right now

**Filed by Darren (director seat), 2026-08-22.** Raised by the engineer in the last paragraph of #1109, which ended "it wants its own issue if anyone agrees it is due." I agree it is due, and a paragraph inside a closed incident is not a tracker. ## The condition `docs/` is at its **40-page ceiling for the `large` band**, which is the maximum band, and most pages sit within a few hundred characters of the 8000-character page cap. The consequence is not theoretical and it is not about tidiness: * **Four issues in milestone 17 needed a documentation page and none could have one.** Each was merged into a crowded neighbour instead, and paid for by trimming existing prose to make room. * **Two separate `main` breakages in four days came out of that pressure.** #1081 cut `docs/sirens-echo-turn-stages.md` back under the cap after #1077 and #1079 both landed content in it. #1109 and #1110 did the same for `docs/sirens-echo-admission.md` after #1104 and #1106, at 8574 against 8000. So the caps are now shaping what gets written, where it gets written, and how often `main` goes red. That is a documentation-architecture problem wearing a CI failure as a symptom. ## What is deliberately not being proposed **Not raising the caps.** The bands are deliberate, `large` is already the maximum, and the caps exist because an unbounded page is one nobody reads. The intended remedy for a repository that outgrows its band is to **merge two related pages and free a slot**, which is what the hook's own message advises. ## What this asks for An editorial pass rather than a feature change: 1. **Find the merge candidates.** Which pairs of pages are one subject split across two files, and which single page is really two subjects that would each be under the cap alone. 2. **Merge enough to free real headroom**, not exactly one slot, since the next four features already want pages. 3. **Say in the docs layout guidance what a contributor should do** when their change needs a page and none is free, so the answer is not rediscovered by each agent under deadline. ## Why it is a design call rather than an engineering one Deciding which pages are one subject is an editorial judgement about a reader, and doing it as a side effect of shipping a feature is how both breakages happened. It should be nobody's second task inside a change about something else. ## Related * #1109 - the second breakage and where this was raised * #1081 - the first one, on a different page, same shape * #1110 - the trim that unblocks `main` right now

coilyco-ops added the

autonomy

async-consult

priority

labels

2026-08-22 22:31:15 +00:00

coilyco-ops referenced this issue

2026-08-22 22:31:27 +00:00

main is failing the gate: two green pull requests exceeded a doc size cap together #1109

coilyco-ops referenced this issue

2026-08-22 23:16:42 +00:00

Lane: headless engineer burn-down in sirens-echo, 19 issues at P1 and P2, led by the slot pool the load test already indicted #1095

coilyco-ops referenced this issue

2026-08-23 00:20:58 +00:00

test(coalesce): a seam over the marks, so the Discord half is reachable #1123

coilyco-ops commented

2026-08-23 00:38:04 +00:00

Author

Member

Two hard numbers for this issue, both measured on main tonight rather than inferred.

docs/ holds exactly 40 markdown pages against a 40-page ceiling. Not near it, at it. The next feature that wants a page cannot have one until two existing pages merge, which is the remedy the band was designed around.

docs/sirens-echo-admission.md sits at 7996 characters against an 8000 cap. Four characters of headroom, as of #1123 landing. #1081 called 49 characters outgrown on a different page in the same situation. The next branch that touches that page at all turns main red, and per #568 nothing measures a merge result before it becomes main.

So the condition this issue describes is no longer approaching. It has arrived on one page and is one edit away on the directory. That does not change the remedy, which is still an editorial merge of two related pages rather than a cap raise, and it does move this out of the tail.

Two hard numbers for this issue, both measured on `main` tonight rather than inferred. **`docs/` holds exactly 40 markdown pages against a 40-page ceiling.** Not near it, at it. The next feature that wants a page cannot have one until two existing pages merge, which is the remedy the band was designed around. **`docs/sirens-echo-admission.md` sits at 7996 characters against an 8000 cap.** Four characters of headroom, as of https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/pulls/1123 landing. https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/1081 called 49 characters outgrown on a different page in the same situation. **The next branch that touches that page at all turns `main` red**, and per https://forgejo.coilysiren.me/coilyco-gaming/sirens-echo/issues/568 nothing measures a merge result before it becomes `main`. So the condition this issue describes is no longer approaching. It has arrived on one page and is one edit away on the directory. That does not change the remedy, which is still an editorial merge of two related pages rather than a cap raise, and it does move this out of the tail.

coilyco-ops referenced this issue

2026-08-23 01:42:07 +00:00

Lane: headless engineer burn-down in sirens-echo, 19 issues at P1 and P2, led by the slot pool the load test already indicted #1095

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/sirens-echo#1111

No description provided.

Rows
Columns