ralphflow 0.5.0 → 0.5.2

package/src/templates/research/loops/03-document-loop/prompt.md

@@ -12,6 +12,24 @@ Read `.ralph-flow/{{APP_NAME}}/03-document-loop/tracker.md` FIRST to determine w
 
 ---
 
+## Visual Communication Protocol
+
+When communicating scope, structure, relationships, or status, render **ASCII diagrams** using Unicode box-drawing characters. These help the user see the full picture at the terminal without scrolling through prose.
+
+**Character set:** `┌ ─ ┐ │ └ ┘ ├ ┤ ┬ ┴ ┼ ═ ● ○ ▼ ▶`
+
+**Diagram types to use:**
+
+- **Scope/Architecture Map** — components and their relationships in a bordered grid
+- **Decomposition Tree** — hierarchical breakdown with `├──` and `└──` branches
+- **Data Flow** — arrows (`──→`) showing how information moves between components
+- **Comparison Table** — bordered table for trade-offs and design options
+- **Status Summary** — bordered box with completion indicators (`✓` done, `◌` pending)
+
+**Rules:** Keep diagrams under 20 lines and under 70 characters wide. Populate with real data from current context. Render inside fenced code blocks. Use diagrams to supplement, not replace, prose.
+
+---
+
 ## STAGE 1: COMPILE
 
 1. **Read context:**
@@ -24,7 +42,8 @@ Read `.ralph-flow/{{APP_NAME}}/03-document-loop/tracker.md` FIRST to determine w
    - "What format should the final document be? (markdown/pdf/ppt/html)" with options
    - Also ask: "Any specific structure, branding, or style requirements?"
 
-3. **Plan document structure:**
+3. **Render a Document Blueprint** — output an ASCII diagram showing document sections in reading order with estimated word counts, story-to-section mapping, and appendix structure
+4. **Plan document structure:**
    - Executive summary / abstract
    - Table of contents
    - Arrange stories in logical reading order (not necessarily story-number order)
@@ -109,6 +128,28 @@ Read `.ralph-flow/{{APP_NAME}}/03-document-loop/tracker.md` FIRST to determine w
 
 ---
 
+## Decision Reporting Protocol
+
+When you make a substantive decision a human reviewer would want to know about, report it to the dashboard:
+
+**When to report:**
+- Document structure decisions (how you organized the overall narrative)
+- Story ordering choices (why stories were arranged in a particular sequence)
+- Format decisions (how you adapted content for the chosen output format)
+- Editorial choices (what to include in the executive summary, what to put in appendices)
+- Audience adaptation decisions (how you adjusted tone or depth)
+
+**How to report:**
+```bash
+curl -s --connect-timeout 2 --max-time 5 -X POST "http://127.0.0.1:4242/api/decision?app=$RALPHFLOW_APP&loop=$RALPHFLOW_LOOP" -H 'Content-Type: application/json' -d '{"item":"DOCUMENT","agent":"document-loop","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: reading files, updating tracker. Only report substantive choices that affect the final document.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
 ## Rules
 
 - This runs ONCE, on-demand. It is not a recurring loop.