Repository navigation
Split oversized README sections into their own docs pages #16
Description
Problem
The generator writes every section into the root README.md, whatever its size. On a repository
with a large surface — a skill catalog, a rule set, a command reference — a single section grows
into a table of dozens of rows, and the README becomes a document nobody reads top to bottom.
A concrete case: in pekral/ai-olympus the ## Skill Catalog and ## Rules Overview sections were
150 lines of a 443-line README. Two tables, 55 and 27 rows, sitting between the installation
instructions and everything that follows. A reader looking for the quickstart scrolled past both.
Moving each into its own page under docs/ and leaving a three-line summary with a link cut the
README by a third and made both tables more useful, because each page could then be restructured
for its own content — the catalog gained a group index with per-group counts, and the rule set was
regrouped by scope instead of listed as one flat table.
The generator should reach that outcome on its own.
What to build
Add a size-and-complexity gate to the section-writing step. When a section exceeds the threshold,
the generator writes it to its own page under docs/ and replaces the README section with a short
summary plus a link.
1. Decide when a section moves out
The gate reads the section the generator has already composed, before it is written. A section
moves out when it meets either condition:
- Size — the rendered section exceeds a line threshold. Propose a default and state it in the
skill; do not hardcode a number without justifying it against real READMEs. - Complexity — the section carries a repeating structure long enough to need navigation of its
own: a table beyond N rows, three or more subsections each carrying a table or list, or nested
subsections two levels deep.
A section below both thresholds stays in the README unchanged. The gate never splits a short
section, and never splits prose that has no repeating structure — a long narrative section is not
a catalog.
2. Restructure, never paste
The moved page is not the README section with a new filename. It is the same content organised for
a page of its own:
- a
#title and a one-paragraph statement of what the page holds, - an index when the page carries three or more groups — a table of the groups with the count of
rows in each, linking to the anchors below, - the original subsections promoted one heading level (
###becomes##), - every relative link rewritten for the new depth (
](skills/x/)becomes](../skills/x/)).
3. Leave a real summary behind
The README section keeps its heading and gains two to four lines: what the section covers, the
scale (55 skills, 27 rule files), and a link to the page. Never leave a bare See docs/x.md
line — a reader must learn what is there without following the link.
4. Name the pages predictably
docs/<section-slug>.md, derived from the section heading. Respect an existing docs/ layout when
the repository already has one, and never overwrite a page the repository already ships.
Acceptance criteria
- A README section under both thresholds is left in place, byte-identical to what the generator
writes today. - A section over either threshold is written to
docs/<slug>.mdand replaced in the README by a
summary of two to four lines carrying the scale and the link. - The moved page carries a title, an intro paragraph, and — with three or more groups — a group
index with per-group counts. - Every relative link inside a moved section resolves from its new location. A link that pointed
at a real path before the move points at the same real path after it. - Heading levels inside the moved page are promoted by one, so the page has exactly one
#and no
orphan###under a missing##. - Running the generator twice produces no diff on the second run.
- An existing
docs/page not written by this run is never overwritten.
Out of scope
- Splitting a long narrative section that carries no repeating structure.
- Any change to which sections the generator composes, or to their content.
- A
docs/index page listing the generated pages.
Activity
pekral commentedon Nov 12, 2026
A fix is ready for review in #18.
What changed: when a README section grows into a long catalogue — a big table, many grouped lists — the skill now moves it to its own page under
docs/and leaves a short summary in the README saying what is there, how much (for example "55 skills"), and where to find it. Short sections, the installation steps and the first example always stay in the README. A page that already exists is never overwritten.How to test:
docs/with a title, an intro, and a list of groups with their counts, and that the README keeps two to four lines about it with a working link.Risk areas and edge cases:
Also covered by this PR: an older test scenario still expected the installation steps to be only a link to the docs; it now matches the current rule. Re-verify scenario 1 in
tests/scenarios.mdreads consistently with the README rules.pekral commentedon Nov 12, 2026
✅ Changes satisfy the assignment — all 7 acceptance criteria met. See Assignment Compliance below.
TL;DR
When a README section grows into a long catalogue, the skill now moves it to its own page under
docs/and leaves a short summary in the README. Short sections, the installation steps and the first example stay where they are.Authors: @pekral
Summary of changes
Long catalogue sections move to their own documentation pages
The change teaches the README skill when a section is too big to stay in the README: a section with tables or lists that runs past 60 lines, or holds more than 15 entries, or has several grouped parts. Such a section becomes its own page with a title, a short introduction and a list of its groups with counts, and the README keeps two to four lines saying what is there, how much, and where. The installation path never moves, a page that already exists is never overwritten, and running the skill twice changes nothing the second time.
How to test
docs/with a title, an introduction and a group list with counts, and that the README keeps a short summary with a working link.Assignment Compliance
Goal met: Yes
pekral commentedon Nov 12, 2026
✅ Changes satisfy the assignment — all 7 acceptance criteria met. See Assignment Compliance below.
TL;DR
The review findings are fixed: the README and changelog now describe exactly when a section moves, and the test scenario for an existing page is set up so it can actually be checked.
Authors: @pekral
Summary of changes
Section split description and test scenario corrected
The README and changelog now say that only sections with tables, lists or grouped parts can move, and that the installation steps, header and license never do — matching what the skill does. The test scenario for a page that already exists now uses a rule list big enough to be moved, so the "never overwrite" rule is really exercised. Two edge cases are now covered as well: two sections that would get the same page name, and a group that has both a table and a list.
How to test
Assignment Compliance
Goal met: Yes