feed-the-machine 1.6.0 → 1.7.0

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

@@ -1,86 +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.
+# 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

@@ -1,103 +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
+# 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

@@ -1,2 +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.
+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.