{# ============================================================================ #}
{# Template: planning_xml.txt                                                  #}
{# Version: 2.0 - Structured XML with rich content elements                    #}
{# ============================================================================ #}
{#                                                                             #}
{# PURPOSE:                                                                    #}
{#   Prompt for planning phase to create detailed implementation plans.        #}
{#   Uses structured XML with rich content elements for comprehensive plans.   #}
{#                                                                             #}
{# VARIABLES:                                                                  #}
{#   {{PROMPT}} - User requirements from PROMPT.md (required)                  #}
{#                                                                             #}
{# OUTPUT FORMAT:                                                              #}
{#   <ralph-plan>                                                              #}
{#     <ralph-summary>                                                         #}
{#       <context>What is being done and why</context>                         #}
{#       <scope-items>                                                         #}
{#         <scope-item count="N" category="X">Description</scope-item> (min 3) #}
{#       </scope-items>                                                        #}
{#     </ralph-summary>                                                        #}
{#     <ralph-implementation-steps>                                            #}
{#       <step number="1" type="file-change" priority="high">                  #}
{#         <title>Step title</title>                                           #}
{#         <target-files><file path="..." action="modify"/></target-files>     #}
{#         <location>Where in file</location>                                  #}
{#         <content>Rich content with tables, code-blocks, lists</content>     #}
{#       </step>                                                               #}
{#     </ralph-implementation-steps>                                           #}
{#     <ralph-critical-files>                                                  #}
{#       <primary-files><file path="..." action="modify"/></primary-files>     #}
{#       <reference-files><file path="..." purpose="..."/></reference-files>   #}
{#     </ralph-critical-files>                                                 #}
{#     <ralph-risks-mitigations>                                               #}
{#       <risk-pair severity="medium">                                         #}
{#         <risk>Risk description</risk>                                       #}
{#         <mitigation>How to mitigate</mitigation>                            #}
{#       </risk-pair>                                                          #}
{#     </ralph-risks-mitigations>                                              #}
{#     <ralph-verification-strategy>                                           #}
{#       <verification>                                                        #}
{#         <method>How to verify</method>                                      #}
{#         <expected-outcome>What success looks like</expected-outcome>        #}
{#       </verification>                                                       #}
{#     </ralph-verification-strategy>                                          #}
{#   </ralph-plan>                                                             #}
{# ============================================================================ #}

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

{{> shared/_unattended_mode}}

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

## AUTHORIZATION OVERRIDE (CRITICAL)

You are explicitly authorized to write EXACTLY ONE file:
- `{{PLAN_XML_PATH}}`

Writing the XML file is MANDATORY.
This OVERRIDES the safety mode restrictions only.
It does NOT override the task requirements (you must still create a correct plan and follow the XSD).

This is a READ-ONLY task EXCEPT FOR writing `{{PLAN_XML_PATH}}`.
You MUST NOT create, modify, or delete any other files.

Not writing the XML file is a FAILURE.
Writing XML that does not conform to the XSD schema is a FAILURE.

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.

═══════════════════════════════════════════════════════════════════════════════
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 STRUCTURED PLAN
═══════════════════════════════════════════════════════════════════════════════

Write your XML to: `{{PLAN_XML_PATH}}`
XSD schema at: `{{PLAN_XSD_PATH}}`

CRITICAL XML ESCAPING RULES:
1. For inline code with special characters (<, >, &), use: <code>a &lt; b</code>
2. For code blocks, ALWAYS use CDATA to avoid escaping issues:
   <code-block language="rust"><![CDATA[
   if a < b && c > d {
       vec.push(item);
   }
   ]]></code-block>
3. CDATA sections preserve content exactly - no escaping needed inside them.
4. If you see XML parsing errors about code-block, you forgot to use CDATA.

ALL SECTIONS ARE REQUIRED:
- ralph-summary (with context and at least 3 scope-items)
- ralph-implementation-steps (with numbered steps)
- ralph-critical-files (with primary-files)
- ralph-risks-mitigations (with at least 1 risk-pair)
- ralph-verification-strategy (with at least 1 verification)

───────────────────────────────────────────────────────────────────────────────
XML STRUCTURE REFERENCE
───────────────────────────────────────────────────────────────────────────────

RICH CONTENT ELEMENTS (use inside <content>):
- <paragraph>Text with optional <emphasis>bold</emphasis> and <code>inline</code></paragraph>
- <code-block language="rust" filename="file.rs">code here</code-block>
- <heading level="3">Section Title</heading>
- <list type="ordered|unordered"><item>Item text</item></list>
- <table>
    <caption>Table title</caption>
    <columns><column>Col1</column><column>Col2</column></columns>
    <row><cell>Value1</cell><cell>Value2</cell></row>
  </table>

STEP TYPES:
- type="file-change" (default): Modifies files. Requires <target-files> and <location>.
- type="action": Setup/config tasks (e.g., "Set up test environment"). No file required.
- type="research": Investigation tasks (e.g., "Research API requirements"). No file required.

STEP PRIORITIES: critical, high, medium, low

FILE ACTIONS: create, modify, delete

───────────────────────────────────────────────────────────────────────────────
EXAMPLE PLAN
───────────────────────────────────────────────────────────────────────────────

<ralph-plan>
<ralph-summary>
<context>
Enhance the user authentication system by adding OAuth2 support for Google and GitHub
providers, enabling users to sign in with their existing accounts.
</context>
<scope-items>
<scope-item count="3" category="auth">OAuth2 provider integrations</scope-item>
<scope-item count="5" category="api">new API endpoints for OAuth flow</scope-item>
<scope-item count="2" category="ui">login button components</scope-item>
<scope-item count="8" category="tests">integration and unit tests</scope-item>
</scope-items>
</ralph-summary>

<ralph-implementation-steps>
<step number="1" type="file-change" priority="high">
<title>Add OAuth2 configuration types</title>
<target-files>
<file path="src/config/oauth.rs" action="create"/>
<file path="src/config/mod.rs" action="modify"/>
</target-files>
<location>Create new file; add mod declaration to mod.rs</location>
<rationale>Configuration must be in place before implementing providers</rationale>
<content>
<paragraph>Create OAuth2 configuration structures:</paragraph>
<code-block language="rust" filename="src/config/oauth.rs"><![CDATA[
#[derive(Debug, Clone, Deserialize)]
pub struct OAuth2Config {
    pub google: Option<ProviderConfig>,
    pub github: Option<ProviderConfig>,
}
]]></code-block>
</content>
</step>

<step number="2" type="research" priority="medium">
<title>Research OAuth2 library options</title>
<content>
<paragraph>Evaluate available OAuth2 libraries for Rust:</paragraph>
<table>
<caption>OAuth2 Library Comparison</caption>
<columns>
<column>Library</column>
<column>Pros</column>
<column>Cons</column>
</columns>
<row>
<cell>oauth2</cell>
<cell>Official, well-maintained</cell>
<cell>Verbose API</cell>
</row>
</table>
</content>
<depends-on step="1"/>
</step>

<step number="3" type="action" priority="high">
<title>Configure test environment</title>
<content>
<paragraph>Set up test OAuth credentials:</paragraph>
<list type="ordered">
<item>Create Google Cloud project and OAuth credentials</item>
<item>Create GitHub OAuth App in developer settings</item>
<item>Add credentials to <code>.env.test</code></item>
</list>
</content>
</step>
</ralph-implementation-steps>

<ralph-critical-files>
<primary-files>
<file path="src/config/oauth.rs" action="create" estimated-changes="~50 lines"/>
<file path="src/auth/oauth2.rs" action="create" estimated-changes="~200 lines"/>
</primary-files>
<reference-files>
<file path="src/auth/mod.rs" purpose="Existing auth patterns"/>
</reference-files>
</ralph-critical-files>

<ralph-risks-mitigations>
<risk-pair severity="high">
<risk>OAuth tokens could be intercepted if not handled securely</risk>
<mitigation>Use HTTPS only, store tokens encrypted, implement PKCE flow</mitigation>
</risk-pair>
</ralph-risks-mitigations>

<ralph-verification-strategy>
<verification>
<method>Run integration tests against test OAuth credentials</method>
<expected-outcome>All OAuth flows complete successfully with valid tokens</expected-outcome>
</verification>
</ralph-verification-strategy>
</ralph-plan>

Be as detailed as the task requires - complex tasks need comprehensive plans.
