;\n}\n```\n\n**Why this is wrong:**\n- Mock encodes the bug into the test\n- TypeScript can't catch inline mocks with wrong method names\n- Test passes because both code and mock are wrong\n- Runtime crashes when real object is used\n\n**The fix:**\n```typescript\n// ✅ GOOD: Derive mock from interface\n\n// Step 1: Open interface definition (PlatformAdapter)\n// Step 2: List methods defined there (close, initialize, etc.)\n// Step 3: Mock EXACTLY those methods\n\nconst mock = {\n initialize: vi.fn().mockResolvedValue(undefined),\n close: vi.fn().mockResolvedValue(undefined), // From interface!\n};\n\n// Now test FAILS because code calls cleanup() which doesn't exist\n// That failure reveals the bug BEFORE runtime\n```\n\n### Gate Function\n\n```\nBEFORE writing any mock:\n\n 1. STOP - Do NOT look at the code under test yet\n 2. FIND: The interface/type definition for the dependency\n 3. READ: The interface file\n 4. LIST: Methods defined in the interface\n 5. MOCK: ONLY those methods with EXACTLY those names\n 6. DO NOT: Look at what your code calls\n\n IF your test fails because code calls something not in mock:\n ✅ GOOD - The test found a bug in your code\n Fix the code to call the correct interface method\n NOT the mock\n\n Red flags:\n - \"I'll mock what the code calls\"\n - Copying method names from implementation\n - Mock written without reading interface\n - \"The test is failing so I'll add this method to the mock\"\n```\n\n**Detection:**\n\nWhen you see runtime error \"X is not a function\" and tests pass:\n1. Check if X is mocked\n2. Compare mock methods to interface methods\n3. Look for method name mismatches\n```\n\n**Why this works:**\nDirectly addresses the failure pattern from feedback.\n\n---\n\n### 7. subagent-driven-development: Require Skills Reading for Test Subagents\n\n**Add to prompt template when task involves testing:**\n\n```markdown\nBEFORE writing any tests:\n\n1. Read testing-anti-patterns skill:\n Use Skill tool: superpowers:testing-anti-patterns\n\n2. Apply gate functions from that skill when:\n - Writing mocks\n - Adding methods to production classes\n - Mocking dependencies\n\nThis is NOT optional. Tests that violate anti-patterns will be rejected in review.\n```\n\n**Why this works:**\nEnsures skills are actually used, not just exist.\n\n**Trade-off:**\nAdds time to each task, but prevents entire classes of bugs.\n\n---\n\n### 8. subagent-driven-development: Allow Implementer to Fix Self-Identified Issues\n\n**Modify Step 2:**\n\n**Current:**\n```\nSubagent reports back with summary of work.\n```\n\n**Proposed:**\n```\nSubagent performs self-reflection, then:\n\nIF self-reflection identifies fixable issues:\n 1. Fix the issues\n 2. Re-run verification\n 3. Report: \"Initial implementation + self-reflection fix\"\n\nELSE:\n Report: \"Implementation complete\"\n\nInclude in report:\n- Self-reflection findings\n- Whether fixes were applied\n- Final verification results\n```\n\n**Why this works:**\nReduces latency when implementer already knows the fix. Documented case: would have saved one round-trip for entrypoint bug.\n\n**Trade-off:**\nSlightly more complex prompt, but faster end-to-end.\n\n---\n\n## Implementation Plan\n\n### Phase 1: High-Impact, Low-Risk (Do First)\n\n1. **verification-before-completion: Configuration change verification**\n - Clear addition, doesn't change existing content\n - Addresses high-impact problem (false confidence in tests)\n - File: `skills/verification-before-completion/SKILL.md`\n\n2. **testing-anti-patterns: Mock-interface drift**\n - Adds new anti-pattern, doesn't modify existing\n - Addresses high-impact problem (runtime crashes)\n - File: `skills/testing-anti-patterns/SKILL.md`\n\n3. **requesting-code-review: Explicit file reading**\n - Simple addition to template\n - Fixes concrete problem (reviewers can't find files)\n - File: `skills/requesting-code-review/SKILL.md`\n\n### Phase 2: Moderate Changes (Test Carefully)\n\n4. **subagent-driven-development: Process hygiene**\n - Adds new section, doesn't change workflow\n - Addresses medium-high impact (test reliability)\n - File: `skills/subagent-driven-development/SKILL.md`\n\n5. **subagent-driven-development: Self-reflection**\n - Changes prompt template (higher risk)\n - But documented to catch bugs\n - File: `skills/subagent-driven-development/SKILL.md`\n\n6. **subagent-driven-development: Skills reading requirement**\n - Adds prompt overhead\n - But ensures skills are actually used\n - File: `skills/subagent-driven-development/SKILL.md`\n\n### Phase 3: Optimization (Validate First)\n\n7. **subagent-driven-development: Lean context option**\n - Adds complexity (two approaches)\n - Needs validation that it doesn't cause confusion\n - File: `skills/subagent-driven-development/SKILL.md`\n\n8. **subagent-driven-development: Allow implementer to fix**\n - Changes workflow (higher risk)\n - Optimization, not bug fix\n - File: `skills/subagent-driven-development/SKILL.md`\n\n---\n\n## Open Questions\n\n1. **Lean context approach:**\n - Should we make it the default for pattern-based tasks?\n - How do we decide which approach to use?\n - Risk of being too lean and missing important context?\n\n2. **Self-reflection:**\n - Will this slow down simple tasks significantly?\n - Should it only apply to complex tasks?\n - How do we prevent \"reflection fatigue\" where it becomes rote?\n\n3. **Process hygiene:**\n - Should this be in subagent-driven-development or a separate skill?\n - Does it apply to other workflows beyond E2E tests?\n - How do we handle cases where process SHOULD persist (dev servers)?\n\n4. **Skills reading enforcement:**\n - Should we require ALL subagents to read relevant skills?\n - How do we keep prompts from becoming too long?\n - Risk of over-documenting and losing focus?\n\n---\n\n## Success Metrics\n\nHow do we know these improvements work?\n\n1. **Configuration verification:**\n - Zero instances of \"test passed but wrong config was used\"\n - Jesse doesn't say \"that's not actually testing what you think\"\n\n2. **Process hygiene:**\n - Zero instances of \"test hit wrong server\"\n - No port conflict errors during E2E test runs\n\n3. **Mock-interface drift:**\n - Zero instances of \"tests pass but runtime crashes on missing method\"\n - No method name mismatches between mocks and interfaces\n\n4. **Self-reflection:**\n - Measurable: Do implementer reports include self-reflection findings?\n - Qualitative: Do fewer bugs make it to code review?\n\n5. **Skills reading:**\n - Subagent reports reference skill gate functions\n - Fewer anti-pattern violations in code review\n\n---\n\n## Risks and Mitigations\n\n### Risk: Prompt Bloat\n**Problem:** Adding all these requirements makes prompts overwhelming\n**Mitigation:**\n- Phase implementation (don't add everything at once)\n- Make some additions conditional (E2E hygiene only for E2E tests)\n- Consider templates for different task types\n\n### Risk: Analysis Paralysis\n**Problem:** Too much reflection/verification slows execution\n**Mitigation:**\n- Keep gate functions quick (seconds, not minutes)\n- Make lean context opt-in initially\n- Monitor task completion times\n\n### Risk: False Sense of Security\n**Problem:** Following checklist doesn't guarantee correctness\n**Mitigation:**\n- Emphasize gate functions are minimums, not maximums\n- Keep \"use judgment\" language in skills\n- Document that skills catch common failures, not all failures\n\n### Risk: Skill Divergence\n**Problem:** Different skills give conflicting advice\n**Mitigation:**\n- Review changes across all skills for consistency\n- Document how skills interact (Integration sections)\n- Test with real scenarios before deployment\n\n---\n\n## Recommendation\n\n**Proceed with Phase 1 immediately:**\n- verification-before-completion: Configuration change verification\n- testing-anti-patterns: Mock-interface drift\n- requesting-code-review: Explicit file reading\n\n**Test Phase 2 with Jesse before finalizing:**\n- Get feedback on self-reflection impact\n- Validate process hygiene approach\n- Confirm skills reading requirement is worth overhead\n\n**Hold Phase 3 pending validation:**\n- Lean context needs real-world testing\n- Implementer-fix workflow change needs careful evaluation\n\nThese changes address real problems documented by users while minimizing risk of making skills worse.\n"
},
{
"path": "docs/plans/2026-01-17-visual-brainstorming.md",
"content": "# Visual Brainstorming Companion Implementation Plan\n\n> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.\n\n**Goal:** Give Claude a browser-based visual companion for brainstorming sessions - show mockups, prototypes, and interactive choices alongside terminal conversation.\n\n**Architecture:** Claude writes HTML to a temp file. A local Node.js server watches that file and serves it with an auto-injected helper library. User interactions flow via WebSocket to server stdout, which Claude sees in background task output.\n\n**Tech Stack:** Node.js, Express, ws (WebSocket), chokidar (file watching)\n\n---\n\n## Task 1: Create the Server Foundation\n\n**Files:**\n- Create: `lib/brainstorm-server/index.js`\n- Create: `lib/brainstorm-server/package.json`\n\n**Step 1: Create package.json**\n\n```json\n{\n \"name\": \"brainstorm-server\",\n \"version\": \"1.0.0\",\n \"description\": \"Visual brainstorming companion server for Claude Code\",\n \"main\": \"index.js\",\n \"dependencies\": {\n \"chokidar\": \"^3.5.3\",\n \"express\": \"^4.18.2\",\n \"ws\": \"^8.14.2\"\n }\n}\n```\n\n**Step 2: Create minimal server that starts**\n\n```javascript\nconst express = require('express');\nconst http = require('http');\nconst WebSocket = require('ws');\nconst chokidar = require('chokidar');\nconst fs = require('fs');\nconst path = require('path');\n\nconst PORT = process.env.BRAINSTORM_PORT || 3333;\nconst SCREEN_FILE = process.env.BRAINSTORM_SCREEN || '/tmp/brainstorm/screen.html';\nconst SCREEN_DIR = path.dirname(SCREEN_FILE);\n\n// Ensure screen directory exists\nif (!fs.existsSync(SCREEN_DIR)) {\n fs.mkdirSync(SCREEN_DIR, { recursive: true });\n}\n\n// Create default screen if none exists\nif (!fs.existsSync(SCREEN_FILE)) {\n fs.writeFileSync(SCREEN_FILE, `\n\n\n Brainstorm Companion\n \n\n\n Brainstorm Companion
\n Waiting for Claude to push a screen...
\n\n`);\n}\n\nconst app = express();\nconst server = http.createServer(app);\nconst wss = new WebSocket.Server({ server });\n\n// Track connected browsers for reload notifications\nconst clients = new Set();\n\nwss.on('connection', (ws) => {\n clients.add(ws);\n ws.on('close', () => clients.delete(ws));\n\n ws.on('message', (data) => {\n // User interaction event - write to stdout for Claude\n const event = JSON.parse(data.toString());\n console.log(JSON.stringify({ type: 'user-event', ...event }));\n });\n});\n\n// Serve current screen with helper.js injected\napp.get('/', (req, res) => {\n let html = fs.readFileSync(SCREEN_FILE, 'utf-8');\n\n // Inject helper script before