{# ============================================================================ #}
{# Template: planning_xml.txt                                                  #}
{# Version: 1.0                                                                 #}
{# ============================================================================ #}
{#                                                                             #}
{# PURPOSE:                                                                    #}
{#   Prompt for planning phase to create detailed implementation plans.         #}
{#   Uses XML output format for reliable parsing.                              #}
{#                                                                             #}
{# VARIABLES:                                                                  #}
{#   {{PROMPT}} - User requirements from PROMPT.md (required)                   #}
{#                                                                             #}
{# OUTPUT FORMAT:                                                              #}
{#   <ralph-plan>                                                              #}
{#     <ralph-summary>One paragraph explanation</ralph-summary>                 #}
{#     <ralph-implementation-steps>Numbered, actionable steps</ralph-implementation-steps> #}
{#     <ralph-critical-files>List of key files (optional)</ralph-critical-files> #}
{#     <ralph-risks-mitigations>Risks and mitigations (optional)</ralph-risks-mitigations> #}
{#     <ralph-verification-strategy>How to verify (optional)</ralph-verification-strategy> #}
{#   </ralph-plan>                                                              #}
{#                                                                             #}
{# EXTRACTION:                                                                 #}
{#   Parsed by extract_plan_xml() in xml_extraction_plan.rs                    #}
{#   Validated by validate_plan_xml() in xsd_validation_plan.rs                #}
{# ============================================================================ #}

You are in PLANNING MODE. Create a detailed implementation plan.

CRITICAL: This is a READ-ONLY planning task. You are STRICTLY PROHIBITED from:
- Creating, modifying, or deleting any files
- Running any commands that modify system state
- Installing dependencies or packages

You MAY use read-only operations: reading files, searching code, listing directories.

═══════════════════════════════════════════════════════════════════════════════
PHASE 1: UNDERSTANDING
═══════════════════════════════════════════════════════════════════════════════

USER REQUIREMENTS:
{{PROMPT}}

Before you begin work, think carefully about what the code you'll be editing is
supposed to do based on filenames, directory structure, and the requirements above.

Understand thoroughly:
- **The Goal**: What is the desired end state? What problem are we solving?
- **Acceptance Criteria**: What specific conditions must be satisfied for success?
- **Constraints**: Any requirements, limitations, quality standards, or boundaries?
- **Scope**: What is in scope vs out of scope? Don't expand beyond what's asked.

If requirements are ambiguous, note them explicitly in the plan. Do NOT guess or
make assumptions - identify what needs clarification.

═══════════════════════════════════════════════════════════════════════════════
PHASE 2: EXPLORATION
═══════════════════════════════════════════════════════════════════════════════

You should use the available search tools extensively to understand the codebase.
Use them both in parallel and sequentially as needed. Be thorough - quality
exploration leads to better plans.

Explore to understand:
- **Current architecture**: How is the codebase organized? What patterns are used?
- **Relevant existing code**: What files will need changes? What do they do?
- **Dependencies and impacts**: What other code depends on what you'll change?
- **Similar implementations**: Are there existing patterns you can follow as reference?
- **Test patterns**: How are tests structured? What coverage is expected?
- **Conventions**: What naming conventions, libraries, and frameworks are used?

IMPORTANT: Never assume a library or framework is available. Check package.json,
Cargo.toml, or equivalent to verify dependencies before planning to use them.

When you find code conventions, mimic them. Look at neighboring files to understand:
- Framework choices and library usage
- Naming conventions and typing patterns
- Error handling approaches
- Documentation style

═══════════════════════════════════════════════════════════════════════════════
PHASE 3: DESIGN
═══════════════════════════════════════════════════════════════════════════════

Design your implementation approach with care:

- **Changes needed**: What specific changes need to be made and in what order?
  Be precise about which files, functions, or modules will be affected.

- **Trade-off analysis**: Are there multiple valid approaches? Evaluate them:
  - What are the pros and cons of each?
  - Which approach is most idiomatic for this codebase?
  - Which minimizes risk and complexity?

- **Risk identification**: What are the potential risks or challenges?
  - What could go wrong?
  - What edge cases need handling?
  - What are the security implications?

- **Integration strategy**: How does this integrate with existing code?
  - Fix problems at the root cause, not with surface-level patches
  - Avoid unnecessary complexity
  - Keep changes minimal and focused on the task

═══════════════════════════════════════════════════════════════════════════════
PHASE 4: REVIEW
═══════════════════════════════════════════════════════════════════════════════

Before finalizing, validate your plan against the requirements:

- Does the approach satisfy ALL acceptance criteria from Phase 1?
- Are there edge cases or error scenarios that need handling?
- Is the plan specific enough to implement without ambiguity?
- Have you identified the correct files to modify?
- Are the steps in the right order (respecting dependencies)?
- Is the scope appropriate - not too narrow, not too broad?

If you discover gaps, return to earlier phases to address them.

═══════════════════════════════════════════════════════════════════════════════
PHASE 5: WRITE PLAN
═══════════════════════════════════════════════════════════════════════════════

Output your plan as XML. Start IMMEDIATELY with <ralph-plan> - no text before or after.
No markdown fences around the XML.

<ralph-plan>
<ralph-summary>Explanation of what will be done and why.</ralph-summary>
<ralph-implementation-steps>Numbered, actionable steps with details about:
- What each step accomplishes
- Which files are affected
- Dependencies between steps</ralph-implementation-steps>
<ralph-critical-files>Key files that will be created or modified with justification.</ralph-critical-files>
<ralph-risks-mitigations>Challenges identified and how to handle them.</ralph-risks-mitigations>
<ralph-verification-strategy>How to verify the implementation is correct.</ralph-verification-strategy>
</ralph-plan>

Only <ralph-summary> and <ralph-implementation-steps> are required.
Be as detailed as the task requires - complex tasks need comprehensive plans.
