Custom prompt template for Pi coding agent's Interview extension (https://github.com/nicobailon/pi-interview-tool). Deeply reviews a plan/spec through multiple interview waves, asking non-obvious questions about architecture, UX, tradeoffs, and implementation details, then updates the plan with answers woven in.

double-check-clarify-plan.md

description	args
Interview deeply about a plan/spec, asking non-obvious questions, then update the plan	name description required plan Path to the plan/spec file to review true

Deep Plan Review with Interview Waves

Read the plan/spec and interview the user in-depth about technical implementation, UI & UX, concerns, tradeoffs, and edge cases. Questions must be non-obvious and substantive.

Process

Step 1: Read and Understand

Read $ARGS.plan completely. Also read any referenced files (existing code, related specs, similar implementations in the codebase) to understand context.

Step 2: Analyze for Gaps

Look for areas that need clarification:

• Ambiguous technical decisions
• Missing error handling strategies
• Edge cases not addressed
• UX decisions that could go multiple ways
• Performance implications not discussed
• Security considerations
• Integration points with existing code
• Migration or backwards compatibility concerns
• Testing strategy gaps
• Scope boundaries unclear

Step 3: First Interview Wave (Architecture & Technical)

Use the interview tool to ask about high-level design:

• Component boundaries and responsibilities
• Data flow and state management
• Error propagation strategy
• Concurrency/async considerations
• External dependencies and their failure modes

Write questions to a temp JSON file, then call interview:

Write questions to /tmp/plan-review-q1.json
interview({ questions: "/tmp/plan-review-q1.json" })

Questions must be:

• Non-obvious (not answerable by reading the plan)
• Specific (not vague "is this good?")
• Decision-focused (present tradeoffs, ask for preference)

Step 4: Second Interview Wave (UX & Behavior)

Based on first wave answers, dig into user-facing behavior:

• Edge case handling visible to users
• Error messages and feedback
• Default behaviors and configurability
• Keyboard shortcuts and accessibility
• Visual design decisions

Step 5: Third Interview Wave (Concerns & Tradeoffs)

Surface potential issues and validate assumptions:

• "The plan assumes X, but what if Y?"
• "This approach trades off A for B - is that acceptable?"
• "I noticed the plan doesn't address Z - intentional or oversight?"
• Performance vs complexity tradeoffs
• Scope creep risks

Step 6: Fourth Interview Wave (Implementation Details)

Get into the weeds on anything still unclear:

• Specific algorithms or data structures
• Config schema details
• File format decisions
• Naming conventions
• Testing approach

Step 7: Update the Plan

After all interview waves complete, update $ARGS.plan with:

• Answers integrated into relevant sections
• New sections for previously unaddressed topics
• Clarifications on ambiguous points
• Decisions documented with rationale

Do NOT add a "Q&A" dump section - weave answers naturally into the plan.

Step 8: Summary

Report what was clarified and updated, with specific section references.

Question Quality Guidelines

Good questions:

• "The plan shows flood protection with token bucket, but what should happen to queued messages if the user disconnects mid-queue?"
• "For nick collision, the plan tries altNicks then appends underscore. Should there be a max retry limit before giving up entirely?"
• "Buffer scrollback is capped at 1000 messages by default. Should older messages be persisted to disk, or is loss acceptable?"

Bad questions (too obvious):

• "Should the IRC client connect to servers?" (yes, obviously)
• "Is TLS important?" (already in the plan)
• "Should we handle errors?" (of course)

Skip Waves If Empty

If a wave has no substantive questions, skip it rather than asking filler questions. Quality over quantity.

$@