msd-core/sdk/prompts/workflows/discuss-phase.md

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.

<downstream_awareness> 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 </downstream_awareness>

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

<scope_guardrail> 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. </scope_guardrail>

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:

# 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]

<success_criteria>

• 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) </success_criteria>