{# ============================================================================ #}
{# Template: planning_xml.txt #}
{# Version: 3.0 - Dumb-agent-proof planning with rich guidance #}
{# ============================================================================ #}
{# #}
{# PURPOSE: #}
{# Prompt for planning phase to create detailed implementation plans. #}
{# Uses structured XML with rich content elements for comprehensive plans. #}
{# Provides explicit guidance to make plans executable by weak agents. #}
{# #}
{# VARIABLES: #}
{# {{PROMPT}} - User requirements from the request (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}}
{{> shared/_no_git_commit}}
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}}`.
- Only writable file: `{{PLAN_XML_PATH}}`
- Writing this XML file is mandatory and must conform to `{{PLAN_XSD_PATH}}`
- Writing the XML file is MANDATORY. Not writing it is a FAILURE.
- XML that does not conform to the XSD schema is a FAILURE.
- No other files may be created/modified/deleted
- Allowed operations: any non-mutating tools (for example file reads/search/listing and image analysis)
═══════════════════════════════════════════════════════════════════════════════
PLANNING CONSTRAINTS (ANTI-RUNAWAY POLICY - PROGRESS-BASED)
═══════════════════════════════════════════════════════════════════════════════
Track these control signals while planning:
- required_sections = [objective, scope, steps, risks, verification]
- unresolved_unknowns (max 3)
- stagnation_count (increment when no materially new info is found)
Progress-based rules:
1. Exploration is allowed only while it increases section coverage or resolves unknowns.
2. If stagnation_count reaches 2, stop exploration and start drafting.
3. If unresolved_unknowns > 3, stop exploration and convert extras into explicit investigation steps.
4. After drafting, run one critique pass.
5. Critique may request at most one targeted re-exploration pass.
6. Then finalize plan; no further exploration allowed.
Additional guardrails:
- Resolve unknowns during planning before finalizing whenever feasible.
- If investigation is large or spans independent areas, split work into parallel investigation tracks.
- Use subagents when parallel investigation is appropriate, and map each output to an explicit plan update.
- Consolidate and synthesize parallel findings before finalizing.
- If findings are inconsistent, run targeted follow-up investigation or record explicit unresolved risks.
- If investigation yields a clear picture, convert it into actionable implementation tasks, not additional placeholders.
- When open questions or unknowns cannot be resolved immediately, convert them into explicit investigation/research steps with question, why it blocks, and expected evidence.
═══════════════════════════════════════════════════════════════════════════════
PHASE 1: UNDERSTANDING
═══════════════════════════════════════════════════════════════════════════════
USER REQUIREMENTS:
{{PROMPT}}
Extract only what is needed:
- Goal (objective)
- Acceptance criteria and definition of done
- Constraints
- In-scope vs out-of-scope
- Assumptions and open questions
If requirements are ambiguous, note the ambiguity explicitly in the plan.
═══════════════════════════════════════════════════════════════════════════════
PHASE 2: EXPLORATION
═══════════════════════════════════════════════════════════════════════════════
Gather only sufficient context for implementation:
- likely files to change
- existing patterns to follow
- key dependencies and tests
Avoid exhaustive exploration. Favor signal over completeness.
═══════════════════════════════════════════════════════════════════════════════
PHASE 3: DESIGN
═══════════════════════════════════════════════════════════════════════════════
Design a practical implementation path:
- ordered steps with dependencies
- explicit inputs and expected outputs per step
- verification method per step
- which steps can run in parallel vs must stay sequential
- key trade-off notes (brief)
- risks and mitigations (brief)
Choose a complete solution that fixes the problem at the root cause. Do not plan surface-level fixes or partial implementations.
═══════════════════════════════════════════════════════════════════════════════
PHASE 4: REVIEW
═══════════════════════════════════════════════════════════════════════════════
Quick validation before output:
- all acceptance criteria covered
- target files are specific
- steps are actionable and sequenced
- each step has clear completion evidence
- scope is not expanded
- unresolved unknowns are explicit and bounded
- handoff is executable by an agent with zero prior context
═══════════════════════════════════════════════════════════════════════════════
PHASE 5: WRITE STRUCTURED PLAN
═══════════════════════════════════════════════════════════════════════════════
Write XML to: `{{PLAN_XML_PATH}}`
XSD schema: `{{PLAN_XSD_PATH}}`
═══════════════════════════════════════════════════════════════════════════════
REQUIRED SECTIONS (All sections are REQUIRED unless marked optional)
═══════════════════════════════════════════════════════════════════════════════
1. **ralph-summary** (REQUIRED)
- MUST have <context> (non-empty) explaining what and why
- MUST have <scope-items> with minimum 3 items
- Each scope-item describes work category with count and description
2. **ralph-implementation-steps** (REQUIRED)
- Each <step> MUST have: number attribute, <title>, <content>
- file-change steps MUST have <target-files> with at least one <file path="..." action="..."/>
- <content> MUST have at least one element: <paragraph>, <code-block>, <list>, etc.
3. **ralph-critical-files** (REQUIRED)
- MUST have <primary-files> with at least one <file path="..." action="..."/>
- <reference-files> section is optional but recommended
4. **ralph-risks-mitigations** (REQUIRED - minimum 1 risk-pair)
- Each <risk-pair> MUST have both <risk> and <mitigation>
5. **ralph-verification-strategy** (REQUIRED - minimum 1 verification)
- Each <verification> MUST have both <method> and <expected-outcome>
═══════════════════════════════════════════════════════════════════════════════
IMPLEMENTATION CONTEXT REQUIREMENTS
═══════════════════════════════════════════════════════════════════════════════
For each implementation step, provide:
- **Concrete target files/areas**: Specific file paths and locations
- **Ordered steps with dependencies**: Numbered steps in execution order
- **Risk + mitigation pairs**: For each significant decision
- **Verification strategy**: How to verify the step succeeded
- **Clear boundaries**: What is in-scope vs out-of-scope
The plan must be detailed enough that a developer agent with zero prior context
can execute it without guessing.
═══════════════════════════════════════════════════════════════════════════════
PRE-SUBMISSION CHECKLIST
═══════════════════════════════════════════════════════════════════════════════
Before writing the XML, verify:
[ ] All required sections are present
[ ] All minimum counts are met (3 scope-items, 1 risk-pair, 1 verification)
[ ] All steps have required attributes and elements
[ ] All file paths are specific and correct
[ ] All element content is non-empty
[ ] XML is well-formed (proper closing tags, valid structure)
[ ] No markdown fences around XML
═══════════════════════════════════════════════════════════════════════════════
SKILLS AND MCP GUIDANCE
═══════════════════════════════════════════════════════════════════════════════
Add all relevant skills and MCP suggestions to `<skills-mcp>`. Look through
available skills before writing the XML. Consider whether any MCP or
MCP-backed system should also be suggested. Use `<skill>` and `<mcp>` entries,
and add `reason=""` when helpful. Keep recommendations grounded in the actual
task. Do not assume the consumer is a developer or fixer.
═══════════════════════════════════════════════════════════════════════════════
ANNOTATED EXAMPLE (Replace all content with your actual plan values)
═══════════════════════════════════════════════════════════════════════════════
<!-- This example shows what "good" looks like for each field type -->
<ralph-plan>
<ralph-summary>
<!-- context: one paragraph explaining what and why; be specific -->
<context>Adding AUTHORIZATION OVERRIDE blocks to XSD retry templates so weak agents
know they are permitted to write the output file during a format-only fix pass.</context>
<!-- scope-items: minimum 3; use count= for quantity, category= for type -->
<scope-items>
<scope-item count="4" category="template-modifications">Modify four XSD retry templates to add AUTHORIZATION OVERRIDE section</scope-item>
<scope-item count="1" category="regression-test">Add status contract regression test to prevent "completed" from being dropped</scope-item>
<scope-item count="1" category="documentation">Update template version headers to v6.0</scope-item>
</scope-items>
</ralph-summary>
<skills-mcp>
<!-- Add relevant skills/MCPs; remove this block if none apply -->
<skill reason="Write failing test first per TDD mandate">test-driven-development</skill>
</skills-mcp>
<ralph-implementation-steps>
<!-- Each step needs: number, type, priority, title, target-files (if file-change), content -->
<step number="1" type="file-change" priority="high">
<title>Add AUTHORIZATION OVERRIDE to developer_iteration_xsd_retry.txt</title>
<target-files>
<!-- action must be create, modify, or delete -->
<file path="ralph-workflow/src/prompts/templates/developer_iteration_xsd_retry.txt" action="modify"/>
</target-files>
<!-- location: WHERE in the file to make the change -->
<location>After the CRITICAL INSTRUCTIONS section, before the DO NOT DO section</location>
<!-- rationale: WHY this step is needed -->
<rationale>v5.0 lacks AUTHORIZATION OVERRIDE so agent scope is ambiguous</rationale>
<!-- content: WHAT to do; use paragraph/list/code-block elements -->
<content>
<paragraph>Insert the AUTHORIZATION OVERRIDE block from planning_xsd_retry.txt v6.0, adapting the file path variable to the correct template variable for this phase.</paragraph>
<list type="ordered">
<item>Copy AUTHORIZATION OVERRIDE block verbatim from planning_xsd_retry.txt</item>
<item>Replace PLAN_XML_PATH with the correct variable for this phase (e.g., DEVELOPMENT_RESULT_XML_PATH, ISSUES_XML_PATH, etc.)</item>
<item>Update version header comment to v6.0</item>
</list>
</content>
</step>
<!-- Additional steps follow same pattern -->
</ralph-implementation-steps>
<ralph-critical-files>
<primary-files>
<!-- estimated-changes: rough change size hint -->
<file path="ralph-workflow/src/prompts/templates/developer_iteration_xsd_retry.txt" action="modify" estimated-changes="add ~15 lines AUTHORIZATION OVERRIDE block"/>
</primary-files>
<reference-files>
<!-- purpose: why this file is referenced, not changed -->
<file path="ralph-workflow/src/prompts/templates/planning_xsd_retry.txt" purpose="Source of v6.0 AUTHORIZATION OVERRIDE block to copy"/>
</reference-files>
</ralph-critical-files>
<ralph-risks-mitigations>
<!-- severity: low, medium, high, or critical -->
<risk-pair severity="medium">
<risk>Template variable names differ between phases, causing copy-paste errors when copying AUTHORIZATION OVERRIDE blocks</risk>
<mitigation>Verify each template's variable names against the template header comment before copying blocks; run cargo build to catch any Tera template errors</mitigation>
</risk-pair>
</ralph-risks-mitigations>
<ralph-verification-strategy>
<verification>
<method>Run cargo test -p ralph-workflow to ensure no template rendering regressions</method>
<expected-outcome>All tests pass; no ERROR/WARNING in output</expected-outcome>
</verification>
</ralph-verification-strategy>
</ralph-plan>
═══════════════════════════════════════════════════════════════════════════════
MINIMUM XML SKELETON (must be valid per XSD)
═══════════════════════════════════════════════════════════════════════════════
<ralph-plan>
<ralph-summary>...</ralph-summary>
<skills-mcp>
<skill reason="Implementation should start with failing tests">test-driven-development</skill>
<mcp reason="Use for dependency and library research">context7</mcp>
</skills-mcp>
<ralph-implementation-steps>...</ralph-implementation-steps>
<ralph-critical-files>...</ralph-critical-files>
<ralph-risks-mitigations>...</ralph-risks-mitigations>
<ralph-verification-strategy>...</ralph-verification-strategy>
</ralph-plan>
XML rules:
- Start with `<ralph-plan>` and end with `</ralph-plan>`
- No markdown fences
- Escape inline XML chars or use CDATA in code-blocks
Output only valid XML content to `{{PLAN_XML_PATH}}`.