standards-index

name	standards-index
description	Maintain the documentation index to prevent orphaned standards

Standards Index Skill

Keep all standard documents indexed and discoverable by maintaining category README files.

Context

Every standard document must appear in the appropriate category README, or it becomes "orphaned" — undiscovered and unused. This skill teaches you to scan, verify, and fix the standards index structure.

Domain Context

Standards are organized in docs/standards/ by category:

• engineering/ — Code patterns, architecture, APIs
• design/ — UI, styling, accessibility
• quality/ — Testing, governance, documentation
• operations/ — Deployment, monitoring, incidents
• architecture/ — Module boundaries, package design

Each category has a README.md that indexes all documents in that category. The index is the discoverable interface to all standards.

Reference: levels/L1-context/library/ structure

Instructions

1. Scan all category directories — Find every .md file that is not named README.md

   find docs/standards -type f -name "*.md" ! -name "README.md" | sort
   

   • Deliverable: Complete list of all standard files

2. Verify each file in the README — Check that each .md appears in its category's README.md

   • For each file found in step 1, search for it in the corresponding README.md
   • Format to look for: - [Title](./filename.md) — Description
   • Deliverable: List of files that ARE indexed (matches) and files that are NOT (orphaned)

3. Run check-doc-index.sh — Use verification script to catch any misses

   ./levels/L2-ceremonies/scripts/check-doc-index.sh
   

   • This script identifies orphaned documents and invalid references
   • Deliverable: Script output showing status

4. Fix orphaned documents — For each orphaned file:

   • Option A: Add reference to the appropriate category README
   • Option B: Delete the file if it's not needed (discuss with team first)
   • Option C: Move the file to the correct category
   • Update the README with alphabetized entry: - [Standard Name](./filename.md) — One sentence description
   • Deliverable: All orphaned docs either indexed or removed

5. Verify index coherence — Check that category READMEs are well-formed

   • Each README has a brief intro explaining the category
   • All entries are alphabetized by title
   • All descriptions are 1-line, scannable, consistent in format
   • Deliverable: Coherent, well-organized category indexes

Anti-Patterns

1. Orphaned standards — Documents that exist but are not indexed

   • Happens when: A standard is created but not added to README
   • Impact: Standard is never discovered or used
   • Guard: Before creating any .md file in docs/standards/, plan its README entry

2. Stale index entries — README links to files that no longer exist

   • Happens when: A file is deleted or moved, but the README is not updated
   • Impact: Broken references in agent context
   • Guard: When deleting or moving a standard, immediately update the README

3. Inconsistent formatting — README entries don't follow a pattern

   • Happens when: Multiple people edit READMEs without a template
   • Impact: Index is hard to scan and maintain
   • Guard: Use the template format consistently: - [Title](./file.md) — Description

Further Reading

• levels/L2-ceremonies/scripts/check-doc-index.sh — Verification script
• levels/L1-context/library/README.md — Example of well-maintained index
• AGENTS.md — How agent files reference the standards index