feed-the-machine 1.0.0

package/ftm-debug/references/phases/PHASE-3-TO-6-EXECUTION.md

@@ -0,0 +1,436 @@
+# Phases 3–6: Synthesis, Solve, Review, and Present
+
+---
+
+## Phase 3 (War Room Phase 2 in original numbering): Synthesis & Solve
+
+After all investigation agents complete, synthesize their findings before solving.
+
+### Step 1: Cross-Reference Findings
+
+Read all four reports and synthesize:
+
+1. **Do the hypotheses match the research?** If the Researcher found a known bug that matches a Hypothesis, that's high signal.
+2. **Does the reproduction confirm a hypothesis?** If the Reproducer's characterization (only fails with X input, timing-dependent, etc.) matches a hypothesis's prediction, that's strong evidence.
+3. **What does the instrumentation suggest?** If the Instrumenter's logging points would help verify a specific hypothesis, note that.
+4. **Are there contradictions?** If the Researcher says "this is a known library bug" but the Hypothesizer says "this is a logic error in our code," figure out which is right.
+
+Present the synthesis to the user briefly:
+
+```
+War Room Findings:
+  Researcher: [key finding]
+  Reproducer: [reproduction status + characterization]
+  Hypothesizer: [top hypothesis]
+  Instrumenter: [logging added, key observation points]
+
+  Cross-reference: [how findings align or conflict]
+  Recommended fix approach: [what to try first]
+
+Proceeding to solve in isolated worktree.
+```
+
+### Step 2: Solver Agent Prompt
+
+Launch the **Solver agent** in a fresh worktree. The Solver gets the full synthesis — all four reports plus the cross-reference analysis.
+
+```
+You are the Solver in a debug war room. The investigation team has
+completed their analysis and you now have comprehensive context. Your
+job is to implement the fix.
+
+Working directory: [worktree path]
+Problem: [problem statement]
+Codebase context: [from Phase 0]
+
+## Investigation Results
+
+[paste full synthesis: Research findings, Reproduction results,
+Hypotheses ranked, Instrumentation notes, Cross-reference analysis]
+
+## Execution Rules
+
+### Work Incrementally
+- Start with the highest-ranked hypothesis
+- Implement the minimal fix that addresses it
+- COMMIT after each discrete change (not one big commit at the end)
+- Use clear commit messages: "Fix: [what] — addresses hypothesis [N]"
+
+### Verify as You Go
+- After each fix attempt, run the reproduction test from REPRODUCTION.md
+- If the project has existing tests, run them too (zero broken windows)
+- If the fix works on the reproduction but breaks other tests, that's
+  not done — fix the regressions too
+
+### If the First Hypothesis Doesn't Pan It
+- Don't keep hacking at it. Move to hypothesis #2.
+- Revert the failed attempt (git revert or fresh branch) so each
+  attempt starts clean
+- If you exhaust all hypotheses, say so — don't invent new ones
+  without evidence
+
+### Clean Up After Yourself
+- Remove any debug logging you added (unless the user wants to keep it)
+- Make sure the fix is minimal — don't refactor surrounding code
+- Don't add "just in case" error handling beyond what the fix requires
+
+### Do NOT Declare Victory
+- You are the Solver, not the Reviewer. Your job ends at "fix committed."
+- Do NOT tell the user "restart X to see the change" — that's the
+  Reviewer's job (and the Reviewer must do it, not the user)
+- Do NOT present results directly to the user — hand off to the
+  Reviewer agent via FIX-SUMMARY.md
+- Do NOT say the fix works unless you have actually verified it
+  by running it. "The code looks correct" is not verification.
+
+## Output Format
+
+1. All changes committed in the worktree with descriptive messages
+2. Write a file called `FIX-SUMMARY.md` documenting:
+   - **Root cause**: What was actually wrong (one paragraph)
+   - **Fix applied**: What you changed and why
+   - **Files modified**: List with brief descriptions
+   - **Commits**: List of commit hashes with messages
+   - **Verification**: What tests you ran and their results
+   - **Requires restart**: YES/NO — does the fix require restarting
+     a process, reloading config, or rebuilding to take effect?
+   - **Visual component**: YES/NO — does this bug have a visual or
+     experiential symptom that needs visual verification?
+   - **Remaining concerns**: Anything that should be monitored or
+     might need follow-up
+```
+
+---
+
+## Phase 4 (War Room Phase 3): Review & Verify
+
+**HARD GATE — You cannot proceed to Phase 5 without completing this phase.**
+
+This is non-negotiable. You cannot present results to the user until a Reviewer has independently verified the fix. "I checked with grep" is not verification. "The tests pass" is not verification. "The patch was applied" is not verification.
+
+Verification means: **the actual behavior the user reported as broken now works correctly, as observed by an agent, with captured evidence.**
+
+### Step 1: Determine Verification Method BEFORE Launching the Reviewer
+
+Look at the original bug report. Ask: "How would a human know this is fixed?"
+
+- If the answer involves SEEING something (UI, terminal output, rendered image, visual layout) → the Reviewer MUST capture a screenshot or visual evidence. Use `screencapture`, Playwright `browser_take_screenshot`, or process output capture.
+- If the answer involves a BEHAVIOR (API returns correct data, CLI produces right output, server responds correctly) → the Reviewer MUST exercise that behavior and capture the output.
+- If the answer is "the error stops happening" → the Reviewer MUST trigger the scenario that caused the error and confirm it no longer occurs.
+
+The verification method goes into the Reviewer's prompt. Don't let the Reviewer decide — tell it exactly what to verify and how.
+
+### Step 2: If the Fix Requires a Restart, the Reviewer Handles It
+
+Many fixes (bundle patches, config changes, build artifacts) require restarting a process to take effect. The Reviewer must:
+
+1. Restart the process (use `osascript` to launch in a new terminal if needed, or kill and restart the background process)
+2. Wait for it to initialize
+3. Exercise the fixed behavior
+4. Capture evidence (screenshot, output, logs)
+
+If the Reviewer literally cannot restart because it's running inside the process being fixed, try these alternatives first:
+
+1. **Launch a SEPARATE instance** via osascript/terminal:
+   ```bash
+   osascript -e 'tell application "Terminal" to do script "cd /path && claude --print \"hello\""'
+   sleep 5
+   screencapture -x /tmp/verification.png
+   ```
+   Then READ the screenshot to verify.
+
+2. **Launch via background process** and capture output:
+   ```bash
+   nohup claude --print "test" > /tmp/claude-output.txt 2>&1 &
+   sleep 5
+   cat /tmp/claude-output.txt
+   ```
+
+3. **Use Playwright MCP** if available to screenshot a running instance.
+
+Only if ALL of these are impossible should you flag as BLOCKED. In that case, tell the user exactly what to look for, why you couldn't verify it yourself, and what the expected visual result should be (with specifics, not "check if it works").
+
+### Step 3: Reviewer Agent Prompt
+
+```
+You are the Reviewer in a debug war room. The Solver has implemented a
+fix and your job is to verify it actually works, doesn't break anything
+else, and is the right approach.
+
+Working directory: [solver's worktree path]
+Problem: [original problem statement]
+Fix summary: [from FIX-SUMMARY.md]
+Reproduction: [from REPRODUCTION.md]
+
+## Review Checklist
+
+### 1. Does the Fix Address the Root Cause?
+- Read the fix diff carefully
+- Does it fix the actual root cause, or just mask the symptom?
+- Could the same bug recur in a different form?
+- Is the fix in the right layer of abstraction?
+
+### 2. Reproduction Verification (YOU MUST RUN THESE — do not list them for the user)
+- EXECUTE the reproduction test — it should PASS now
+- Run it multiple times if the bug was intermittent
+- Try variations of the reproduction (different inputs, timing, config)
+- Capture the actual output/logs as evidence
+
+### 3. Regression Check (YOU MUST RUN THESE)
+- EXECUTE the full test suite and capture results
+- EXECUTE linting and type checking
+- EXECUTE any build steps and verify success
+- If the fix involves a running process (server, CLI tool, UI):
+  launch it, exercise the fixed behavior, check logs, and capture
+  evidence that it works
+
+### 4. Live Verification (critical — tests passing is NECESSARY but NOT SUFFICIENT)
+
+Tests verify code structure. Live verification proves the feature actually
+works as experienced by a user. Many bugs exist in the gap between "all
+tests pass" and "it actually works." Your job is to close that gap.
+
+**Why this matters**: A test can assert that a function returns the right
+value, but that doesn't prove the function gets called, its output reaches
+the renderer, the renderer handles it correctly, and the user sees the
+expected result. Each layer can silently fail while tests pass.
+
+#### Automated Runtime Verification (always do these)
+- If the fix involves a server/process: START it, EXERCISE the fixed
+  behavior via curl/CLI/API calls, READ stdout/stderr, CAPTURE evidence
+- If the fix involves CLI output: RUN the command, CAPTURE the output,
+  COMPARE against expected output
+- If the fix involves log output: RUN the code, READ the log file,
+  CONFIRM expected entries appear
+- If the fix involves a build: RUN the build, VERIFY the output artifact
+  exists and contains expected content (grep/inspect the built files)
+- If the fix involves configuration: LOAD the config, VERIFY the values
+  propagate to where they're used at runtime (not just that the config
+  file is correct)
+
+#### Visual/Runtime Verification (when the bug has a visual or interactive component)
+
+Some bugs only manifest visually — terminal rendering, UI display, image
+output, interactive behavior. Tests can't catch these. You must verify
+the actual rendered result.
+
+**Techniques for visual verification:**
+
+1. **Playwright/browser automation**: For web UIs, launch Playwright,
+   navigate to the page, take a screenshot, and inspect the DOM. Check
+   that elements are visible, correctly positioned, and contain expected
+   content. This catches CSS bugs, rendering issues, and layout breaks
+   that pass all unit tests.
+
+2. **AppleScript + screenshot** (macOS): For native apps, CLI tools with
+   visual output, or terminal-rendered content:
+   ```
+   # Launch the application via AppleScript
+   osascript -e 'tell application "Terminal" to do script "your-command"'
+   # Wait for it to render, then capture
+   screencapture -x /tmp/verification-screenshot.png
+   ```
+   Then read the screenshot to verify the visual result.
+
+3. **Process output capture**: For CLI tools and terminal UIs, run the
+   command with output capture (script command, tee, or redirect) and
+   inspect the raw output including ANSI codes, escape sequences, and
+   control characters that affect rendering.
+
+4. **Playwright for Electron/web-based tools**: Many modern tools
+   (VS Code extensions, Electron apps, web dashboards) can be automated
+   with Playwright. Use `browser_navigate`, `browser_snapshot`, and
+   `browser_take_screenshot` to verify rendered state.
+
+5. **ftm-browse ($PB) for UI verification**: If ftm-browse is
+   installed, use it for visual verification of web UI bugs. First check
+   whether the binary exists:
+   ```bash
+   PB="$HOME/.claude/skills/ftm-browse/bin/ftm-browse"
+   ```
+   If the binary exists at that path, use it:
+   - **Navigate**: `$PB goto <url>` — open the affected page
+   - **Before screenshot**: `$PB screenshot --path /tmp/debug-before.png`
+     (capture state BEFORE verifying the fix is live, if you need a
+     before/after comparison — do this before the fix is applied or on
+     a pre-fix worktree)
+   - **After screenshot**: `$PB screenshot --path /tmp/debug-after.png`
+     (capture state AFTER fix is applied and running)
+   - **DOM inspection**: `$PB snapshot -i` — get the interactive ARIA
+     tree to verify element existence, visibility, and state
+     (e.g., confirm a button is now visible, a panel is collapsed,
+     an error message is gone)
+   - Report both screenshot paths in REVIEW-VERDICT.md so the user
+     can compare before/after visually.
+
+   **Graceful fallback**: If the binary does NOT exist at
+   `$HOME/.claude/skills/ftm-browse/bin/ftm-browse`, fall back to
+   test-only and other available verification methods (Playwright, etc.).
+   Do NOT fail the review. Record in the Verification Gate section:
+   "Visual verification skipped — ftm-browse not installed."
+
+**When to use visual verification:**
+- Terminal rendering (status lines, TUI elements, colored output, unicode)
+- Web UI changes (layout, styling, visibility, interaction)
+- Image/PDF/document generation (verify output visually, not just file size)
+- Any bug where "it looks wrong" was part of the symptom
+- Any fix where tests pass but you're not 100% confident the user will
+  see the correct result
+
+**The rule**: If the bug was reported as something the user SAW (or didn't
+see), verification must confirm what the user will SEE (or will now see).
+Passing tests are evidence, not proof. Visual confirmation is proof.
+
+#### Never Do This
+- NEVER write "How to verify: run X" — instead, RUN X yourself and
+  report what happened
+- NEVER say "restart the app to see the change" — restart it yourself,
+  observe the result, report back
+- NEVER assume tests passing = feature working. Tests verify code paths.
+  Live verification proves the feature delivers its intended experience.
+
+### 5. Code Quality
+- Is the fix minimal and focused?
+- Does it follow the project's existing patterns?
+- Are there edge cases the fix doesn't handle?
+- Is error handling appropriate (not excessive, not missing)?
+
+### 6. Observability
+- Will this failure mode be visible if it happens again?
+- Should any permanent logging or monitoring be added?
+- Are there metrics or alerts that should be updated?
+
+## Mandatory Verification Gate
+
+Before writing the verdict, answer these two questions:
+
+**Q1: Was the bug reported as something visual/experiential?**
+(Did the user say "it doesn't show up", "it looks wrong", "the UI is broken",
+"nothing happens when I click", "the output is garbled", etc.)
+
+If YES → Visual verification is REQUIRED. You cannot approve without
+capturing a screenshot, reading rendered output, or observing the
+running application. Grep checks and log analysis are not sufficient.
+
+If NO → Automated runtime verification (running tests, checking output)
+is sufficient.
+
+**Q2: Does the fix require restarting a process to take effect?**
+(Patching a bundle, changing config loaded at startup, modifying
+compiled artifacts, etc.)
+
+If YES → YOU must restart the process, observe the result, and capture
+evidence. Do not tell the user to restart — do it yourself:
+```
+# Example: restart a CLI tool and capture its output
+osascript -e 'tell application "Terminal" to do script "cd /path && your-command"'
+sleep 3
+screencapture -x /tmp/verification-screenshot.png
+# Then READ the screenshot to verify
+```
+
+If you cannot restart the process (e.g., it's the very tool you're
+running inside), this is one of the rare legitimate cases to ask the
+user — but you MUST say what specific thing to look for and why you
+couldn't verify it yourself.
+
+## Output Format
+
+Write a file called `REVIEW-VERDICT.md` with:
+
+### Verdict: [APPROVED / APPROVED WITH CHANGES / NEEDS REWORK]
+
+### Verification Gate
+- Bug is visual/experiential: [YES/NO]
+- Fix requires process restart: [YES/NO]
+- Visual verification performed: [YES — describe what was captured / NO — explain why not required / BLOCKED — explain why agent couldn't do it]
+
+### Fix Verification
+- Reproduction test: [PASS/FAIL — actual output]
+- Full test suite: [PASS/FAIL with details]
+- Build: [PASS/FAIL]
+- Lint/typecheck: [PASS/FAIL]
+- Runtime verification: [what was run, what was observed]
+- Visual verification: [screenshot path, DOM snapshot, or rendered output captured — or N/A with reason]
+
+### Code Review Notes
+- [specific observations, line references]
+
+### Concerns
+- [anything that needs attention]
+
+### Recommended Follow-ups
+- [monitoring, tests to add, documentation to update]
+```
+
+If the Reviewer says **NEEDS REWORK**, send the feedback back to the Solver agent for another iteration. The Solver-Reviewer loop continues until the verdict is APPROVED (max 3 iterations — after that, escalate to the user with full context of what's been tried).
+
+---
+
+## Phase 5 (War Room Phase 4): Present Results
+
+**CHECKPOINT: Before presenting, confirm these are true:**
+- [ ] A Reviewer agent was spawned (not just the Solver declaring victory)
+- [ ] The Reviewer's verdict includes actual evidence (output captures, screenshots, log snippets — not just "PASS")
+- [ ] If the bug was visual, visual evidence was captured
+- [ ] If the fix required a restart, the restart happened and post-restart behavior was verified
+- [ ] No "How to Verify" or "Restart X to see the change" instructions are included in the presentation
+
+If any of these are false, you are not ready to present. Go back to Phase 4.
+
+Once the Reviewer approves, present the full results to the user:
+
+```
+## Debug War Room Complete
+
+### Root Cause
+[One paragraph explaining what was wrong — clear enough that someone
+unfamiliar with the code would understand]
+
+### What Changed
+[List of files modified with brief descriptions]
+
+### Verification Already Performed
+[These are things the Reviewer ALREADY RAN — not suggestions for the
+user to do. Include actual output/evidence.]
+- Reproduction test: PASS — [actual output snippet]
+- Full test suite: PASS — [X tests passed, 0 failures]
+- Build: PASS
+- Runtime verification: [command run, output captured, expected vs actual]
+- Visual verification (if applicable): [what was launched, screenshot/DOM
+  evidence, what the user will see — this closes the gap between "tests
+  pass" and "it actually works"]
+- Reviewer verdict: APPROVED
+
+### Key Findings
+- [Top research findings that informed the fix]
+- [Instrumentation insights that revealed the bug]
+- [Hypotheses that were tested, including ones that were wrong — these
+  help the user's understanding]
+
+### Commits (in worktree: [branch name])
+[List of commits with messages]
+
+Ready to merge. All automated verification has passed.
+```
+
+**Do NOT include a "How to Verify Yourself" section with manual steps.** If there is any verification that can be automated, the Reviewer must have already done it. The only reason to mention verification steps to the user is if something genuinely requires human judgment (visual design review, business logic confirmation) — and even then, explain what the agents already checked and what specifically needs a human eye.
+
+Wait for the user to validate. Once they confirm:
+
+1. Merge the solver's worktree branch to main
+2. Clean up all worktrees and branches
+3. Remove any remaining debug instrumentation (unless the user wants to keep it)
+
+---
+
+## Phase 6: Escalation Protocol
+
+If after 3 Solver-Reviewer iterations the fix still isn't approved:
+
+1. Present everything to the user: all hypotheses tested, all fix attempts, all review feedback
+2. Ask the user for direction — they may have context that wasn't available to the agents
+3. If the user provides new information, restart from Phase 1 with the new context
+4. If the user wants to pair on it, switch to interactive debugging with all the instrumentation and research already done as context
+
+The war room is powerful but not omniscient. Sometimes the bug requires domain knowledge only the user has. The goal is to do 90% of the work so the user's intervention is a focused 10%.

package/ftm-debug/references/protocols/BLACKBOARD.md

@@ -0,0 +1,86 @@
+# Shared Blackboard Protocol
+
+The blackboard is a persistent shared state that allows skills to coordinate across sessions and learn from past debugging sessions.
+
+---
+
+## Blackboard Read (on session start)
+
+Before starting, load context from the blackboard:
+
+1. Read `~/.claude/ftm-state/blackboard/context.json` — check current_task, recent_decisions, active_constraints
+2. Read `~/.claude/ftm-state/blackboard/experiences/index.json` — filter entries by task_type="bug" and tags matching the current error domain
+3. Load top 3-5 matching experience files for known fixes and failed approaches
+4. Read `~/.claude/ftm-state/blackboard/patterns.json` — check recurring_issues for matching symptoms and codebase_insights for relevant file patterns
+
+If index.json is empty or no matches found, proceed normally without experience-informed shortcuts.
+
+---
+
+## Blackboard Write (on session complete)
+
+After the debug session concludes, update the blackboard:
+
+### 1. Update context.json
+
+Path: `~/.claude/ftm-state/blackboard/context.json`
+
+- Set `current_task.status` to `"complete"`
+- Append a decision summary to `recent_decisions` (keep array capped at 10 entries)
+- Update `session_metadata.skills_invoked` to include `"ftm-debug"`
+- Update `session_metadata.last_updated` to current timestamp
+
+### 2. Write Experience File
+
+Path: `~/.claude/ftm-state/blackboard/experiences/YYYY-MM-DD_task-slug.json`
+
+Capture the following in the experience file:
+
+```json
+{
+  "date": "YYYY-MM-DD",
+  "task_slug": "short-description-of-bug",
+  "task_type": "bug",
+  "symptom": "One-sentence description of what the user reported",
+  "root_cause": "One-sentence description of what was actually wrong",
+  "hypotheses_tested": [
+    { "hypothesis": "...", "outcome": "confirmed | rejected" }
+  ],
+  "fix_approach": "Brief description of the fix strategy used",
+  "fix_files": ["path/to/file1.js", "path/to/file2.ts"],
+  "verification_method": "test | visual | runtime | combined",
+  "tags": ["race-condition", "react", "async", "etc."],
+  "check_first_next_time": "The thing that was most predictive of the root cause"
+}
+```
+
+### 3. Update experiences/index.json
+
+Path: `~/.claude/ftm-state/blackboard/experiences/index.json`
+
+Append a new entry to the index:
+
+```json
+{
+  "file": "YYYY-MM-DD_task-slug.json",
+  "task_type": "bug",
+  "tags": ["same-tags-as-experience-file"],
+  "summary": "One-line description for quick matching"
+}
+```
+
+### 4. Emit Event
+
+Emit `task_completed` event to signal the session is done.
+
+---
+
+## Experience File Matching Logic
+
+When loading experiences at session start, match by:
+
+1. **task_type** must equal `"bug"`
+2. **tags** overlap with current error domain (e.g., framework name, error category, file path patterns)
+3. **symptom** similarity (loose match on keywords from the current problem statement)
+
+Prioritize experiences where `check_first_next_time` is populated — these are the highest-value shortcuts.

package/ftm-debug/references/protocols/EDGE-CASES.md

@@ -0,0 +1,103 @@
+# Edge Cases, Anti-Patterns & Fallback Handling
+
+---
+
+## Anti-Pattern: Asking the User to Do Agent Work
+
+This is the single most important rule of the war room: **never ask the user to perform a verification step that an agent could perform**.
+
+Examples of violations:
+- "Restart the application and check if the doom head appears" — an agent can launch the app, capture a screenshot, read the output, verify the rendering
+- "Run `tail -f /tmp/debug.log` and look for entries" — an agent can read that file
+- "Open a browser and check the UI" — an agent can use Playwright/Puppeteer to screenshot and inspect the DOM
+- "Try running this command and let me know what happens" — an agent can run the command
+- "All 103 tests pass!" without verifying the actual feature works — tests are a proxy, not proof. The agent must also verify runtime behavior matches expectations
+
+Examples of legitimate user asks:
+- "Does this visual design match what you wanted?" — subjective human judgment
+- "Is this the business logic you intended?" — domain knowledge only the user has
+- "Should we merge this to main?" — permission/authority decision
+
+When in doubt: if it can be executed by running a command, reading a file, or checking output, an agent does it. The user reviews the evidence the agent collected, not the raw behavior.
+
+---
+
+## Anti-Pattern: Collapsing Solver and Reviewer Into One
+
+A common failure mode: the session reads this skill, does good investigation work, writes a fix, then presents results directly to the user — skipping the Reviewer agent entirely. The Solver says "Restart X to see the change" and declares victory.
+
+This defeats the entire verification system. The Solver is biased toward their own fix. They wrote the code and believe it works. The Reviewer exists as an independent check.
+
+**The rule**: After the Solver commits their fix, you MUST spawn a separate Reviewer agent. The Reviewer reads FIX-SUMMARY.md, runs the verification gate, and either approves or sends it back. Only after the Reviewer approves do you present results to the user.
+
+If you find yourself writing "Root Cause / What Changed / How to Verify" without having spawned a Reviewer — stop. You're doing the anti-pattern. Spawn the Reviewer.
+
+---
+
+## Anti-Pattern: Structural Verification Masquerading as Live Verification
+
+Another common failure: the session verifies the fix by grepping the patched file for expected strings, checking that function references exist, or confirming config values are set. This is structural verification — it proves the code was written, not that it works.
+
+Example of structural verification pretending to be live:
+```
+✓ grep -c "doom_status patch start" cli.js → 1
+✓ grep -c "doomStatuslineBackend" cli.js → 6
+✓ node -e "require('cli.js')" → parses
+```
+
+This proves the patch was applied and the file isn't syntactically broken. It does NOT prove the doom head renders visually. The grep checks are necessary but they are Phase 4 Step 3 (regression checks), not Phase 4 Step 4 (live verification).
+
+Live verification for this bug would be: launch Claude Code, wait for the statusline to render, capture a screenshot, confirm the doom head is visible. That's what the Reviewer must do for visual bugs.
+
+---
+
+## Fallback: Reviewer Cannot Restart the Process
+
+If the Reviewer literally cannot restart because it's running inside the process being fixed (e.g., debugging Claude Code from within Claude Code), try these alternatives before flagging BLOCKED:
+
+1. **Launch a SEPARATE instance** via osascript/terminal:
+   ```bash
+   osascript -e 'tell application "Terminal" to do script "cd /path && claude --print \"hello\""'
+   sleep 5
+   screencapture -x /tmp/verification.png
+   ```
+   Then READ the screenshot to verify.
+
+2. **Launch via background process** and capture output:
+   ```bash
+   nohup claude --print "test" > /tmp/claude-output.txt 2>&1 &
+   sleep 5
+   cat /tmp/claude-output.txt
+   ```
+
+3. **Use Playwright MCP** if available to screenshot a running instance.
+
+Only if ALL of these are impossible: flag as BLOCKED, tell the user exactly what to look for, why you couldn't verify it yourself, and what the expected visual result should be (with specifics, not "check if it works").
+
+---
+
+## Fallback: ftm-browse Not Installed
+
+When visual verification is needed for a web UI bug:
+
+```bash
+PB="$HOME/.claude/skills/ftm-browse/bin/ftm-browse"
+```
+
+If the binary does NOT exist at that path:
+- Fall back to Playwright MCP, Puppeteer, or screencapture
+- Do NOT fail the review
+- Record in REVIEW-VERDICT.md Verification Gate section: "Visual verification skipped — ftm-browse not installed."
+- Use whatever alternative is available
+
+---
+
+## Fallback: Exhausted All Hypotheses Without a Fix
+
+If the Solver exhausts all hypotheses and no fix is approved after 3 Solver-Reviewer iterations:
+
+1. Do NOT invent new hypotheses without evidence
+2. Present everything to the user: all hypotheses tested, all fix attempts, all review feedback
+3. Ask for direction — the user may have domain context not available to the agents
+4. If the user provides new information, restart from Phase 1 with the updated context
+5. If the user wants to pair, switch to interactive debugging with all instrumentation and research as context

package/ftm-debug.yml

@@ -0,0 +1,2 @@
+name: ftm-debug
+description: Deep multi-vector debugging war room that launches parallel agent teams to instrument, research, reproduce, hypothesize, solve, and verify tricky bugs. Use when a bug is stubborn, multi-turn debugging hasn't worked, the user says "debug this deeply", "war room this", "I can't figure out why", "this is driving me crazy", "launch the debug team", or any situation where standard debugging is insufficient. Also triggers on "/ftm-debug". Covers any codebase — frontend, backend, CLI tools, native apps, build systems, anything. Do NOT use for simple one-step fixes — this is the heavy artillery for problems that resist normal debugging.