Learned Documentation Guide

Overview:

docs/learned/

• YAML frontmatter for routing and discovery
• Hierarchical category organization (categories listed in index below)
• Index files for category navigation
• Routing tables in AGENTS.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

title

read_when

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 .impl/ folders"

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

1. Match by topic - Does the doc clearly fit one category? (see index above for categories)
2. Match by related docs - Are similar docs already in a category?
3. When unclear - Place at root level; categorize later when patterns emerge
4. 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](../category/doc.md) - Brief description

Index File Template

Each category has an

index.md

---
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](doc.md) |

## Documents in This Category

### [Document Title]

**File:** [doc.md](doc.md)

[1-2 sentence description]

## Related Topics

- [Other Category](../other/) - Brief relevance

Code in Documentation

Critical rule: NEVER embed Python functions that process erk data or encode business logic.

Why This Matters

Embedded Python code in documentation:

• Is NOT under test - it silently goes stale
• Causes bugs when agents copy outdated patterns
• Encodes business assumptions (field names, conventions) that can change
• Creates maintenance burden requiring docs-code sync

PR #2681 demonstrated this: an agent copied incorrect scratch directory paths from documentation because the docs hadn't been updated when the implementation changed.

The "Simple Function" Trap

Even "simple" functions are dangerous. A one-liner like:

# DANGEROUS - encodes `agent-` prefix convention
files = [f for f in dir.glob("*.jsonl") if not f.name.startswith("agent-")]

Embeds a naming convention that could change. When it does, the docs become a source of bugs.

What to REMOVE (Aggressive Stance)

Remove ALL Python

def

• Process session logs, JSONL, or erk data
• Encode path patterns or naming conventions
• Filter, parse, or transform erk-specific data
• Implement algorithms that exist (or could exist) in production
• Show "how to" implementation patterns for erk internals

Even if the function doesn't exist in production today, it could be added later, creating divergence.

Class Templates and File Listings

Also REMOVE:

Class templates:

• Full class definitions showing "how to implement X"
• Method implementations from base classes
• Example classes that duplicate actual implementations

Directory/file listings with counts:

• Lines like

  ├── skills/  (2 files)

  - counts go stale
• Exhaustive file listings enumerating every file

Replace with:

• Source references: "See

  path/to/example.py

  for the pattern"
• Structural trees without counts showing organization
• CLI commands: "Use

  ls dir/

  to see current files"

What to KEEP (Narrow Exceptions)

• JSON/YAML format examples: Showing data structure, not processing code
• External library patterns: Click commands, pytest fixtures, Rich tables (teaching third-party APIs)
• Anti-pattern demonstrations: Code explicitly marked "WRONG" or "DON'T DO THIS"
• Shell/bash commands:

  ls

  ,

  jq

  ,

  grep

  for operational tasks
• Type definitions: Dataclass/TypedDict showing structure (not methods)

Decision Test

Before keeping a Python code block, ask:

1. Does it contain a

   def

   statement? → Probably REMOVE
2. Does it process erk-specific data? → REMOVE
3. Does it encode a convention (field name, path pattern, prefix)? → REMOVE
4. Is it teaching a third-party API (Click, pytest, Rich)? → KEEP
5. Is it showing data FORMAT (not processing)? → KEEP
6. Does it show a class template? → REMOVE, reference source
7. Does it list files with counts? → REMOVE counts, use structural tree

Replacement Format

When removing code, replace with:

1. Prose description of what the operation does
2. Source pointer to canonical implementation
3. CLI command if one exists for agents to use

Before (BAD):

```python
def find_session_logs(project_dir: Path) -> list[Path]:
    """Find all main session logs (exclude agent logs)."""
    return [
        f for f in project_dir.glob("*.jsonl")
        if f.is_file() and not f.name.startswith("agent-")
    ]
```

After (GOOD):

Main session logs are `.jsonl` files that don't start with `agent-`. Agent
subprocess logs use the `agent-<id>.jsonl` naming convention.

To list sessions for a project, use:
erk exec list-sessions

See `preprocess_session.py` for the canonical implementation.

Source Pointer Rules

• Point to source file path:

  package/module.py

• NEVER include line numbers (they go stale)
• Use backticks for file paths
• Prefer CLI commands over source pointers when available

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](doc.md)

• Different category:

  [doc.md](../category/doc.md)

• To category index:

  [Category](../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

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](docs/learned/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:

docs/learned/index.md

docs/learned/<category>/index.md

docs/learned/<category>/tripwires.md

tripwires:

docs/learned/tripwires-index.md

Never edit these files directly. Changes will be overwritten.

Workflow for Changes

1. Edit the source frontmatter in the relevant documentation file(s)
2. Run sync:

   erk docs sync

3. Verify changes in the generated files
4. Commit both the source and generated files

Adding a New Tripwire

To add a tripwire rule:

1. Add to the

   tripwires:

   field in the relevant doc's frontmatter:

   tripwires:
     - action: "doing something dangerous"
       warning: "Do this instead."
   

2. 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