Should the long chapters go? The appraisal Munim asked for on 31 August, measured 2 September

Authored by the session that succeeded FIX 6 (the "NOT NAMED" session), 2026-09-02, on the Mac Studio. This answers a question he asked at 2026-08-31 17:26 that no session in the FIX chain answered. The research half was done that night by FIX 2 (six agents, research-2026-08-31-repo-architecture/); the measurement on this tree was not, and it is what settles the question.

The question, verbatim (recovered from FIX 1's recording, 2026-08-31T17:26:47Z)

"...to get rid of the extensive list of checks we're doing. My understanding is these checks are being done because a playbook is written in a number of different sections and chapters, and a change in one chapter affects many other chapters. So all these checks have to be done. Is that correct? Or is that too simple?

If that's in any way correct, I'm starting to question whether we should completely delete all the long chapters of the playbook because this is not creating a book here—really, we're creating a machinery, a mechanism. All of how it works can be described, I imagine, within a summary of a couple of pages, whatever the equivalent would be, because most of the detail of how something works is written kind of like blueprints or actually within the machinery itself.

So, within the skills, the guards, etc.—being simply told where to look figures out how something works. Having high-level diagrams or high-level indexes, references explaining where things are, how things work, how things click with each other is really the way to go.

I appreciate that would be a massive rewrite for ShipIt and a lot of deletions, but I'm seriously thinking that's the way forward. One particular way might be that we keep a copy of the ShipIt repo for posterity's sake in case whatever changes we make are bad.

I would love your appraisal and follow a multi-faceted approach to appraise what I'm saying, if you need to—if you can do it yourself, that's fine too. Correlate it with research for things like the ShipIt repo, find online what the best practices are, and whether what I'm saying is correct or incorrect.

Because currently, what exists just seems impractical."

The answer in three sentences

1. The premise is too simple. 70 of the 99 checks never read a chapter at all; they guard the machinery (skills, templates, hooks), the repo's own upkeep files, and each other. Of the 29 that do read a chapter, 13 exist because a chapter is the MASTER copy of a fact the machinery uses, and exactly 1 compares a chapter with another chapter.
2. The direction is right. The published evidence FIX 2 gathered says overviews are dead weight to an agent and redundancy, not length, is the real cost. The guide is 184K words, hand-synchronised on 73 of the 84 commits that touched it in the last 30 days, and nothing shipped to a founder depends on most of it.
3. Deleting it wholesale today deletes three procedures nothing else holds. The release procedure, the blueprint audit and the stage map exist ONLY as chapters, and the navigator sends a founder to read them because no command covers them. So the order is: move those into the machinery first, then delete, with a git tag as the posterity copy.

The measurements, each with the command that produced it

All on ~/ship-it at 7418e93f, 2026-09-02, Mac Studio.

M1. Which checks read the guide. 99 scripts in scripts/lint-*.sh scripts/check-*.sh (ls | wc -l). For each, grep -c 'guide/': 29 mention the guide, 70 do not. Of the 29, the ones whose job is "a chapter and the machinery must say the same thing", read off their own capability-map line and their guide/ targets: lint-stage-numbering (00a), lint-pipeline-agreement (skills-guide, 00a), lint-security-floor-rows (11), lint-document-hierarchy-agreement (02), lint-review-pipeline-complete (09, skills-guide, 01b), lint-model-currency (12), lint-anti-slop-canonical (08b), lint-command-position-claims, lint-quickref-complete (11, the only chapter-vs-itself check), lint-guide-false-promise (07, 01b), lint-guide-prescribes-lintable-code (01, 09, anti-patterns), lint-skill-listed (skills-guide, 00a), lint-cadence-tracked (skills-guide, 00a). 13. The rest of the 29 scan the guide as one of several directories for a generic fault (a dash, a phantom script, a library-only path).

M2. What breaks when the guide is deleted. Two throwaway clones under the scratchpad, git rm -r guide in one, every one of the 105 lint/check scripts run in both with a 120 s cap (run-checks.sh, control.tsv / noguide.tsv). 10 of 105 change status: 7 correctly report NOT-MEASURABLE (ephemeral-handoff, guide-false-promise, pipeline-agreement, quickref-complete, security-floor-rows, skill-listed, stage-numbering); 3 go red (document-hierarchy-agreement, orphaned-pointer, repair-damage, the last because the navigator claims parity with a stage map that no longer exists). 13 were red in both arms (runner artefacts and the two known-red checks). lint-broken-anchor resolves 331 section citations with the guide and 240 without: 91 section-level pointers lead into the guide. One check, lint-guide-prescribes-lintable-code, stayed GREEN with the guide gone (it read 61 template files and said PASS), which is the blind-green the plan's Phase 0 names and is fixed in this session.

M3. Who points at each chapter from the surfaces a founder receives. git grep -oh 'guide/[^ ]*\.md' -- skills/ templates/ references/ | sort | uniq -c: 151 pointer lines into 25 chapters. Top: 09-quality-gates 24, 12-prompt-engineering 18, skills-guide 14, 01b 13, anti-patterns 12, 17-claude-md-authoring 10, 00a-workflow-map 10, 11-hardening-release 7. Four chapters are named by nothing but the README: 16-product-surface, 08c-stitch-design-workflow, 05a-backend-core, 15-recovery-troubleshooting, 15,954 words (the plan's Phase 8 count, reproduced).

M4. Chapters that ARE a procedure, not a description. skills/universal/implementation-guide.md (the navigator every project gets on day one) lines 409, 432, 436, 558: Stage 10 is "Walk guide/11-hardening-release.md end-to-end", the blueprint audit is "a manual walkthrough of guide/04-blueprint-audit.md Rounds A–D, not a skill", and "/deploy, /ship, /release: No deploy skill. Follow guide/11". Line 123: "Stage numbers are the canonical map's numbers", the map being guide/00a-workflow-map.md (120 table rows). Three procedures and the stage table live only in chapters.

M5. The upkeep tax. git log --since=30.days -- guide/ | wc -l: 84 commits touched the guide in 30 days; 73 of them also touched skills/, templates/ or scripts/, which is lint-executable-surface doing its job and is also the cost of a second copy made visible.

M6. Who reads it as a human. The 47 deployed deck pages (dist/, modules/janika-welcome/*.html) name 0 chapters (command grep, positive control 11 hits on the working notes beside them). Janika's onboarding working note names 8 chapters; the README names 8. Munim, 2026-08-31: "I'll only read what you show me here in the transcripts and terminal CLI."

The research, as FIX 2 found it (plan findings 3, 4, 5, 6; sources in research-2026-08-31-repo-architecture/)

• Overviews are not followed, instructions are (Gloaguen et al., arXiv:2602.11988; SkillsBench: comprehensive prose +0.7pp against focused docs +19 to +21pp). The guide is mostly overview.
• Redundancy, not length, is what costs: delete every other .md and the same context file flips from useless to helpful (same paper). The guide is a second copy of facts the machinery owns.
• Length does not suppress a rule (this repo's own Phase 5, 60 runs, 100% vs 100%). So cutting is for navigation and for the second-copy tax, never for instruction-following.
• AI-authored instructions score BELOW none (SkillsBench self-generated, −8 to −11pp). So whatever replaces a chapter must be curated by a person or moved verbatim, never regenerated.
• Anthropic's own practice (Cherny, July 2026): delete everything, restore line by line, measure. A chapter earns its place only if something that executes points at it for a fact.

CORRECTION 2026-09-02, made by this same session before anything was deleted. Read it before move 1.

M3 was measured over skills/ templates/ references/ only, and I then wrote "named by nothing but the README", which is a claim about the WHOLE repo that the measurement never made. Re-run over everything (command grep -rln '08c-stitch', excluding the handover folder and the chapter itself): guide/08c-stitch-design-workflow.md is named by seven files — guide/12-prompt-engineering.md, guide/05-architecture.md, guide/08-design-workflow.md, guide/08d-mobile-device-testing.md, meta/skill-authoring.md, feedback/system-review-log.md and README.md. There is no chapter here that nothing names. What M3 actually measured, and all it measured, is that no SHIPPED surface points at these four.

And the deeper test says three of the four hold facts nothing else holds. Distinctive strings searched across skills/, templates/ and the rest of guide/:

So move 1 as written was wrong and NOTHING WAS DELETED. "Nothing points at it" is a claim about ROUTING; "nothing else holds it" is a claim about CONTENT, and only the second licenses a deletion. An unrouted chapter holding a unique procedure is a routing defect, not dead weight, and deleting it destroys the procedure while leaving the defect. This is meta/lessons.md > L-0091 (the cheap observable standing in for the property) committed by the appraisal built to avoid it.

The corrected order: there is no free first move. The cut starts at move 2, the authority inversion, for every chapter including these four, and each chapter leaves only when the fact it holds lives in something that runs. 08c is the one that could go soonest, because its unique half is already in the shipped design command; it still needs a pass to confirm nothing is lost.

The recommendation, and what it costs

Cut the guide to what executes, in three moves, in this order.

1. Delete the four chapters nothing names (15,954 words). Zero dependents by M3; the only pointers are the README's index lines. One commit. WITHDRAWN by the CORRECTION above, 2026-09-02, before any deletion. Both of its premises failed re-measurement.
2. Invert the authority. For each fact a chapter is the master copy of (M1's 13 checks, M4's three procedures): move the fact into the surface that runs it, retarget the check, then the chapter is prunable. Concretely: the stage table into the navigator or a data file the navigator reads; the release chapter into a /release command; the blueprint audit into a /blueprint-audit command; the security-floor rows into the file that runs the gate; the model tier table and the document hierarchy into the rulebook template. Each is one commit that re-proves two or three checks. This is what the independent reviewer said had to come first (FIX 2 report, item 7) and it was piloted once on the model tier (bd182ba).
3. Judge the rest by pointers, not by length. A chapter stays only if a shipped surface points at a SECTION of it for a fact (M2's 91 anchors are the list). Everything else becomes one line in the index Munim described: where it is, what it does, what it clicks into. The map at meta/architecture-map.html is that index's picture; guide/00a-workflow-map.md is its table.

The posterity copy is a git tag (guide-before-cut-2026-09-02), not a second repository: git already keeps every byte, and a second copy is the redundancy the research warns against.

What deleting wholesale today would cost instead (M2, M4): three procedures with no command to replace them, 151 dangling pointers refused by lint-orphaned-pointer, 10 checks flipped, and a navigator claiming parity with a map that is gone.

What has actually been done, 2026-09-02

Munim ruled the same day, asked with the alternatives priced: the three moves in order, over deleting the whole guide today and over cutting only the four unnamed chapters; and the posterity copy is a dated bookmark in the saved history, over a second copy of the repo. Filed as meta/decisions.md > D-0014.

1. The posterity bookmark exists and is on GitHub: the tag guide-before-cut-2026-09-02, holding all 28 chapters as they stood. git checkout guide-before-cut-2026-09-02 -- guide/<file> brings any one of them back.
2. Nothing was deleted, and the reason is the CORRECTION above, which was found and written before any deletion rather than after one.
3. The first authority inversion is DONE: the Security Floor. The eight rows of the blocking launch gate now belong to templates/SECURITY_FLOOR_TEMPLATE.md, which ships into every project, and the chapter explains why each row exists and defines nothing. Chosen first because it was the clearest case of the whole fault: a page no founder can open owning the gate the method calls "no ship below this line". scripts/lint-security-floor-rows.sh carries the new direction in its header, its two runtime labels and both mismatch messages; self-test 18/18, both arms PASS, 8 rows matched. The generalisable half: an inversion is mostly WORDS, and it is not done until the surface a person reads AT RUNTIME says it too — the header said the new thing while the printed labels still called the chapter the definer.
4. A check that had gone green while blind was repaired in the same pass. The two-clone probe that produced M2 caught lint-guide-prescribes-lintable-code.sh printing PASS off the 61 template files alone, having read no chapter, because its empty-scan guard tested the UNION of its two halves. It now refuses when the guide half is empty, proved in both directions. That was PHASE 0's last unmarked bullet in the restructuring plan.

Still to invert, in order of size: the stage map (guide/00a-workflow-map.md, read by four checks and by the navigator every project receives), then the release procedure and the blueprint audit, which are both STAGES a founder is told to walk with no command to run.

What would change this answer

• A shipped surface found to depend on a chapter this measurement did not see (M3 searched skills/ templates/ references/; scripts/ and .claude/ were searched in M1 and the probe).
• Munim ruling that the third persona (a founder arriving from GitHub with no context) needs a book and not an index. Nothing measured here speaks to that reader.