# Patterns — What Works Well

Agents: Read this before starting work. Use these patterns over inventing new ones.

**Entry format for new entries:**
- `Session:` and `Date:` — when first recorded (e.g., `Session 3, 2026-04-01`)
- `Last Validated:` — session number when last confirmed still accurate (e.g., `Session 5`)
- `Related:` — links to connected patterns/mistakes/decisions
- `Tags:` — for filtering (e.g., `#testing`, `#architecture`, `#pipeline`, `#research`)

Older entries may not have all fields yet — add `Last Validated:` when you reference or verify an entry. If `Last Validated` is 15+ sessions old, verify before relying on the entry.

---

### Semantic Search Over Full File Reads
- **What:** Use vault-search.py for context gathering instead of reading entire files. Dramatically reduces token usage while finding relevant content across the whole knowledge base.
- **Context:** Any time an agent needs to find context. Search by meaning, not keywords.
- **Session:** 1
- **Agent:** Researcher, all agents
- **Tags:** #research, #tokens

### Subagents Over Skills for Pipeline Steps
- **What:** Using subagents (own context window, persistent memory, tool restrictions) instead of skills for pipeline agents. Prevents main conversation context bloat and allows specialized tool access.
- **Context:** When defining pipeline stages that need isolated execution.
- **Session:** 1
- **Agent:** All pipeline agents
- **Tags:** #pipeline, #architecture

### Write to Files Incrementally, Never Batch at End
- **What:** For long tasks, write completed sections to output files as they're finished rather than holding everything in context until the end. Protects against context compaction AND gives real-time progress visibility.
- **Context:** Any task that produces a large document (research, specs, plans) or modifies multiple files.
- **Session:** 1
- **Agent:** All agents
- **Tags:** #reliability, #crash-recovery