Extract implementation decisions that downstream agents need. Analyze the phase to identify gray areas and capture decisions that guide research and planning. Headless SDK variant — in autonomous mode, AI self-discusses by analyzing available context and making decisions based on project artifacts and codebase patterns. **CONTEXT.md feeds into:** 1. **Researcher** — Reads CONTEXT.md to know WHAT to research - Locked decisions guide research focus - Discretion areas get options explored 2. **Planner** — Reads CONTEXT.md to know WHAT decisions are locked - Locked decisions become non-negotiable plan constraints - Discretion areas allow planner flexibility In headless mode, the AI acts as both visionary and builder. It: - Analyzes the phase goal and available context - Identifies gray areas that need decisions - Makes autonomous decisions based on codebase patterns, requirements, and best practices - Documents decisions clearly for downstream agents The phase boundary comes from the roadmap and is FIXED. Discussion clarifies HOW to implement what's scoped, never WHETHER to add new capabilities. When analysis suggests scope creep: note it in "Deferred Ideas" section, do not act on it. Load phase context from injected context files. Extract: phase directory, phase number, phase name, has_research, has_context, has_plans. If phase not found: report error via event stream. If CONTEXT.md already exists: load it and use as-is (in headless mode, existing context is not re-discussed). If no CONTEXT.md: proceed to analysis. Read project-level and prior phase context: - PROJECT.md — vision, principles, non-negotiables - REQUIREMENTS.md — acceptance criteria, constraints - STATE.md — current progress, decisions - Prior CONTEXT.md files — locked preferences from earlier phases Analyze the phase to identify gray areas: 1. **Domain boundary** — What capability is this phase delivering? 2. **Check prior decisions** — What's already decided from earlier phases? 3. **Gray areas by category** — For each relevant category, identify 1-2 specific ambiguities 4. **Auto-resolve each gray area** — Make decisions based on: - Codebase patterns (existing conventions) - Prior phase decisions (consistency) - Requirements (constraints) - Best practices (industry standard) 5. **Log each decision** with rationale **CRITICAL — Single-pass guard:** This step MUST complete in ONE pass. After writing CONTEXT.md, you are DONE. Do NOT re-read your own CONTEXT.md to identify "gaps", "undefined types", or "missing references" and run additional passes. Each decision naturally references other types and interfaces — this is expected, not a gap. The planner and executor will handle implementation details. Self-referential gap-finding creates an infinite loop where: 1. Pass N creates decisions referencing types/interfaces 2. Pass N+1 "discovers" those references as "gaps" 3. Pass N+1 creates new decisions that reference more types 4. Repeat forever Write your decisions once, comprehensively, then stop. Create CONTEXT.md capturing decisions made: ```markdown # Phase [X]: [Name] - Context **Gathered:** [date] **Status:** Ready for planning **Source:** AI self-discuss (headless mode) ## Phase Boundary [Clear statement of what this phase delivers] ## Implementation Decisions ### [Category] - **D-01:** [Decision] — Rationale: [why] ### AI Discretion [Areas where AI had flexibility and chose approach] ## Existing Code Insights ### Reusable Assets - [Component/hook/utility]: [How it could be used] ### Established Patterns - [Pattern]: [How it constrains/enables this phase] ## Specific Ideas [Any particular approaches derived from codebase analysis] ## Deferred Ideas [Ideas that came up but belong in other phases] ``` - Phase validated against roadmap - Prior context loaded and honored - Gray areas identified and resolved autonomously - CONTEXT.md captures actual decisions with rationale - Scope maintained (no creep into deferred ideas)