Leverage-point analysis for failed prompts. Determines whether the fix belongs at the plan, prompt, or code level before generating any fix. Use when a prompt fails verification, a checkpoint catches an issue, fix attempts aren't working, or the user says "debug", "why did this fail", "investigate".
Leverage-point analysis for failed prompts. Determines whether the fix belongs at the plan, prompt, or code level before generating any fix. Use when a prompt fails verification, a checkpoint catches an issue, fix attempts aren't working, or the user says "debug", "why did this fail", "investigate".
aliases
["conducty-debug","debug"]
tags
["conducty/skill","conducty/debug"]
cluster
conductor
version
1.0.0
origin
robertbarclayy/conducty (MIT)
Conducty Debug — Leverage Point Analysis
When something fails, the first question is not "what's wrong with the code?" It's "where is the highest leverage point to fix this?" A failure might be a code bug, a prompt quality problem, a plan assumption error, or a systemic issue affecting multiple prompts. Fixing at the wrong level wastes retries.
The Leverage Hierarchy
Fix at the highest level that applies:
Plan assumptions → fixes the most, prevents future failures
↓
Prompt quality → fixes this prompt and similar future prompts
↓
Code bug → fixes this specific failure only
Plan-level fix: The design was wrong, the acceptance criteria were incorrect, or the context was insufficient. A code fix won't help because the code was implementing the wrong thing correctly. Signal: the tracer failed, or multiple prompts in the same group fail for related reasons.
Prompt-level fix: The prompt was vague, missing context, had no no-go zones, or specified the wrong approach. The code did what the prompt said, but the prompt said the wrong thing. Signal: spec review passes but verification fails, or the implementer was BLOCKED/NEEDS_CONTEXT.
Code-level fix: The prompt was clear and correct, but the implementation had a bug. This is the only case where a traditional "fix the code" approach is appropriate. Signal: the failure is in specific logic, not in misunderstanding.
The Four Phases
Phase 1: Classify the Failure
Before doing anything else, determine the leverage point:
Read the failure output carefully. What exactly failed? Not "tests fail" but which test, which assertion, what value.
Compare failure against the prompt. Did the implementer build what the prompt asked for? If yes, the problem is the prompt or the plan, not the code. If no, it might be a code bug.
Check if this is systemic. Are other prompts in the same group failing? Do they share assumptions, context, or dependencies? If 2+ prompts fail in the same group, suspect a plan-level issue before investigating individual code bugs.
Classify:
Plan-level: Tracer failed, multiple related failures, design assumptions don't hold
Prompt-level: Agent was BLOCKED/NEEDS_CONTEXT, verification fails despite spec compliance, prompt smells visible in retrospect
Code-level: Clear implementation bug in otherwise well-specified work
Phase 2: Investigate Root Cause
Investigation depends on the leverage level. Use Read, Grep, Glob, and Bash (git diff, git log) to gather evidence — never guess.
For plan-level issues:
Re-read the design doc from [[conducty-shape]]. What assumption doesn't hold?
Check the project context file — is it stale or incomplete?
Was the complexity underestimated? Was the appetite realistic?
Would a different decomposition avoid this failure?
For prompt-level issues:
Check for prompt smells (see [[conducty-tdd]]): vague acceptance, missing context, mixed concerns, no verification, unbounded scope
Was the no-go zone clear enough? Did the agent creep outside scope?
Was the characterization step present for existing code modifications?
Would a different prompt structure have prevented this?
For code-level issues:
Read error messages and stack traces completely
Check what the prompt actually changed (git diff via Bash)
Trace data flow: where does the bad value originate? (Grep)
Find working examples of similar code in the same codebase
Compare what's different between working and broken
Phase 3: Hypothesis and Minimal Test
Form a single hypothesis. "The root cause is X because Y." Be specific.
Design the minimal verification. What's the smallest thing you can check to confirm or deny the hypothesis?
Test it. One variable at a time. Don't fix multiple things at once.
If wrong: Form a new hypothesis. Don't pile on fixes.
Phase 4: Generate the Fix
The fix depends on the leverage level:
Plan-level fix:
Revise the design or plan assumptions
May require re-running [[conducty-shape]] for the affected goal
May require restructuring the group
Update the active plan note before generating new prompts
Prompt-level fix:
Rewrite the prompt with the missing context, clearer criteria, or better approach
Add the prompt smell that was missed to the improvement log
The fix prompt should reference the original failure: "This prompt failed because [root cause]. The rewritten version addresses this by [specific change]."
Code-level fix:
Generate a root-cause-informed fix prompt:
Fix P{N}: {original description}
**Root cause**: {what was actually wrong, with evidence}
**Leverage point**: Code — the prompt was correct, the implementation had a bug
**What went wrong**: {the specific failure}
**Fix required**:
- {path/to/file} — {exact change needed and why}
**Do NOT**:
- {wrong fix that addresses the symptom}
- {scope creep that goes beyond the fix}
**Verification**: `{original verification}` AND confirm {specific fix evidence}
Circuit Breaker: 3 Retries
If a prompt has Retries >= 2 and this would be attempt #3:
STOP. Do not generate another fix.
This pattern indicates the fix is at the wrong leverage level. Three code-level fixes that don't work means the problem is at the prompt or plan level:
Each fix reveals new issues in different places → design assumption is wrong
Fixes require changes outside the prompt's scope → decomposition is wrong
Each fix creates new symptoms → the approach itself is flawed
Instead:
Set Status to blocked
Summarize: what was tried, what happened each time, what pattern you see
Identify which higher leverage level the problem actually belongs to
Present to the user with a recommendation: revise the design, split the prompt, or take a different approach entirely
Pattern Library
After resolving a failure, prepend an entry to [[Failure Patterns]] (the accumulating note in the vault — see [[conducty-obsidian]]):
### {YYYY-MM-DD HHmm} — {brief description}-**Plan**: [[Plan YYYY-MM-DD HHmm Topic]]
-**Prompt**: see [[Prompt Log]] entry P{N}
-**Leverage point**: plan / prompt / code
-**Symptom**: {what the failure looked like}
-**Root cause**: {what was actually wrong}
-**Fix**: {what resolved it}
-**Prevention**: {what would prevent this in future prompts}
The pattern library is read by [[conducty-plan]] (Step 1) and [[conducty-improve]] to prevent repeat failures. A pattern that appears twice is a process gap, not bad luck. Prepend new entries (newest at top); never delete old ones.
Systemic Failure Detection
When investigating a single failure, also check for systemic issues:
2+ failures in the same group with related symptoms → likely a shared assumption problem
Failures across groups in the same project → likely stale context or incorrect architecture understanding
Failures across projects → likely a prompt template problem
Systemic issues get plan-level or template-level fixes, not individual prompt fixes. Flag them for [[conducty-checkpoint]] and [[conducty-improve]].
