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

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-python skill 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/<category>/index.md

Frontmatter from category

docs/learned/<category>/tripwires.md

tripwires: field in category docs

docs/learned/tripwires-index.md

Category tripwires with routing hints

Never edit these files directly. Changes will be overwritten.

Workflow for Changes

• Edit the source frontmatter in the relevant documentation file(s)

• Run sync: erk docs sync

• Verify changes in the generated files

• Commit both the source and generated files

Adding a New Tripwire

To add a tripwire rule:

• Add to the tripwires: field in the relevant doc's frontmatter: tripwires:

  • action: "doing something dangerous" warning: "Do this instead."

• Run erk docs sync to regenerate tripwires.md

Quick Reference

• Full navigation: docs/learned/guide.md

• Category index: docs/learned/index.md

• Regenerate indexes: erk docs sync

• Run validation: make fast-ci