plan-authoring

Plan Authoring Guide

Agent-First Format Rule

Every plan.md section MUST use tables, key-value pairs, or tagged lists as primary format. Prose is limited to the Summary section (max 3 key-value lines). The primary consumer is an AI agent — optimize for parseability over readability.

Plan Writing Process

Phase 0: Research

1. HAS_TECH_CONTEXT_DOC = true → read as baseline; pre-fill Technical Context values, require only confirmation.
2. Extract unknowns (anything marked NEEDS CLARIFICATION) → research task per unknown.
3. Consolidate in research.md using structured format below. Merge by topic, rewrite full file.
4. Budget: ≤4KB. Existing >3KB → consolidate before adding.

research.md Format

Prohibited: code blocks, implementation snippets, comparison tables, narrative paragraphs, duplicate summary sections.

Per-topic: 4 structured fields, max 2 sources. Global budget: ≤4KB.

Consolidation: merge overlapping topics, normalize names, remove stale details.

Structure:

# Research: [Feature Name]
> Feature | Date | Purpose

## [Topic N]
- **Decision**: [what was chosen]
- **Rationale**: [why — max 1 sentence]
- **Rejected**: [alternatives and why — max 1 sentence]
- **Pitfalls**: [anti-patterns to avoid — max 1 sentence]
- **Sources**: [URL1], [URL2]

## Summary
| Topic | Decision | Rationale |
|-------|----------|-----------|

## Sources Index
| URL | Topic | Fetched |
|-----|-------|---------|

Phase 1: Design & Contracts

Prerequisites: research.md complete

Items 1–2 are conditional — auto-detect signals from spec; fall back to interactive prompt when ambiguous.

1. Data Model → data-model.md (conditional):
   • Generate when: non-empty "Key Entities", terms database/storage/persist/CRUD/entity/etc., or Storage ≠ N/A
   • Skip → replace Data Model Summary table with N/A — no persistent data
   • Include: entity names, fields, relationships, validation rules, state transitions
   • Populate ## Data Model Summary table in plan.md with entity overview