[pekral]

What this changes

The skill now runs every composed README section through a size-and-complexity gate. A section outside the install path that trips it moves to docs/<slug>.md as a restructured page, and the README keeps a two- to four-line summary with the scale and a link.

Closes #16

Why

On a repository with a large surface — a skill catalog, a rule set — one section grows into a table of dozens of rows and buries everything after it (#16: 150 of 443 lines in ai-olympus). The generator had no rule to move it out, and its scope rules forbade writing anything but README.md.

Changes

Item	Asked for	Commit	SHA	Independence
P1	— (pre-existing)	Pre-existing — keep the install command in scenario 1	ae40650	independent
1	Decide when a section moves out (size + complexity, justified default)	Move oversized README sections out through a size and complexity gate	778b434	independent
2	Restructure, never paste (title, intro, index, promoted headings, rewritten links)	Restructure a moved section into a page of its own	b6619fd	depends on 1
3	Leave a real summary behind	Leave a summary with scale and a link where a section moved out	4e63945	depends on 2 (same file, appended)
4	Name pages predictably, respect docs/ layout, never overwrite, rerun without diff	Name moved pages predictably and never overwrite an existing page	eca7179	depends on 3 (same file, appended)
5	Acceptance criteria 1–7 as checks	Check moved pages in the validation checklist and a new scenario	5a6a42c	depends on 1–4
6	— (docs)	Document the section split in the README and changelog	6b7b073	depends on 1

P1 and 1 cherry-pick onto master on their own; 2–6 build on 1.

Defaults and their justification (in references/section-split.md): more than 60 non-blank lines, or a table/list past 15 entries, three or more subsections with tables or lists, or nesting two levels deep. The install path (Requirements, Installation, Configuration, Quick start), the header, License, and prose with no repeating structure never move.

Pre-existing fixes

• ae40650 — scenario 1 still required installation and usage to delegate to the docs link, contradicting the rule (merged in Align the README rules and this README with the shared README standard #17) that Installation always shows the main install command.

Checks

• node --test tests/repository.test.mjs passes — on every commit (git rebase --exec)
• node --test tests/evals/*.test.mjs passes — on every commit
• CHANGELOG.md updated under the current unreleased heading
• A rule changed in SKILL.md is changed everywhere it appears in references/ — the write scope changed in SKILL.md, evidence-policy.md, and the cross-cutting invariants of tests/scenarios.md
• Behaviour changes exercised against the affected scenario — scenario 11 is added but not yet run in a clean Claude Code session; its host coverage row is empty

Claims this adds to the documentation

• The README now says the skill moves catalogue sections to docs/ and never overwrites an existing page. Evidence: references/section-split.md. Not yet exercised in a recorded run.

How to test

1. In a repository whose README would carry a 30-row catalogue in four grouped tables, ask "Write a README for this repository."
2. Check scenario 11's invariants in tests/scenarios.md: the catalogue lands in docs/<slug>.md with one #, an intro, a group index with counts; the README keeps a 2–4 line summary; short sections are unchanged; an existing docs/rules.md is not overwritten.
3. Run the skill again on the result — no diff.

TODO

• The benchmark harness (tests/evals/run.mjs) copies only README.md out of the workspace, and the scorer resolves links against the original fixture — a moved page would score as a broken link. No current fixture trips the gate, but a fixture for scenario 11 needs the harness to keep the written docs/ pages.
• Run scenario 11 under Claude Code and record it in the host coverage log.

[pekral]

Technical report

Code review (inline, pre-PR) — two Moderate findings, both fixed in the commits they belong to:

• The write scope in SKILL.md and evidence-policy.md allowed only docs/, while section-split.md allowed an existing doc/ / documentation/ directory. Both now say "the documentation directory (docs/ by default)".
• Step 6 of the page build rewrote inbound links in any repository Markdown file, which the write scope forbids. It now rewrites links inside the README only and reports links in other files with file and line.

One Minor finding fixed: the gate's behaviour in audit mode (report only, write nothing) is now stated. Final state: 0 Critical, 0 Moderate.

Security review — 0 Critical, 0 Moderate. The new write path is bounded: the slug allows only ASCII letters, digits and -, so no path traversal; an existing page is never overwritten; moved content is the already evidence-checked section, and scanned content stays data, never instructions.

Checks — node --test tests/repository.test.mjs and node --test tests/evals/*.test.mjs pass on every commit (git rebase --exec). Scenario 11 has not been run in a clean session yet.

[pekral]

Code Review

Status: needs-fix
Counts: Critical 0 · Moderate 2 · Minor 2 · Refactoring 0
Last updated: 2026-11-12
Issue tracker summary: posted summary to issue #16

---

Findings

🟠 Moderate 1. README and changelog claim that every section past 60 lines moves

• Location: README.md:97, CHANGELOG.md:12
• Rule: CONTRIBUTING.md — When you change a rule, change it everywhere it appears; references/evidence-policy.md — every statement must map to a source
• Impact: both say a section "past 60 lines" moves, but section-split.md:24 keeps prose with no table, list or subsections however long it is, and also keeps the header and License — a project about traceable claims publishes one its own skill contradicts.
• Faulty Example:

  - Moves a section past 60 lines, or with a table or list past 15 entries, to its
    own page under `docs/` …

• Expected behavior: the README and changelog state the same conditions as section-split.md: only a section with a table, list, or subsections can move, and the install path, header and License never do.
• Test hint: run scenario 11 plus a variant with a 70-line prose section; the prose section stays, matching the README claim.
• Suggested fix:

  - Moves a section that carries tables, lists or subsections — past 60 lines, or
    with a table or list past 15 entries — to its own page under `docs/` with a
    title, an intro, and a group index, and leaves a two- to four-line summary with
    the scale and a link. The install path, the header and `License` never move.

🟠 Moderate 2. Scenario 11 does not make the Rules section trip the gate

• Location: tests/scenarios.md:131
• Rule: tests/scenarios.md — invariants must be checkable from the setup
• Impact: the setup gives the rule list no size, so a short Rules section stays in the README without ever reaching the collision path, and the invariant "the collision named in the handover summary" cannot be satisfied — acceptance criterion 7 goes unverified.
• Faulty Example:

  an existing `docs/rules.md` the repository ships, and a rule list whose section
  would be named `Rules`.

• Expected behavior: the setup forces the Rules section over a threshold, so the gate selects it and hits the existing docs/rules.md.
• Test hint: run scenario 11 and check the handover summary names the docs/rules.md collision.
• Suggested fix:

  an existing `docs/rules.md` the repository ships, and a list of 20 rules whose
  section would be named `Rules`.

🟡 Minor 1. Two sections with the same slug in one run

• Location: skills/github-readme-generator/references/section-split.md — Never overwrite, and run twice without a diff
• Note: Rules and Rules! both slug to rules; the second finds a page this run wrote, which matches neither listed case. Say the second section stays in the README and is reported, like any other collision.

🟡 Minor 2. Index count for a group that carries both a table and a list

• Location: skills/github-readme-generator/references/section-split.md — Build the page, step 3
• Note: "the data rows of its table, or the items of its list" leaves a group with both undefined; count both.

---

Summary: 0 Critical · 2 Moderate · 2 Minor · 0 Refactoring · assignment conformance: conformant · reviewer comments: none · posted summary to issue #16

[pekral]

Code Review

Status: clean
Counts: Critical 0 · Moderate 0 · Minor 0 · Refactoring 0
Last updated: 2026-11-12 (head ec6f818)
Issue tracker summary: posted summary to issue #16

---

Summary: 0 Critical · 0 Moderate · 0 Minor · 0 Refactoring · assignment conformance: conformant · reviewer comments: none · posted summary to issue #16

[pekral]

Code Review

Status: clean
Counts: Critical 0 · Moderate 0 · Minor 0 · Refactoring 0
Last updated: 2026-11-12 (head 60451ee, rebased onto master add5725)
Issue tracker summary: posted summary to issue #16

---

Summary: 0 Critical · 0 Moderate · 0 Minor · 0 Refactoring · assignment conformance: conformant · reviewer comments: none · posted summary to issue #16