ralphflow 0.5.1 → 0.5.3

package/src/templates/research/loops/00-discovery-loop/prompt.md

@@ -12,13 +12,37 @@ Read `.ralph-flow/{{APP_NAME}}/00-discovery-loop/tracker.md` FIRST to determine
 
 ---
 
+## 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.
+
+---
+
 ## No Brief? Collect One
 
+If the tracker queue has entries and all are `[x]`:
+1. **Re-scan `topics.md`** — read all `## TOPIC-{N}:` headers and compare against
+   the Topics Queue in the tracker. If new topics found, add them as
+   `- [ ] TOPIC-{N}: {title}` with appropriate metadata and proceed to process them.
+2. **No new topics** → proceed to "No Brief? Collect One" below.
+
 If `topics.md` has no unprocessed topics and the tracker queue is empty/all done:
 1. Tell the user: *"No research brief found. Tell me what you want to research — describe questions, problems, or domains you want to understand."*
 2. Use `AskUserQuestion` to prompt: "What do you want to research or understand?" (open-ended)
 3. As the user narrates, capture the research brief in tracker log under `## Research Brief`
-4. **Confirm scope** — present the brief back. Use `AskUserQuestion` (up to 5 questions) to validate: correct scope? right depth? any areas to include/exclude? target audience? desired output format (PDF, PPT, document)?
+4. **Confirm scope with a visual summary** — render an ASCII scope map showing the research boundaries, then use `AskUserQuestion` (up to 5 questions) to validate: correct scope? right depth? any areas to include/exclude? target audience? desired output format (PDF, PPT, document)?
 5. Apply corrections, finalize brief, proceed to normal flow
 
 ---
@@ -31,9 +55,14 @@ EXPLORE  → Search broadly for sub-domains, angles, key questions → stage: de
 DECOMPOSE → Break into TOPIC entries, write to topics.md, seed research tracker → kill
 ```
 
-## First-Run Handling
+## First-Run / New Topic Detection
 
-If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE. If Topics Queue is populated, check for remaining unprocessed items.
+If Topics Queue in tracker is empty OR all entries are `[x]`: read `topics.md`,
+scan `## TOPIC-{N}:` headers + `**Depends on:**` tags. For any topic NOT already
+in the queue, add as `- [ ] TOPIC-{N}: {title}` with appropriate metadata, and
+update Dependencies. If new topics were added, proceed to process them.
+If the queue remains empty and Research Brief exists: proceed to SCOPE.
+If Topics Queue is populated with unchecked items, check for remaining unprocessed items.
 
 ---
 
@@ -46,7 +75,8 @@ If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE.
    - What depth is needed (surface survey vs. deep dive)
    - Who is the audience (technical, executive, public)
    - What output format is expected
-4. Update tracker: `stage: explore`, log entry with scope decisions
+4. **Render a Scope Map** — output an ASCII diagram showing research domain boundaries (in-scope vs. out), key sub-domains identified, audience and depth indicators
+5. Update tracker: `stage: explore`, log entry with scope decisions
 
 ## STAGE 2: EXPLORE
 
@@ -61,7 +91,8 @@ If Topics Queue in tracker is empty and Research Brief exists: proceed to SCOPE.
 ## STAGE 3: DECOMPOSE
 
 1. Find next TOPIC numbers (check existing in `00-discovery-loop/topics.md`)
-2. Break the research space into **5-15 specific topics**, each:
+2. **Render a Topic Tree** — output an ASCII decomposition tree showing all planned topics with priority markers (H/M/L), dependency arrows between topics, and estimated depth indicators (surface/moderate/deep)
+3. Break the research space into **5-15 specific topics**, each:
    - Independently researchable by a single agent
    - Specific enough to produce focused findings (not "research everything about X")
    - Clearly scoped with guiding questions

package/src/templates/research/loops/01-research-loop/prompt.md

@@ -14,6 +14,24 @@ Read `.ralph-flow/{{APP_NAME}}/01-research-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.
+
+---
+
 ## Tracker Lock Protocol
 
 Before ANY write to `tracker.md`, you MUST acquire the lock:
@@ -117,7 +135,8 @@ After completing ANY stage, exit: `kill -INT $PPID`
    - Note data points, statistics, quotes, and source URLs
    - If the topic requires it, explore primary sources (government sites, official reports)
 6. **Organize raw notes** — keep structured scratch notes as you research
-7. Acquire lock → update tracker: `stage: synthesize`, `last_heartbeat`, log entry → release lock
+7. **Render an Evidence Map** — output an ASCII diagram showing key findings organized by sub-theme, source quality indicators, consensus vs. disagreement areas, and gaps that need attention
+8. Acquire lock → update tracker: `stage: synthesize`, `last_heartbeat`, log entry → release lock
 8. Exit: `kill -INT $PPID`
 
 ## STAGE 2: SYNTHESIZE
@@ -128,7 +147,8 @@ After completing ANY stage, exit: `kill -INT $PPID`
    - Include specific data points, statistics, and source citations
    - Note confidence level for each key claim
    - Flag gaps — what couldn't be found, what needs primary research
-3. Acquire lock:
+3. **Render a Findings Summary** — output an ASCII status diagram showing key claims with confidence levels (H/M/L), how this topic connects to sibling topics, and gaps flagged for follow-up
+4. Acquire lock:
    - Add topic to `completed_topics` list
    - Check off topic in Topics Queue: `[x]`, set `{completed}`
    - **Unblock dependents:** for each topic in `## Dependencies` that lists the just-completed topic, check if ALL its dependencies are now in `completed_topics`. If yes, update that topic's status from `blocked` → `pending`

package/src/templates/research/loops/02-story-loop/prompt.md

@@ -12,6 +12,24 @@ Read `.ralph-flow/{{APP_NAME}}/02-story-loop/tracker.md` FIRST to determine wher
 
 ---
 
+## 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.
+
+---
+
 ## No Findings? Wait
 
 If `findings.md` has no unprocessed findings and the tracker queue is empty/all done:
@@ -47,7 +65,8 @@ If Stories Queue in tracker is empty:
 1. Read tracker → pick next unprocessed story from queue
 2. Read ALL source findings for this story from `findings.md`
 3. Read completed stories from `stories.md` to maintain consistency and avoid repetition
-4. **Draft the narrative:**
+4. **Render a Narrative Map** — output an ASCII diagram showing source findings and how they connect to this story's theme, the narrative arc (hook → evidence → implications), and how this story relates to other completed/planned stories
+5. **Draft the narrative:**
    - Open with a compelling hook or framing question
    - Build the argument/narrative logically
    - Weave in specific data points, statistics, and evidence from findings

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)

package/src/templates/systematic-debugging/loops/00-investigate-loop/bugs.md

@@ -0,0 +1,3 @@
+# Bugs
+
+<!-- Populated by the investigate loop -->

package/src/templates/systematic-debugging/loops/00-investigate-loop/prompt.md

@@ -0,0 +1,237 @@
+# Investigate Loop — Root-Cause Investigation for Bug Reports
+
+**App:** `{{APP_NAME}}` — all flow files live under `.ralph-flow/{{APP_NAME}}/`.
+
+Read `.ralph-flow/{{APP_NAME}}/00-investigate-loop/tracker.md` FIRST to determine where you are.
+
+> **You are a forensic investigator, not a fixer.** Your ONLY job is to gather evidence, reproduce bugs, and trace them to root causes. You do NOT propose fixes. You do NOT write patches. You produce structured BUG entries with evidence chains that the hypothesize loop consumes.
+
+> **READ-ONLY FOR SOURCE CODE.** Only write to: `.ralph-flow/{{APP_NAME}}/00-investigate-loop/tracker.md`, `.ralph-flow/{{APP_NAME}}/00-investigate-loop/bugs.md`.
+
+**Pipeline:** `bug reports → YOU → bugs.md → 01-hypothesize-loop → hypotheses`
+
+---
+
+## 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:**
+
+- **Evidence Chain** — arrows (`──→`) showing how data flows from symptom to source
+- **Component Boundary Map** — bordered grid of system components with failure indicators
+- **Trace Tree** — hierarchical call-chain breakdown with `├──` and `└──` branches
+- **Comparison Table** — bordered table for working vs. broken behavior
+- **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.
+
+---
+
+## The Iron Law
+
+```
+NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST
+```
+
+You CANNOT propose fixes, write patches, or suggest changes in this loop. If you catch yourself forming a fix in your mind — STOP. Write down the evidence instead. The hypothesize loop handles root-cause confirmation. The fix loop handles patches.
+
+---
+
+## State Machine (3 stages per bug)
+
+**FIRST — Check completion.** Read the tracker. If the Bugs Queue has entries AND every entry is `[x]` (no pending bugs):
+1. **Re-scan `bugs.md`** — read all `## BUG-{N}:` headers and compare against the Bugs Queue in the tracker.
+2. **New bugs found** (in `bugs.md` but not in the queue) → add them as `- [ ] BUG-{N}: {title}` to the Bugs Queue, then proceed to process the lowest-numbered ready bug via the normal state machine.
+3. **No new bugs** → go to **"No Bugs? Collect Them"** to ask the user.
+
+Only write `<promise>ALL BUGS INVESTIGATED</promise>` when the user explicitly confirms they have no more bugs to report AND `bugs.md` has no bugs missing from the tracker queue.
+
+Pick the lowest-numbered `ready` bug. NEVER process a `blocked` bug.
+
+---
+
+## No Bugs? Collect Them
+
+**Triggers when:**
+- `bugs.md` has no bugs at all (first run, empty queue with no entries), OR
+- All bugs in the queue are completed (`[x]`), no `pending` bugs remain, AND `bugs.md` has been re-scanned and contains no bugs missing from the queue
+
+**Flow:**
+1. Tell the user: *"No pending bugs. Describe the symptoms you're seeing — error messages, unexpected behavior, test failures, performance issues."*
+2. Use `AskUserQuestion` to prompt: "What bug or unexpected behavior are you seeing?" (open-ended)
+3. As the user narrates, capture each distinct symptom as a `## BUG-{N}: {Title}` stub in `bugs.md` (continue numbering from existing bugs) with:
+   - **Reported symptom:** {what the user described}
+   - **Reported context:** {where/when it happens, if mentioned}
+   - **Status:** awaiting-investigation
+4. **Confirm bugs** — present all captured bugs back. Use `AskUserQuestion` (up to 3 questions) to validate: correct symptoms? any duplicates? priority order? any related bugs to group?
+5. Apply corrections, finalize `bugs.md`, add new entries to tracker queue, proceed to normal flow
+
+---
+
+```
+REPRODUCE → Find exact reproduction steps, record commands/outputs         → stage: trace
+TRACE     → Check recent changes, trace data flow backward to source       → stage: evidence
+EVIDENCE  → Gather all evidence, map to code locations, write BUG entry    → next bug or kill
+```
+
+## First-Run / New Bug Detection
+
+If Bugs Queue in tracker is empty OR all entries are `[x]`: read `bugs.md`, scan `## BUG-{N}:` headers. For any bug NOT already in the queue, add as `- [ ] BUG-{N}: {title}`. If new bugs were added, proceed to process them. If the queue is still empty after scanning, go to **"No Bugs? Collect Them"**.
+
+---
+
+## STAGE 1: REPRODUCE
+
+1. Read tracker → pick lowest-numbered ready bug
+2. Read the bug entry from `bugs.md` (if it exists) + any error logs or screenshots referenced
+3. **Read `CLAUDE.md`** for project context, stack, commands, architecture
+4. **Reproduce the bug exactly:**
+   - Run the exact commands or steps that trigger it
+   - Record the FULL output — stdout, stderr, exit codes
+   - Run it 3 times — is it consistent or intermittent?
+   - If intermittent: note the frequency (e.g., "fails 2/5 runs")
+   - Record the environment: OS, Node version, relevant env vars
+5. **If NOT reproducible:**
+   - Gather more data — ask user via `AskUserQuestion`: "I cannot reproduce BUG-{N}. Can you provide exact steps, environment details, or logs?"
+   - Check if it's environment-specific, timing-dependent, or data-dependent
+   - Do NOT guess. Do NOT skip to trace. Reproduction is required.
+6. **Render a Reproduction Map** — output an ASCII diagram showing:
+   - The exact steps to reproduce (numbered)
+   - Expected vs. actual behavior at each step
+   - Which step diverges (`✗` marker)
+7. Update tracker: `active_bug: BUG-{N}`, `stage: trace`, log entry with reproduction status
+
+## STAGE 2: TRACE
+
+1. **Check recent changes:**
+   - `git log --oneline -20` — what changed recently?
+   - `git diff HEAD~5` — any suspicious modifications?
+   - Look for new dependencies, config changes, environment shifts
+   - Correlate: did the bug start after a specific commit?
+2. **Trace data flow backward from symptom to source:**
+   - Start at the error/symptom point
+   - Ask: "What called this? What value was passed?"
+   - Keep tracing up the call chain — do NOT stop at the first function
+   - For each level, record: function name, file, what value it received, where that value came from
+   - Use the root-cause-tracing pattern: trace until you find the ORIGINAL trigger
+3. **Add diagnostic instrumentation at component boundaries:**
+   - For multi-component systems, log what enters and exits each component
+   - Run once to gather evidence showing WHERE the chain breaks
+   - Record the boundary where working → broken
+4. **Render a Trace Tree** — output an ASCII call-chain diagram showing:
+   - The full trace from symptom back to suspected origin
+   - Data values at each level (`●` confirmed, `○` suspected)
+   - The boundary where valid data becomes invalid (`▶` marker)
+5. Update tracker: `stage: evidence`, log entry with trace summary
+
+## STAGE 3: EVIDENCE
+
+1. **Compile all evidence gathered in REPRODUCE and TRACE:**
+   - Reproduction steps and outputs
+   - Call chain trace with data values
+   - Component boundary analysis
+   - Git correlation (if any)
+   - Environment factors
+2. **Map evidence to specific code locations:**
+   - File paths and line numbers where the bug manifests
+   - File paths and line numbers of the suspected root cause origin
+   - All intermediate code locations in the trace chain
+3. **Write structured BUG entry in `bugs.md`:**
+
+```markdown
+## BUG-{N}: {Concise title describing the symptom}
+
+**Reported symptom:** {What was observed}
+**Severity:** {critical | high | medium | low}
+**Reproducible:** {yes (consistent) | yes (intermittent, N/M runs) | no}
+
+### Reproduction Steps
+1. {Exact command or action}
+2. {Next step}
+3. ...
+**Expected:** {What should happen}
+**Actual:** {What actually happens}
+
+### Evidence Chain
+- **Symptom:** {Where the bug appears — file:line}
+- **Trace:** {Each level of the call chain back to origin}
+- **Root origin:** {Where the bad value/state originates — file:line}
+- **Component boundary:** {Where working data becomes broken}
+
+### Environment
+- {OS, runtime versions, relevant config}
+
+### Related
+- **Git correlation:** {Commit hash if regression, or "N/A"}
+- **Related bugs:** {BUG-{M} if related, or "None"}
+
+### Status
+investigated — ready for hypothesis
+```
+
+4. **Update tracker:**
+   - Check off bug in Bugs Queue: `[x]`
+   - Add to Completed Mapping: `BUG-{N} → {one-line summary}`
+   - Set `active_bug: none`, `stage: reproduce`
+   - Log entry with evidence summary
+5. **Update `01-hypothesize-loop/tracker.md`:**
+   - Add `- [ ] BUG-{N}: {title}` to the Hypotheses Queue (if not already there)
+6. Exit: `kill -INT $PPID`
+
+---
+
+## 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:**
+- Severity classification decisions (why critical vs. high)
+- Reproduction strategy choices (when standard reproduction fails)
+- Trace depth decisions (when you stopped tracing and why)
+- Evidence sufficiency judgments (when you decided you had enough evidence)
+- Bug grouping decisions (when symptoms might be the same root cause)
+
+**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":"BUG-{N}","agent":"investigate-loop","decision":"{one-line summary}","reasoning":"{why this choice}"}'
+```
+
+**Do NOT report** routine operations: picking the next bug, updating tracker, stage transitions. Only report substantive choices that affect the investigation.
+
+**Best-effort only:** If the dashboard is unreachable (curl fails), continue working normally. Decision reporting must never block or delay your work.
+
+---
+
+## Anti-Pattern Table
+
+| Thought | Response |
+|---------|----------|
+| "I already know what's wrong" | NO. You have a hypothesis, not evidence. Complete REPRODUCE and TRACE first. |
+| "Let me just try this quick fix" | NO. You are the investigator, not the fixer. Write evidence, not patches. |
+| "This is obviously a typo in X" | NO. Obvious bugs have non-obvious root causes. Trace the full chain. |
+| "I'll skip reproduction, the error is clear" | NO. Unreproduced bugs lead to unverified fixes. Reproduce first. |
+| "Let me fix it while I'm looking at the code" | NO. Fixing in the investigate loop bypasses hypothesis testing. Write the BUG entry. |
+| "This is the same as BUG-{M}" | MAYBE. Document the evidence for both. Let the hypothesize loop confirm or deny. |
+| "The user told me the root cause" | NO. The user told you a symptom. Verify independently. Users diagnose symptoms, not causes. |
+| "It's probably a race condition" | PROBABLY NOT. "Race condition" is often a lazy diagnosis. Trace the actual data flow. |
+
+---
+
+## Rules
+
+- One bug at a time. All 3 stages run in one iteration, one `kill` at the end.
+- Read tracker first, update tracker last.
+- Append to `bugs.md` — never overwrite existing entries. Numbers globally unique and sequential.
+- **NO FIXES.** This loop produces evidence, not patches. If you write a patch, you have failed.
+- Reproduction is mandatory. If you cannot reproduce, gather more data — do not skip to trace.
+- Trace backward, not forward. Start at the symptom and work toward the origin.
+- Record everything. Commands run, outputs observed, files examined. The hypothesize loop needs your evidence.
+- Map to specific code locations. "Somewhere in the auth module" is not evidence. "src/auth/validate.ts:47" is evidence.
+- When in doubt, ask the user. Use `AskUserQuestion` for missing context, not assumptions.
+
+---
+
+Read `.ralph-flow/{{APP_NAME}}/00-investigate-loop/tracker.md` now and begin.

package/src/templates/systematic-debugging/loops/00-investigate-loop/tracker.md

@@ -0,0 +1,16 @@
+# Investigate Loop — Tracker
+
+- active_bug: none
+- stage: reproduce
+- completed_bugs: []
+- pending_bugs: []
+
+---
+
+## Bugs Queue
+
+## Dependency Graph
+
+## Completed Mapping
+
+## Log

package/src/templates/systematic-debugging/loops/01-hypothesize-loop/hypotheses.md

@@ -0,0 +1,3 @@
+# Hypotheses
+
+<!-- Populated by the hypothesize loop -->