Learned Documentation Guide Overview: docs/learned/ contains agent-focused documentation with: YAML frontmatter for routing and discovery Hierarchical category organization (categories listed in index below) Index files for category navigation Routing tables in AGENTS.md Core Knowledge (ALWAYS Loaded) @learned-docs-core.md Document Registry (Auto-Generated) @docs/learned/index.md Frontmatter Requirements Every markdown file (except index.md) MUST have:
title : Document Title read_when : - "first condition" - "second condition"
Required Fields Field Type Purpose title string Human-readable title for index tables read_when list[string] Conditions when agent should read this doc Writing Effective read_when Values Use gerund phrases: "creating a plan", "styling CLI output" Be specific: "fixing merge conflicts in tests" not "tests" Include 2-4 conditions covering primary use cases Think: "An agent should read this when they are..." Good: read_when : - "creating or closing plans" - "understanding plan states" - "working with .erk/impl-context/ directories" Bad: read_when : - "plans"
Too vague
- "the user asks"
Not descriptive
- Documentation Structure
- Read the master index for current categories and documents:
- docs/learned/index.md
- The index contains:
- All category paths and descriptions
- Root-level documents
- Document listings with "Read when..." conditions
- Category Placement Guidelines
- Match by topic
- - Does the doc clearly fit one category? (see index above for categories)
- Match by related docs
- - Are similar docs already in a category?
- When unclear
- - Place at root level; categorize later when patterns emerge
- Create new category
- - When 3+ related docs exist at root level
- Distinguishing cli/ vs architecture/
- This is the most common confusion:
- cli/
- Patterns for building CLI commands - how users interact with the tool Fast-path patterns (skipping expensive ops) Output formatting and styling Script mode behavior Command organization architecture/ : Internal implementation patterns - how the code works Gateway ABCs and dependency injection Dry-run via wrapper classes Shell integration constraints Protocol vs ABC decisions Document Structure Template
title : [ Clear Document Title ] read_when : - "[first condition]" - "[second condition]"
[Title Matching Frontmatter] [1-2 sentence overview]
[Main Content Sections] [Organized content with clear headers]
Related Topics
Link to related docs - Brief description Index File Template Each category has an index.md following this pattern:
title : [ Category ] Documentation read_when : - "[when to browse this category]"
[Category] Documentation [Brief category description]
Quick Navigation | When you need to... | Read this | |
|
| | [specific task] | doc.md |
Documents in This Category
[Document Title] ** File: ** doc.md [1-2 sentence description]
Related Topics
Other Category
- Brief relevance
Reorganizing Documentation
When moving files between categories:
Step 1: Move Files with git mv
cd
docs/learned
git
mv
old-location/doc.md new-category/doc.md
Step 2: Update Cross-References
Find all references to moved files:
grep
-r
"old-filename.md"
docs/learned/
Update relative links:
Same category:
doc.md
Different category:
doc.md
To category index:
Category
Step 3: Update Index Files
Update Quick Navigation tables in affected index files.
Step 4: Update AGENTS.md
If the doc was in the routing table, update the path.
Step 5: Validate
Run
make fast-ci
to catch broken links and formatting issues.
Updating Routing Tables
AGENTS.md contains the Quick Routing Table for agent navigation.
When to Add Entries
New category additions
High-frequency tasks
Tasks where wrong approach is common
Entry Format
| [Task description] | → [Link or skill] |
Examples:
| Understand project architecture | → Architecture |
| Write Python code | → Load \
dignified-pythonskill FIRST |
Validation
Run before committing:
make
fast-ci
This validates:
YAML frontmatter syntax
Required fields present
Markdown formatting (prettier)
⚠️ Generated Files - Do Not Edit Directly
The following files are
auto-generated
from frontmatter metadata:
File
Source
docs/learned/index.md
Frontmatter from all docs
docs/learned/