# Mistakes — What to Avoid

Agents: Read this before starting work. These are real mistakes from real pipeline runs. Don't repeat them.

**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`, `#data`)

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.

---

### Inconsistent Schema Output From Parallel Agents
- **What happened:** When multiple builder agents ran simultaneously, each independently chose different schema structures because the prompt did not specify the exact format.
- **Root cause:** Agent prompts did not include the EXACT target schema. Each agent independently decided.
- **Prevention:** Always include the EXACT target schema in the agent prompt when launching parallel builders. Specify field naming, nesting format, and conventions. Leave zero ambiguity.
- **Session:** 1
- **Tags:** #parallel-agents, #schema

### Hardcoded Paths in Multiple Files
- **What happened:** An absolute path was hardcoded in many files. When the project moved, every reference had to be updated manually.
- **Root cause:** Hardcoded absolute paths instead of using a single configurable variable or relative paths.
- **Prevention:** Define important paths in ONE place (environment variable, config file, or CLAUDE.md). All other files should reference that source. Makes future migrations trivial.
- **Session:** 1
- **Tags:** #architecture, #maintenance

### Status Change Not Propagated Across All Docs
- **What happened:** A project-wide status change was updated in the main doc but not in 10+ other files that referenced the old status.
- **Root cause:** No single source of truth. Status was duplicated across many files.
- **Prevention:** Major status flags should be documented in exactly ONE place with all other files referencing that source. When changing such a flag, grep the entire vault to find and fix all references.
- **Session:** 1
- **Tags:** #documentation, #consistency