Skip to content

Restructure README for information hierarchy (TL;DR-first)#23

Merged
kgohil merged 1 commit into
mainfrom
readme-info-hierarchy
Jun 24, 2026
Merged

Restructure README for information hierarchy (TL;DR-first)#23
kgohil merged 1 commit into
mainfrom
readme-info-hierarchy

Conversation

@kgohil

@kgohil kgohil commented Jun 24, 2026

Copy link
Copy Markdown
Owner

Reorder (not rewrite) so the benefit/result lands immediately after the mascot + diagram, per the inverted-pyramid / front-load principle:

  1. Hero (mascot + agentic-loop image) — unchanged.
  2. TL;DR — punchline + the measured win (−56% files / −12% tokens / −20% time).
  3. What it gives you — 4 scannable headline bullets (map · reuse-first · self-maintaining · any agent) + jump links.
  4. The problem it solves — the old opening narrative, demoted to context.
  5. … Before/after → How it works → Early signal → Setup → In the box (full detail) → Design stance → Inspiration.

So: TL;DR → what it enables → important → less important. Docs-only; no version change.

Not a rewrite — a reorder for how info lands on first read. After the hero
(mascot + agentic-loop image), lead with the result, not the problem:

- New TL;DR: the punchline + the measured win (-56% files / -12% tokens /
  -20% time) up top.
- 'What it gives you': 4 scannable headline bullets (map / reuse-first /
  self-maintaining / any agent).
- Quick jump links (How it works · numbers · setup).
- Demote the problem narrative under '## The problem it solves' (context, not
  the opener).
- Rename the detailed lower list to 'In the box (full detail)' — the less-imp
  inventory stays, below the fold.

Applies the copy-editing 'lead with the outcome / front-load' sweep.
@kgohil kgohil merged commit adff3e2 into main Jun 24, 2026
3 checks passed
@kgohil kgohil deleted the readme-info-hierarchy branch June 24, 2026 05:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant