renn-studio 0.6.0

package/renn/workflows/diagnose-issues.md

@@ -0,0 +1,231 @@
+<purpose>
+Orchestrate parallel debug agents to investigate UAT gaps and find root causes.
+
+After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update uat.md gaps with diagnosis, then hand off to plan-stage --gaps with actual diagnoses.
+
+Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT.
+</purpose>
+
+<paths>
+DEBUG_DIR=.renn/debug
+
+Debug files use the `.renn/debug/` path (hidden directory with leading dot).
+</paths>
+
+<core_principle>
+**Diagnose before planning fixes.**
+
+UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). plan-stage --gaps then creates targeted fixes based on actual causes, not guesses.
+
+Without diagnosis: "Comment doesn't refresh" → guess at fix → maybe wrong
+With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → precise fix
+</core_principle>
+
+<process>
+
+<step name="parse_gaps">
+**Extract gaps from uat.md:**
+
+Read the "Gaps" section (YAML format):
+```yaml
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  artifacts: []
+  missing: []
+```
+
+For each gap, also read the corresponding test from "Tests" section to get full context.
+
+Build gap list:
+```
+gaps = [
+  {truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."},
+  {truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."},
+  ...
+]
+```
+</step>
+
+<step name="report_plan">
+**Report diagnosis plan to user:**
+
+```
+## Diagnosing {N} Gaps
+
+Spawning parallel debug agents to investigate root causes:
+
+| Gap (Truth) | Severity |
+|-------------|----------|
+| Comment appears immediately after submission | major |
+| Reply button positioned correctly | minor |
+| Delete removes comment | blocker |
+
+Each agent will:
+1. Create DEBUG-{slug}.md with symptoms pre-filled
+2. Investigate autonomously (read code, form hypotheses, test)
+3. Return root cause
+
+This runs in parallel - all gaps investigated simultaneously.
+```
+</step>
+
+<step name="spawn_agents">
+**Spawn debug agents in parallel:**
+
+For each gap, fill the detective-prompt template and spawn:
+
+```
+Task(
+  prompt=filled_detective_prompt,
+  subagent_type="renn-detective",
+  description="Debug: {truth_short}"
+)
+```
+
+**All agents spawn in single message** (parallel execution).
+
+Template placeholders:
+- `{truth}`: The expected behavior that failed
+- `{expected}`: From UAT test
+- `{actual}`: Verbatim user description from reason field
+- `{errors}`: Any error messages from UAT (or "None reported")
+- `{reproduction}`: "Test {test_num} in UAT"
+- `{timeline}`: "Discovered during UAT"
+- `{goal}`: `find_root_cause_only` (UAT flow - plan-stage --gaps handles fixes)
+- `{slug}`: Generated from truth
+</step>
+
+<step name="collect_results">
+**Collect root causes from agents:**
+
+Each agent returns with:
+```
+## CULPRIT FOUND
+
+**Debug Session:** ${DEBUG_DIR}/{slug}.md
+
+**Root Cause:** {specific cause with evidence}
+
+**Evidence Summary:**
+- {key finding 1}
+- {key finding 2}
+- {key finding 3}
+
+**Files Involved:**
+- {file1}: {what's wrong}
+- {file2}: {related issue}
+
+**Suggested Fix Direction:** {brief hint for plan-stage --gaps}
+```
+
+Parse each return to extract:
+- root_cause: The diagnosed cause
+- files: Files involved
+- debug_path: Path to debug session file
+- suggested_fix: Hint for gap closure plan
+
+If agent returns `## INVESTIGATION INCONCLUSIVE`:
+- root_cause: "Investigation inconclusive - manual review needed"
+- Note which issue needs manual attention
+- Include remaining possibilities from agent return
+</step>
+
+<step name="update_uat">
+**Update uat.md gaps with diagnosis:**
+
+For each gap in the Gaps section, add artifacts and missing fields:
+
+```yaml
+- truth: "Comment appears immediately after submission"
+  status: failed
+  reason: "User reported: works but doesn't show until I refresh the page"
+  severity: major
+  test: 2
+  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
+  artifacts:
+    - path: "src/components/CommentList.tsx"
+      issue: "useEffect missing dependency"
+  missing:
+    - "Add commentCount to useEffect dependency array"
+    - "Trigger re-render when new comment added"
+  debug_session: .renn/debug/comment-not-refreshing.md
+```
+
+Update status in frontmatter to "diagnosed".
+
+**Check planning config:**
+
+```bash
+COMMIT_PLANNING_DOCS=$(cat .renn/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
+git check-ignore -q .renn 2>/dev/null && COMMIT_PLANNING_DOCS=false
+```
+
+**If `COMMIT_PLANNING_DOCS=false`:** Skip git operations
+
+**If `COMMIT_PLANNING_DOCS=true` (default):**
+
+Commit the updated uat.md:
+```bash
+git add ".renn/stages/XX-name/{stage}-uat.md"
+git commit -m "docs({stage}): add root causes from diagnosis"
+```
+</step>
+
+<step name="report_results">
+**Report diagnosis results and hand off:**
+
+Display:
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ RENN ► DIAGNOSIS COMPLETE
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+| Gap (Truth) | Root Cause | Files |
+|-------------|------------|-------|
+| Comment appears immediately | useEffect missing dependency | CommentList.tsx |
+| Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
+| Delete removes comment | API missing auth header | api/comments.ts |
+
+Debug sessions: ${DEBUG_DIR}/
+
+Proceeding to plan fixes...
+```
+
+Return to audit orchestrator for automatic planning.
+Do NOT offer manual next steps - audit handles the rest.
+</step>
+
+</process>
+
+<context_efficiency>
+Agents start with symptoms pre-filled from UAT (no symptom gathering).
+Agents only diagnose—plan-stage --gaps handles fixes (no fix application).
+</context_efficiency>
+
+<failure_handling>
+**Agent fails to find root cause:**
+- Mark gap as "needs manual review"
+- Continue with other gaps
+- Report incomplete diagnosis
+
+**Agent times out:**
+- Check DEBUG-{slug}.md for partial progress
+- Can resume with renn.debug
+
+**All agents fail:**
+- Something systemic (permissions, git, etc.)
+- Report for manual investigation
+- Fall back to plan-stage --gaps without root causes (less precise)
+</failure_handling>
+
+<success_criteria>
+- [ ] Gaps parsed from uat.md
+- [ ] Debug agents spawned in parallel
+- [ ] Root causes collected from all agents
+- [ ] uat.md gaps updated with artifacts and missing
+- [ ] Debug sessions saved to ${DEBUG_DIR}/
+- [ ] Hand off to audit for automatic planning
+</success_criteria>