From 88ba26c930b6cf11e59ebbaed0baa1f91080c4b6 Mon Sep 17 00:00:00 2001
From: ejclaw <phj1081@gmail.com>
Date: Thu, 21 May 2026 05:25:34 +0900
Subject: [PATCH] docs(prompt): add debugging discipline rules

---
 prompts/claude-paired-room.md       |  9 +++++++++
 prompts/owner-common-paired-room.md |  9 +++++++++
 src/platform-prompts.test.ts        | 27 +++++++++++++++++++++++++++
 3 files changed, 45 insertions(+)

diff --git a/prompts/claude-paired-room.md b/prompts/claude-paired-room.md
index aef6af5..39ad6d9 100644
--- a/prompts/claude-paired-room.md
+++ b/prompts/claude-paired-room.md
@@ -20,6 +20,15 @@ Before accepting any proposal, run it through:
 Push back with evidence when the owner is wrong. Hold your ground when you are right. Point out logical gaps, missing edge cases, over-engineering. Agree when the owner is genuinely correct.
 If you see a materially better design, debugging path, or scoping choice, propose it briefly. Distinguish blocking defects from optional improvements so the owner can prioritize correctly.
 
+## Debugging discipline
+
+For bugs, outages, failed checks, or unexpected behavior:
+
+- Require root-cause evidence before accepting a fix; do not approve symptom patches
+- Check the diagnosis against exact error/logs, reproduction path, recent changes, or component-boundary data
+- Prefer one clear hypothesis plus the smallest targeted verification over broad rewrites
+- If the owner repeats the same failed fix path 3 times, name the stagnation pattern and recommend a new direction or arbiter path
+
 ## Completion status
 
 **Start your first line** with one of these six statuses. This is required.
diff --git a/prompts/owner-common-paired-room.md b/prompts/owner-common-paired-room.md
index f91f0a5..69b8b99 100644
--- a/prompts/owner-common-paired-room.md
+++ b/prompts/owner-common-paired-room.md
@@ -16,6 +16,15 @@ Before accepting any proposal from the reviewer, run it through:
 
 Challenge the reviewer's reasoning. Point out logical gaps, over-engineering, scope drift. Agree when the work is genuinely correct.
 
+## Debugging discipline
+
+For bugs, outages, failed checks, or unexpected behavior:
+
+- Identify the root-cause before changing code; do not patch symptoms first
+- Ground the diagnosis in evidence: exact error/log, reproduction path, recent changes, or component-boundary data
+- State one hypothesis and verify it with the smallest targeted test or command
+- If the same failed fix path repeats 3 times, name the stagnation pattern and recommend a new direction instead of stacking guesses
+
 ## Completion status
 
 **Start your first line** with one of these six statuses. This is required.
diff --git a/src/platform-prompts.test.ts b/src/platform-prompts.test.ts
index e766e8d..a18f312 100644
--- a/src/platform-prompts.test.ts
+++ b/src/platform-prompts.test.ts
@@ -97,4 +97,31 @@ describe('platform-prompts', () => {
     );
     expect(failoverPlatformPrompt).toContain('acting as `클코`');
   });
+
+  it('keeps the superpowers-derived debugging guidance compressed and role-scoped', () => {
+    const repoRoot = path.resolve(
+      path.dirname(fileURLToPath(import.meta.url)),
+      '..',
+    );
+    const promptsDir = path.join(repoRoot, 'prompts');
+    const ownerPrompt = fs.readFileSync(
+      path.join(promptsDir, 'owner-common-paired-room.md'),
+      'utf-8',
+    );
+    const reviewerPrompt = fs.readFileSync(
+      path.join(promptsDir, 'claude-paired-room.md'),
+      'utf-8',
+    );
+
+    for (const prompt of [ownerPrompt, reviewerPrompt]) {
+      expect(prompt).toContain('## Debugging discipline');
+      expect(prompt).toContain('root-cause');
+      expect(prompt).toContain('component-boundary data');
+      expect(prompt).toContain('same failed fix path');
+      expect(prompt).toContain('3 times');
+      expect(prompt).not.toContain('superpowers');
+      expect(prompt).not.toContain('NO FIXES WITHOUT ROOT CAUSE');
+      expect(prompt).not.toContain('The Four Phases');
+    }
+  });
 });