# Decisions — Architectural and Design Choices

Agents: Search this before making a decision. A decision may already exist. Don't relitigate settled choices.

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

---

### Agent Pipeline Architecture
- **Options considered:** Single-agent workflow, 3-agent (plan/build/review), skills-based pipeline
- **Chosen:** Multi-agent subagent pipeline: Researcher -> Advisor -> Architect -> Designer -> Builder -> Tester -> Designer (post) -> Critic -> Debugger -> Refactor -> Reviewer
- **Why:** Each agent has its own context window, persistent memory, and tool restrictions. Prevents context bloat. Specialist agents (Compliance, Data Integrity) run on-demand.
- **Conditions to revisit:** If pipeline feels too slow, or if a step is consistently redundant.
- **Session:** 1
- **Tags:** #architecture, #pipeline

### Agent-Instruction Loops Over Hook-Based Iteration
- **Options considered:** Full hook-based loops (Stop hooks + bash loops), agent-instruction self-iteration, no iteration
- **Chosen:** Agent-instruction approach: tell Builder/Debugger/Refactor to self-iterate within their execution (type-check, fix, repeat, max N iterations)
- **Why:** Captures 80% of the iterative value with 10% of the infrastructure effort. Full hook-based loops add complexity and debugging surface area. Can upgrade later if insufficient.
- **Conditions to revisit:** If agents consistently fail to self-iterate effectively, upgrade to hook-based loops.
- **Session:** 1
- **Tags:** #pipeline, #agents

### Scoring Rubrics Over Subjective Quality Gates
- **Options considered:** Keep subjective severity levels only, replace with numeric rubrics, add rubrics alongside severity
- **Chosen:** Add 5-category numeric rubrics (0-5 each) to Critic and Reviewer agents. Keep severity levels for individual issues but add aggregate scoring for overall assessment.
- **Why:** Evidence-based scoring rubrics produce more consistent and trackable quality assessments than subjective review. Enables trend analysis across pipeline runs via METRICS.md.
- **Conditions to revisit:** If scoring feels formulaic and misses nuanced issues.
- **Session:** 1
- **Tags:** #pipeline, #quality