repositories / dotfiles

dotfiles

bugabingas dorkfiles

owned by bugabinga

feat(agent): add devil - structured debate tool for reducing sycophancy

5c152c7e02a2cf3251bb237dfd9eb31ac90bdbbf

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

- devils_advocate tool for stress-testing ideas
- Challenge classification: blocking/addressable/assumed/minor
- Stopping conditions: consensus/blocking_found/max_rounds
- Configurable model, rounds, concession threshold
- Stakeholder focus: security/cost/ux/implementation/ethics/skeptical
- Session-aware docs explaining pi implications

Changed files (3)

pi/agent/extensions/devil/index.ts

Added
new file mode 100644
1 +/**
2 + * Devil's Advocate Extension for Pi
3 + *
4 + * A structured debate tool for stress-testing ideas against a devil's advocate.
5 + * Designed to reduce sycophancy by forcing critical examination.
6 + *
7 + * Usage:
8 + * /devil <your idea> - Start a debate
9 + * Call devils_advocate tool
10 + *
11 + * Configuration (settings.json):
12 + * {
13 + * "devilsAdvocate": {
14 + * "model": "anthropic/claude-haiku-4-5", // Optional: specific model
15 + * "maxRounds": 5, // Maximum debate rounds
16 + * "stoppingConditions": "consensus", // consensus | blocking_found | max_rounds
17 + * "concessionThreshold": 0.7, // 0.0-1.0 for concession detection
18 + * "onBlocking": "surface" // surface | escalate | ignore
19 + * }
20 + * }
21 + *
22 + * Pi Session Implications:
23 + * - Debates are stateless (no persistence between calls)
24 + * - Uses current session's model and API credentials
25 + * - Results are returned as tool output, not added to conversation
26 + * - Context from current conversation is NOT automatically included
27 + */
29 +import { Type } from "@sinclair/typebox";
30 +import { complete, type Message } from "@mariozechner/pi-ai";
31 +import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
33 +const DEVIL_SYSTEM_PROMPT = `You are a devil's advocate in a structured debate. Your goal is to STRESS TEST the proposer's idea by identifying blocking issues.
35 +CLASSIFICATION GUIDE:
36 +- **blocking**: Would prevent the idea from working entirely. Must be addressed before proceeding.
37 +- **addressable**: Valid concern but has known mitigations or workarounds.
38 +- **assumed**: Based on premises that may not hold in all contexts.
39 +- **minor**: Aesthetic preference, stylistic choice, or edge case that won't affect success.
41 +EXAMPLES:
42 +- "This requires authentication that doesn't exist" → blocking
43 +- "Users might find this confusing" → addressable (can add onboarding)
44 +- "This assumes fast internet" → assumed (premise may not hold)
45 +- "The button should be blue not green" → minor (cosmetic, doesn't affect functionality)
47 +RULES:
48 +1. Lead with blocking concerns. Do not waste rounds on minor issues.
49 +2. Be specific: name the exact failure mode, not vague risks.
50 +3. If a defense successfully addresses a concern, acknowledge it and move on.
51 +4. Focus on what would actually break the idea, not theoretical concerns.
53 +Format each challenge as:
54 +### [CLASSIFICATION] Challenge Title
55 +**The concern:** Clear statement of the problem
56 +**What would resolve it:** Specific conditions that would satisfy you
57 +**Current status:** outstanding / resolved / retracted`;
59 +const PROPOSER_SYSTEM_PROMPT = `You are presenting an idea for scrutiny. Your goal is to DEFEND it where valid and ACKNOWLEDGE where it's weak.
61 +RULES:
62 +1. Don't capitulate easily - require specific evidence against your idea
63 +2. Distinguish between "I don't know", "that doesn't apply", and "I've addressed that"
64 +3. If a concern is valid, acknowledge it and explain the mitigation
65 +4. Do not concede to blocking concerns without explaining how you'd address them
67 +For each challenge, respond with:
68 +1. **Your defense**: What defeats or addresses this challenge
69 +2. **Concession** (if valid): Acknowledge what concern remains
70 +3. **Status**: outstanding / resolved
72 +Be specific. "I addressed that" requires explaining how.`;
74 +const SYNTHESIS_SYSTEM_PROMPT = `Analyze this debate and produce an honest summary for a user who needs to make a decision.
76 +CLASSIFICATION SUMMARY:
77 +- **blocking**: Must fix before proceeding
78 +- **addressable**: Valid but has mitigations
79 +- **assumed**: Depends on unverified premises
80 +- **minor**: Not worth fixing
82 +Output format:
84 +## Summary
86 +**Recommendation:** proceed / proceed_with_caution / revise / abandon
88 +### Blocking Issues (must address first)
89 +- [blocking concern] → [what would fix it]
91 +### Addressable Concerns (valid concerns with mitigations)
92 +- [concern] → [mitigation strategy]
94 +### What Survived Scrutiny
95 +- [claims that held up under pressure]
97 +### What Was Conceded
98 +- [acknowledged weaknesses]
100 +### Recommended Next Steps
101 +1. [action item]
102 +2. [action item]`;
104 +// Default settings
105 +const DEFAULT_MAX_ROUNDS = 5;
106 +const DEFAULT_STOPPING_CONDITIONS = "consensus";
107 +const DEFAULT_CONCESSION_THRESHOLD = 0.7;
108 +const DEFAULT_ON_BLOCKING = "surface";
110 +interface DevilSettings {
111 + model?: string;
112 + maxRounds?: number;
113 + stoppingConditions?: "consensus" | "blocking_found" | "max_rounds";
114 + concessionThreshold?: number;
115 + onBlocking?: "surface" | "escalate" | "ignore";
118 +export default async function (pi: ExtensionAPI) {
119 + // Read settings
120 + const settings = pi.settingsManager?.getSettings();
121 + const devilSettings: DevilSettings = settings?.devilsAdvocate ?? {};
123 + // Register the devil's advocate tool
124 + pi.registerTool({
125 + name: "devils_advocate",
126 + label: "Devil's Advocate",
127 + description: `A structured debate tool for stress-testing ideas against a devil's advocate.
129 +Run debates to surface blocking issues before committing to decisions.
131 +Parameters:
132 +- idea: The idea/claim to debate (required)
133 +- context: Key-value pairs for background (optional)
134 +- model: Override model (optional)
135 +- maxRounds: Maximum rounds 1-10 (default: ${devilSettings.maxRounds ?? DEFAULT_MAX_ROUNDS})
136 +- stakeholder: security | cost | ux | implementation | ethics | skeptical
137 +- stoppingConditions: When to stop (default: ${devilSettings.stoppingConditions ?? DEFAULT_STOPPING_CONDITIONS})
138 +- output: full | summary_only (default: summary_only)`,
139 + parameters: Type.Object({
140 + idea: Type.String({
141 + description: "The idea, claim, or decision to debate. Be specific and concrete.",
142 + }),
143 + context: Type.Optional(
144 + Type.Record(Type.String(), Type.String(), {
145 + description: "Background: { problem: \"...\", constraint: \"...\", scale: \"...\" }",
146 + })
147 + ),
148 + model: Type.Optional(Type.String({
149 + description: "Model override (e.g., 'anthropic/claude-haiku-4-5')",
150 + })),
151 + maxRounds: Type.Optional(
152 + Type.Number({ minimum: 1, maximum: 10 })
153 + ),
154 + stakeholder: Type.Optional(
155 + Type.Union([
156 + Type.Literal("security"),
157 + Type.Literal("cost"),
158 + Type.Literal("ux"),
159 + Type.Literal("implementation"),
160 + Type.Literal("ethics"),
161 + Type.Literal("skeptical"),
162 + ])
163 + ),
164 + stoppingConditions: Type.Optional(
165 + Type.Union([
166 + Type.Literal("consensus"),
167 + Type.Literal("blocking_found"),
168 + Type.Literal("max_rounds"),
169 + ])
170 + ),
171 + concessionThreshold: Type.Optional(
172 + Type.Number({ minimum: 0, maximum: 1 })
173 + ),
174 + onBlocking: Type.Optional(
175 + Type.Union([
176 + Type.Literal("surface"),
177 + Type.Literal("escalate"),
178 + Type.Literal("ignore"),
179 + ])
180 + ),
181 + output: Type.Optional(
182 + Type.Union([Type.Literal("full"), Type.Literal("summary_only")])
183 + ),
184 + }),
185 + execute: async (_toolCallId, params, signal, onUpdate, ctx) => {
186 + const {
187 + idea,
188 + context,
189 + model: modelOverride,
190 + maxRounds: maxRoundsParam,
191 + stakeholder,
192 + stoppingConditions: stoppingConditionsParam,
193 + concessionThreshold: concessionThresholdParam,
194 + onBlocking: onBlockingParam,
195 + output = "summary_only"
196 + } = params;
198 + const maxRounds = maxRoundsParam ?? devilSettings.maxRounds ?? DEFAULT_MAX_ROUNDS;
199 + const stoppingConditions = stoppingConditionsParam ?? devilSettings.stoppingConditions ?? DEFAULT_STOPPING_CONDITIONS;
200 + const concessionThreshold = concessionThresholdParam ?? devilSettings.concessionThreshold ?? DEFAULT_CONCESSION_THRESHOLD;
201 + const onBlocking = onBlockingParam ?? devilSettings.onBlocking ?? DEFAULT_ON_BLOCKING;
203 + // Determine which model to use
204 + let model = ctx.model;
206 + if (modelOverride) {
207 + const [provider, modelId] = modelOverride.includes("/")
208 + ? modelOverride.split("/")
209 + : [modelOverride, modelOverride];
210 + const foundModel = ctx.modelRegistry.find(provider, modelId);
211 + if (foundModel) model = foundModel;
212 + } else if (devilSettings.model && ctx.model) {
213 + const [provider, modelId] = devilSettings.model.includes("/")
214 + ? devilSettings.model.split("/")
215 + : [ctx.model.provider, devilSettings.model];
216 + const foundModel = ctx.modelRegistry.find(provider, modelId);
217 + if (foundModel) model = foundModel;
220 + if (!model) {
221 + return {
222 + content: [{ type: "text", text: "Error: No model available. Select a model first with /model." }],
223 + details: { error: "No model" },
224 + };
227 + const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
228 + if (!auth.ok || !auth.apiKey) {
229 + return {
230 + content: [{ type: "text", text: `Error: No API key for ${model.provider}` }],
231 + details: { error: "No API key" },
232 + };
235 + const contextText = context
236 + ? Object.entries(context).map(([k, v]) => `- **${k}**: ${v}`).join("\n")
237 + : "No additional context provided.";
239 + const stakeholderContext = stakeholder
240 + ? `\n\n**Focus:** Challenge specifically from ${stakeholder} perspective.`
241 + : "";
243 + // Stream initial output
244 + onUpdate?.({
245 + content: [{ type: "text", text: `## 🗡️ Devil's Advocate Debate\n\n**Idea:** ${idea}\n\n**Context:**\n${contextText}\n\n**Config:** maxRounds=${maxRounds}, stopping=${stoppingConditions}, blocking=${onBlocking}\n**Model:** ${model.provider}/${model.id}\n\n---\n\n` }],
246 + details: {},
247 + });
249 + try {
250 + const rounds_data: string[] = [];
251 + let blockingIssuesFound = 0;
252 + let consecutiveResolved = 0;
253 + let shouldContinue = true;
255 + for (let i = 1; i <= maxRounds && shouldContinue; i++) {
256 + // Devil's challenge
257 + const devilMessages: Message[] = [
258 + { role: "system", content: [{ type: "text", text: DEVIL_SYSTEM_PROMPT }], timestamp: Date.now() },
259 + { role: "user", content: [{ type: "text", text: `Context:\n${contextText}${stakeholderContext}\n\nIdea: ${idea}\n\nRound ${i}/${maxRounds}. Identify the most blocking concern.` }], timestamp: Date.now() },
260 + ];
262 + const devilResponse = await complete(model, { systemPrompt: "", messages: devilMessages }, { apiKey: auth.apiKey, headers: auth.headers, signal });
263 + const devilOutput = devilResponse.content.filter((c): c is { type: "text"; text: string } => c.type === "text").map(c => c.text).join("\n");
265 + // Count blocking issues
266 + const roundBlockingCount = (devilOutput.match(/\[blocking\]/gi) || []).length;
267 + blockingIssuesFound = Math.max(blockingIssuesFound, roundBlockingCount);
269 + // Proposer's rebuttal
270 + const proposerMessages: Message[] = [
271 + { role: "system", content: [{ type: "text", text: PROPOSER_SYSTEM_PROMPT }], timestamp: Date.now() },
272 + { role: "user", content: [{ type: "text", text: `Your idea: ${idea}\n\nChallenges:\n${devilOutput}\n\nRespond to these challenges.` }], timestamp: Date.now() },
273 + ];
275 + const proposerResponse = await complete(model, { systemPrompt: "", messages: proposerMessages }, { apiKey: auth.apiKey, headers: auth.headers, signal });
276 + const proposerOutput = proposerResponse.content.filter((c): c is { type: "text"; text: string } => c.type === "text").map(c => c.text).join("\n");
278 + rounds_data.push(`### Round ${i}\n\n**Challenge:**\n${devilOutput}\n\n**Your Response:**\n${proposerOutput}`);
280 + // Stream round result
281 + onUpdate?.({
282 + content: [{ type: "text", text: `### Round ${i}/${maxRounds}\n\n**Challenge identified.** Respond above.\n\n` }],
283 + details: { round: i, blockingCount: roundBlockingCount },
284 + });
286 + // Check stopping conditions
287 + const resolvedCount = (proposerOutput.match(/\*\*status\*\*:\s*resolved|status:\s*resolved/gi) || []).length;
288 + const concessionIndicators = (proposerOutput.match(/fair point|good point|you're right|concede|acknowledge/i) || []).length;
289 + const concessionScore = resolvedCount + (concessionIndicators * 0.5);
291 + if (stoppingConditions === "consensus" && concessionScore >= concessionThreshold) {
292 + consecutiveResolved++;
293 + if (consecutiveResolved >= 2) {
294 + shouldContinue = false;
296 + } else if (stoppingConditions === "blocking_found" && roundBlockingCount === 0) {
297 + shouldContinue = false;
298 + } else if (stoppingConditions === "max_rounds") {
299 + // Always continue until max_rounds
300 + shouldContinue = i < maxRounds;
303 + if (resolvedCount > 0) consecutiveResolved++;
306 + // Synthesis
307 + const synthesisMessages: Message[] = [
308 + { role: "system", content: [{ type: "text", text: SYNTHESIS_SYSTEM_PROMPT }], timestamp: Date.now() },
309 + { role: "user", content: [{ type: "text", text: `Idea: ${idea}\n\nDebate (${rounds_data.length} rounds):\n${rounds_data.join("\n\n---\n\n")}` }], timestamp: Date.now() },
310 + ];
312 + const synthesisResponse = await complete(model, { systemPrompt: "", messages: synthesisMessages }, { apiKey: auth.apiKey, headers: auth.headers, signal });
313 + const synthesisOutput = synthesisResponse.content.filter((c): c is { type: "text"; text: string } => c.type === "text").map(c => c.text).join("\n");
315 + // Parse recommendation
316 + const recMatch = synthesisOutput.match(/\*\*recommendation\*\*:\s*(\w+)/i);
317 + let recommendation = "proceed_with_caution";
318 + if (recMatch) {
319 + recommendation = recMatch[1].toLowerCase();
320 + if (!["proceed", "proceed_with_caution", "revise", "abandon"].includes(recommendation)) {
321 + recommendation = "proceed_with_caution";
325 + // Handle blocking issues based on onBlocking setting
326 + let blockingNote = "";
327 + if (blockingIssuesFound > 0 && onBlocking === "escalate") {
328 + blockingNote = `\n\n⚠️ **${blockingIssuesFound} blocking issue(s) found.** Review before proceeding.`;
329 + } else if (blockingIssuesFound > 0 && onBlocking === "ignore") {
330 + blockingNote = "";
333 + const outputText = output === "full"
334 + ? `## Full Debate\n\n${rounds_data.join("\n\n---\n\n")}\n\n---\n\n## Summary\n\n${synthesisOutput}${blockingNote}\n\n**Debate:** ${rounds_data.length} rounds | **Blocking issues:** ${blockingIssuesFound}`
335 + : `${synthesisOutput}${blockingNote}\n\n*Debate: ${rounds_data.length} rounds | Blocking: ${blockingIssuesFound}*`;
337 + return {
338 + content: [{ type: "text", text: outputText }],
339 + details: { recommendation, rounds: rounds_data.length, blockingIssues: blockingIssuesFound },
340 + };
341 + } catch (error) {
342 + const message = error instanceof Error ? error.message : String(error);
343 + return {
344 + content: [{ type: "text", text: `## Debate Failed\n\nError: ${message}` }],
345 + details: { error: message },
346 + };
348 + },
349 + });
351 + // Register the /devil command
352 + pi.registerCommand("devil", {
353 + description: "Start a devil's advocate debate",
354 + handler: async (args, ctx) => {
355 + const idea = args.trim();
356 + if (!idea) {
357 + ctx.ui?.notify("Usage: /devil <your idea>", "error");
358 + return;
360 + await ctx.tools?.invoke("devils_advocate", {
361 + idea,
362 + maxRounds: devilSettings.maxRounds ?? DEFAULT_MAX_ROUNDS,
363 + stoppingConditions: (devilSettings.stoppingConditions as any) ?? DEFAULT_STOPPING_CONDITIONS,
364 + });
365 + },
366 + });

pi/agent/extensions/devil/types.ts

Added
new file mode 100644
1 +/**
2 + * Types for the Devil's Advocate debate tool
3 + */
5 +export interface DebateChallenge {
6 + id: string;
7 + claim: string;
8 + severity: {
9 + premise_fatality: number; // 0-1: destroys entire idea?
10 + scope_impact: number; // 0-1: how much of idea affected?
11 + reversibility: number; // 0-1: can idea be amended?
12 + evidence_weight: number; // 0-1: quality of challenge
13 + };
14 + weighted_impact: number; // computed: weighted sum
15 + confidence: {
16 + initial: { point: number; range: [number, number] };
17 + post_rebuttal: {
18 + point: number;
19 + range: [number, number];
20 + shift_reason: string;
21 + };
22 + };
23 + resolution: "resolved" | "contested" | "unresolved";
26 +export interface DebateRound {
27 + round_id: number;
28 + challenges: string[];
29 + rebuttals: string[];
30 + new_information: Array<{
31 + claim: string;
32 + novelty_score: number; // 0-1
33 + significance: "major" | "minor" | "none";
34 + }>;
35 + round_shift_detected: boolean;
38 +export interface RemainingTension {
39 + description: string;
40 + affected_claims: string[];
41 + requires_human_judgment: boolean;
44 +export interface StrongestObjection {
45 + objection: string;
46 + effectiveness_score: number; // 0-1
47 + why_effective: string;
50 +export interface DebateResult {
51 + idea: string;
52 + rounds: DebateRound[];
53 + challenges: DebateChallenge[];
54 + strongest_objection: StrongestObjection;
55 + remaining_tensions: RemainingTension[];
56 + confidence_delta: number; // -1 to +1
57 + recommendation: "proceed" | "revise" | "abandon" | "proceed_with_caution";
60 +export interface DevilsAdvocateOptions {
61 + /** The idea/claim/decision to debate */
62 + idea: string;
63 + /** Background context */
64 + context?: Record<string, string>;
65 + /** Number of challenge-response rounds (default: 3) */
66 + rounds?: number;
67 + /** Challenge style */
68 + perspective?: "strongest" | "naive" | "expert" | "contrarian";
69 + /** Include confidence calibration (default: true) */
70 + confidence_mode?: boolean;
71 + /** Track information novelty per round (default: true) */
72 + track_novelty?: boolean;
73 + /** Output mode */
74 + output?: "full" | "critique_only";
77 +export const SEVERITY_WEIGHTS = {
78 + premise_fatality: 0.4,
79 + scope_impact: 0.3,
80 + reversibility: 0.2,
81 + evidence_weight: 0.1,
82 +};
84 +export function computeWeightedImpact(
85 + severity: DebateChallenge["severity"]
86 +): number {
87 + return (
88 + severity.premise_fatality * SEVERITY_WEIGHTS.premise_fatality +
89 + severity.scope_impact * SEVERITY_WEIGHTS.scope_impact +
90 + severity.reversibility * SEVERITY_WEIGHTS.reversibility +
91 + severity.evidence_weight * SEVERITY_WEIGHTS.evidence_weight
92 + );

pi/agent/tools/devils_advocate.md

Added
new file mode 100644
1 +# devils_advocate
3 +A structured debate tool for stress-testing ideas against a devil's advocate. Designed to reduce sycophancy by forcing critical examination of decisions before commitment.
5 +---
7 +## Quick Start
9 +```bash
10 +pi
11 +/devil we should switch to microservices
12 +```
14 +Or call the tool directly with parameters.
16 +---
18 +## Pi User Implications
20 +### Session Behavior
22 +| Aspect | Behavior |
23 +|--------|----------|
24 +| **Session state** | Debates are stateless. Each call is independent. |
25 +| **Conversation history** | Debate results are NOT automatically added to the conversation. |
26 +| **Model** | Uses the currently selected model (or configured model). |
27 +| **Context** | Does NOT automatically include current conversation context. You must pass it explicitly. |
28 +| **API credentials** | Uses current session's API keys. |
29 +| **Tool results** | Displayed inline, stored in tool details, but not in conversation history unless you add them. |
31 +### When to Use
33 +**Good use cases:**
34 +- Before implementing architectural decisions
35 +- When you're unsure about a direction and want pushback
36 +- After getting too much agreement (sign of sycophancy)
37 +- To document concerns for stakeholders
39 +**Not ideal for:**
40 +- Quick questions (overhead too high)
41 +- When you already have strong disagreement (you don't need a devil)
42 +- Sensitive topics where disagreement feels personal
44 +### Integration with Workflow
46 +```
47 +1. You're working on something
48 +2. You get suspicious agreement → /devil <your idea>
49 +3. Review blocking issues
50 +4. Decide: proceed, revise, or abandon
51 +5. Continue with confidence (or a better idea)
52 +```
54 +### Passing Context
56 +Because debates don't auto-include conversation context:
58 +```javascript
59 +// Good: Explicit context
60 +devils_advocate({
61 + idea: "Add authentication to this endpoint",
62 + context: {
63 + current_approach: "API key in query params",
64 + security_requirements: "Need OAuth for third-party access",
65 + timeline: "Must ship by Friday"
66 + }
67 +})
69 +// Bad: Missing context (devil won't know your constraints)
70 +devils_advocate({
71 + idea: "Add authentication"
72 +})
73 +```
75 +---
77 +## Configuration
79 +Add to `~/.pi/agent/settings.json`:
81 +```json
83 + "devilsAdvocate": {
84 + "model": "anthropic/claude-haiku-4-5",
85 + "maxRounds": 5,
86 + "stoppingConditions": "consensus",
87 + "concessionThreshold": 0.7,
88 + "onBlocking": "surface"
89 + }
91 +```
93 +### Settings Reference
95 +| Setting | Type | Default | Description |
96 +|---------|------|---------|-------------|
97 +| `model` | string | current model | Model for debates. Use cheaper models for speed. |
98 +| `maxRounds` | number | 5 | Maximum debate rounds (1-10). |
99 +| `stoppingConditions` | string | "consensus" | When to stop debating. |
100 +| `concessionThreshold` | number | 0.7 | How much concession triggers early stop (0.0-1.0). |
101 +| `onBlocking` | string | "surface" | What to do with blocking issues. |
103 +### Stopping Conditions
105 +| Value | Behavior |
106 +|-------|----------|
107 +| `consensus` | Stop after 2 consecutive rounds with significant resolutions. |
108 +| `blocking_found` | Stop as soon as no blocking issues remain. |
109 +| `max_rounds` | Always run full `maxRounds`. |
110 +| `user_stops` | (Future: user-controlled stopping.) |
112 +### On Blocking Behavior
114 +| Value | Behavior |
115 +|-------|----------|
116 +| `surface` | Always show blocking issues in output. |
117 +| `escalate` | Add warning if blocking issues found. |
118 +| `ignore` | Don't flag blocking issues (not recommended). |
120 +---
122 +## Parameters
124 +```javascript
125 +devils_advocate({
126 + idea: string, // Required: what to debate
127 + context?: object, // Optional: { key: "value" } pairs
128 + model?: string, // Optional: override model
129 + maxRounds?: number, // Optional: 1-10
130 + stakeholder?: string, // Optional: focus area
131 + stoppingConditions?: string, // Optional: when to stop
132 + concessionThreshold?: number, // Optional: 0.0-1.0
133 + onBlocking?: string, // Optional: blocking behavior
134 + output?: string // Optional: "full" or "summary_only"
136 +```
138 +### Stakeholder Focus
140 +| Value | Focus |
141 +|-------|-------|
142 +| `security` | Security concerns, attack vectors, vulnerabilities |
143 +| `cost` | Cost, ROI, resource implications, scaling costs |
144 +| `ux` | User experience, accessibility, friction points |
145 +| `implementation` | Technical complexity, dependencies, maintenance |
146 +| `ethics` | Ethical concerns, societal impact, fairness |
147 +| `skeptical` | General skepticism, challenged assumptions |
149 +---
151 +## Output Format
153 +### Challenge Classification
155 +Each challenge is classified:
157 +| Classification | Meaning | Action |
158 +|---------------|---------|--------|
159 +| **blocking** | Would prevent the idea from working | Must address first |
160 +| **addressable** | Valid concern with known mitigations | Consider mitigations |
161 +| **assumed** | Based on premises that may not hold | Verify assumptions |
162 +| **minor** | Aesthetic or edge case | Not worth debating |
164 +### Recommendation
166 +| Value | Meaning |
167 +|-------|---------|
168 +| `proceed` | No blocking issues, idea holds up |
169 +| `proceed_with_caution` | Addressable concerns exist |
170 +| `revise` | Blocking issues require design changes |
171 +| `abandon` | Fundamental flaws identified |
173 +### Example Output
175 +```markdown
176 +## Summary
178 +**Recommendation:** proceed_with_caution
180 +### Blocking Issues (must address first)
181 +- Vendor lock-in → Use abstraction layer or multi-cloud strategy
183 +### Addressable Concerns (valid concerns with mitigations)
184 +- Migration complexity → Use migration tooling (Alembic, Flyway)
186 +### What Survived Scrutiny
187 +- SQLite handles our current read/write volume
188 +- Simple deployment model reduces ops burden
190 +### What Was Conceded
191 +- WAL mode limits concurrent read performance at scale
193 +### Recommended Next Steps
194 +1. Define cloud abstraction layer
195 +2. Benchmark with production data volume
196 +3. Prototype migration strategy
198 +*Debate: 3 rounds | Blocking: 1*
199 +```
201 +---
203 +## Examples
205 +### Basic Usage
207 +```
208 +devils_advocate({
209 + idea: "We should migrate from REST to GraphQL"
211 +```
213 +### With Context
215 +```
216 +devils_advocate({
217 + idea: "Use SQLite as primary database",
218 + context: {
219 + scale: "10k concurrent users",
220 + team_size: "5 developers",
221 + requirement: "ACID compliance required",
222 + timeline: "MVP by Q2"
225 +```
227 +### Focused Challenge
229 +```
230 +devils_advocate({
231 + idea: "Add real-time notifications",
232 + stakeholder: "implementation",
233 + stoppingConditions: "blocking_found"
235 +```
237 +### Full Debate with All Parameters
239 +```
240 +devils_advocate({
241 + idea: "Implement OAuth2 authentication",
242 + context: {
243 + current: "API keys in headers",
244 + users: "1000 monthly active",
245 + security_level: "medium"
246 + },
247 + model: "anthropic/claude-sonnet-4-5",
248 + maxRounds: 3,
249 + stakeholder: "security",
250 + stoppingConditions: "consensus",
251 + concessionThreshold: 0.8,
252 + onBlocking: "escalate",
253 + output: "full"
255 +```
257 +---
259 +## Best Practices
261 +### Writing Good Ideas
263 +**Good:**
264 +- "Add rate limiting to the API"
265 +- "Use event sourcing for order management"
266 +- "Implement dark mode across all screens"
268 +**Bad:**
269 +- "Improve performance" (vague)
270 +- "Make it better" (unmeasurable)
271 +- "Add auth" (missing context)
273 +### Providing Context
275 +Context is critical for relevant challenges:
277 +```
278 +// Include relevant constraints
279 +context: {
280 + current_approach: "What you're doing now",
281 + constraints: "What limits you",
282 + requirements: "What must be preserved",
283 + timeline: "When it needs to ship"
285 +```
287 +### Interpreting Results
289 +- **Multiple blocking issues**: Revise the idea significantly
290 +- **Addressable concerns only**: Proceed with mitigations planned
291 +- **Survived full debate**: Good confidence in the idea
292 +- **Early stop (consensus)**: Either the idea is solid or concessions were too easy
294 +---
296 +## Limitations
298 +1. **No conversation memory**: Each debate is independent
299 +2. **LLM classification**: Challenge classification depends on model interpretation
300 +3. **Concession detection**: Keyword matching can be fooled
301 +4. **No escalation actions**: Blocking issues are surfaced, not acted upon
302 +5. **Model-dependent quality**: Challenge quality varies by model
304 +---
306 +## Troubleshooting
308 +### "No model available"
309 +- Select a model first with `/model`
310 +- Or configure `devilsAdvocate.model` in settings
312 +### "Debate took too long"
313 +- Reduce `maxRounds`
314 +- Use a faster model (haiku vs opus)
315 +- Use `stoppingConditions: "blocking_found"`
317 +### "Challenges aren't relevant"
318 +- Provide more specific `context`
319 +- Use `stakeholder` to focus the challenge domain
320 +- Refine your `idea` to be more specific
322 +### "Too many minor challenges"
323 +- Use `stakeholder: "skeptical"` for priority concerns
324 +- Add `context.constraints` to narrow scope
326 +---
328 +## Related
330 +- `/compact` - Summarize conversation (use after debate)
331 +- `/tree` - Review decision history
332 +- `/fork` - Branch on different decisions