Auto Doc Index — Derived Indexes from Frontmatter

Replaces hand-maintained index tables in README.md with auto-generated
tables derived from structured frontmatter in individual doc files.

Why This Matters — Real Evidence

In a real project with 13 ADR files, comparing hand-maintained index vs
auto-generated index revealed 8 discrepancies (62% error rate):

Issue Type	Example	Count
Title truncated	"activate none" vs actual "activate none by default"	2
Status fabricated

Index said "Decided" but file said "Accepted" | 3 |
| Date invented | Index showed "2026-01-28" but file had no Date field | 1 |
| Metadata lost | "(revised 2026-01-28)" stripped from status | 1 |
| Case "normalized" | decided silently changed to Decided | 4 |

These aren't hypothetical risks — they were already present and invisible
in a well-maintained project. Hand-editing creates a false sense of
correctness while the index silently diverges from its source files.

When to Use

• - Setting up a new documentation directory (ADR, RFC, Pitfall, Design Doc, etc.)
• Adding a new document to an existing indexed directory
• Onboarding a project that has hand-maintained doc indexes showing signs of drift
• Resolving recurring merge conflicts in shared README.md index tables
• Migrating from hand-maintained indexes to auto-generated ones

Boundaries

• - This skill generates index tables only — it does not create or modify the content of individual documents.
• The generator script replaces content only between <!-- INDEX:START --> and <!-- INDEX:END --> markers. All other README.md content is preserved verbatim.
• Do NOT use this for indexes that require editorial curation (e.g., "recommended reading order"). Auto-generation is for factual, exhaustive catalogs.
• Do NOT introduce YAML frontmatter parsing libraries — the regex-based approach is intentional to keep the script zero-dependency.
• This skill targets file-system-based documentation. It does not apply to wiki-style or database-backed doc systems.

Problem

A hand-maintained index in README.md is shared mutable state — every
new document requires editing the same file, same table, often the same diff
hunk. In multi-agent or multi-contributor workflows this creates:

• - Silent data loss: titles get shortened, statuses get "corrected"
• Merge conflicts: semantically independent changes collide in the same hunk
• Stale indexes: contributors forget to update, nobody notices
• Normalization illusion: edits look "cleaner" but diverge from source

Solution

Each document is self-describing via frontmatter. A generator script scans
the directory, parses frontmatter, and injects the index table between
<!-- INDEX:START --> / <!-- INDEX:END --> markers in README.md.

Write ops become N:N (each file independent). Index becomes a stateless pure function.

Setup Steps

1. Define frontmatter convention

Choose a frontmatter format for your doc type. Two common patterns:

Pattern A — Inline metadata (ADR/RFC style):
CODEBLOCK0

Pattern B — Bold-field metadata (Pitfall/Postmortem style):
CODEBLOCK1

2. Add markers to README.md

Wrap the existing index table (or create a placeholder) with markers:

CODEBLOCK2

Content outside markers is never touched by the generator.

3. Create the generator script

Copy template/generate-doc-index.ts from this skill's template directory,
or generate a new one following the pattern below.

Core architecture (zero external dependencies):

CODEBLOCK3

See template/generate-doc-index.ts for a
working implementation that handles both Pattern A and Pattern B.

4. Run the generator

CODEBLOCK4

5. Update documentation governance

Add to your project's AGENTS.md or CONTRIBUTING.md:

Rule: Never hand-edit the index table between <!-- INDEX:START/END -->
markers. To add a new document, create the .md file with proper
frontmatter, then run the generator.

Workflow Comparison

CODEBLOCK5

Adding a New Doc Type

To support a new document category (e.g. RFCs, Design Docs):

1. 1. Define the frontmatter convention
2. Add a parser function (regex for title, status, date, etc.)
3. Add a table generator function (column layout)
4. Add <!-- INDEX:START/END --> markers to the README.md
5. Register in the script's main() dispatcher

Anti-patterns

• - Do NOT use YAML frontmatter libraries — regex is sufficient and avoids deps.
• Do NOT generate the entire README.md — only the index section. Preserve

manually-written intro, templates, and notes via the marker pattern.

• - Do NOT require contributors to run the generator before committing.

Run it in CI or as a pre-commit hook for enforcement.

Checklist

CODEBLOCK6