From 2bed35d315c91c83a16452a3b7694a407e416d16 Mon Sep 17 00:00:00 2001 From: Eyejoker Date: Thu, 21 May 2026 05:32:37 +0900 Subject: [PATCH 1/2] 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'); + } + }); }); From ce750eed956ae94838953c45e318ef738d2dece1 Mon Sep 17 00:00:00 2001 From: Eyejoker Date: Thu, 21 May 2026 05:35:59 +0900 Subject: [PATCH 2/2] docs(prompt): allow durable work notes --- prompts/claude-paired-room.md | 8 ++++++++ prompts/owner-common-paired-room.md | 9 +++++++++ src/platform-prompts.test.ts | 25 +++++++++++++++++++++++++ 3 files changed, 42 insertions(+) diff --git a/prompts/claude-paired-room.md b/prompts/claude-paired-room.md index 39ad6d9..6c2c384 100644 --- a/prompts/claude-paired-room.md +++ b/prompts/claude-paired-room.md @@ -29,6 +29,14 @@ For bugs, outages, failed checks, or unexpected behavior: - 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 +## Durable work notes + +Accept file-backed notes as support for handoff or planning, but do not treat them as verification. + +- Useful notes capture architecture choices, multi-step plans, long debugging evidence, or user-requested design decisions +- Flag notes that are stale, vague, secret-bearing, or process noise for a small hotfix +- Prefer concise notes in an existing docs/plans location over new workflow directories + ## 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 69b8b99..69226f3 100644 --- a/prompts/owner-common-paired-room.md +++ b/prompts/owner-common-paired-room.md @@ -25,6 +25,15 @@ For bugs, outages, failed checks, or unexpected behavior: - 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 +## Durable work notes + +Use short Markdown notes when they materially help handoff or continuity across sessions. + +- Good fits: broad architecture choices, multi-step plans, long debugging evidence, or user-requested design notes +- Bad fits: small hotfixes, routine review loops, transient status updates, or notes that only restate chat +- Use an existing docs/plans location when present; ask before creating a new docs directory +- Keep notes brief: goal, decisions, evidence, next steps, and exact file/command references + ## 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 a18f312..2583441 100644 --- a/src/platform-prompts.test.ts +++ b/src/platform-prompts.test.ts @@ -124,4 +124,29 @@ describe('platform-prompts', () => { expect(prompt).not.toContain('The Four Phases'); } }); + + it('keeps file-backed note guidance optional and lightweight', () => { + 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('## Durable work notes'); + expect(prompt).toContain('multi-step plans'); + expect(prompt).toContain('long debugging evidence'); + expect(prompt).toContain('existing docs/plans location'); + expect(prompt).not.toContain('docs/superpowers'); + expect(prompt).not.toContain('Every plan MUST'); + } + }); });