learned-docs

@docs/learned/index.md

Every markdown file (except index.md) MUST have:

```yaml

---

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:

```yaml

read_when:

- "creating or closing plans"

- "understanding plan states"

- "working with .impl/ folders"

```

Bad:

```yaml

read_when:

- "plans" # Too vague

- "the user asks" # Not descriptive

```

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

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

```markdown

---

title: [Clear Document Title]

read_when:

- "[first condition]"

- "[second condition]"

---

# [Title Matching Frontmatter]

[1-2 sentence overview]

[Organized content with clear headers]

• [Link to related docs](../category/doc.md) - Brief description

```

Each category has an index.md following this pattern:

```markdown

---

title: [Category] Documentation

read_when:

- "[when to browse this category]"

---

# [Category] Documentation

[Brief category description]

| When you need to... | Read this |

| ------------------- | ---------------- |

| [specific task] | [doc.md](doc.md) |

[Document Title]

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

[1-2 sentence description]

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

```

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:

```python

# 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 functions that:

• 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):

````markdown

```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):

```markdown

Main session logs are .jsonl files that don't start with agent-. Agent

subprocess logs use the agent-.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

When moving files between categories:

Step 1: Move Files with git mv

```bash

cd docs/learned

git mv old-location/doc.md new-category/doc.md

```

Step 2: Update Cross-References

Find all references to moved files:

```bash

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 to catch broken links and formatting issues.

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

```markdown

| [Task description] | → [Link or skill] |

```

Examples:

• | Understand project architecture | → [Architecture](docs/learned/architecture/) |
• | Write Python code | → Load \dignified-python\ skill FIRST |

Run before committing:

```bash

make fast-ci

```

This validates:

• YAML frontmatter syntax
• Required fields present
• Markdown formatting (prettier)

The following files are auto-generated from frontmatter metadata:

| File | Source |

| -------------------------------------- | ------------------------------------- |

| docs/learned/index.md | Frontmatter from all docs |

| docs/learned//index.md | Frontmatter from category |

| docs/learned//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

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:

```yaml

tripwires:

- action: "doing something dangerous"

warning: "Do this instead."

```

1. Run erk docs sync to regenerate tripwires.md

• Full navigation: [docs/learned/guide.md](docs/learned/guide.md)
• Category index: [docs/learned/index.md](docs/learned/index.md)
• Regenerate indexes: erk docs sync
• Run validation: make fast-ci