/plan-interview

name: plan-interview
description: |
  Ensures alignment between user and Claude during feature/spec planning through a structured interview process.

  Use this skill when the user invokes /plan-interview before implementing a new feature, refactoring, or any non-trivial implementation task. The skill runs an upfront interview to gather requirements across technical constraints, scope boundaries, risk tolerance, and success criteria before any codebase exploration.

  Do NOT use this skill for: pure research/exploration tasks, simple bug fixes, or when the user just wants standard planning without the interview process.

Plan Interview Skill

Install

gh skill install pskoett/pskoett-skills plan-interview

Fallback using the Agent Skills CLI:

npx skills add pskoett/pskoett-skills/skills/plan-interview

Philosophy

Every skill in this collection is built around a core philosophy — a principle that agents struggle to internalize on their own.

This skill's philosophy: **"Make the change easy, then make the change."**

Agents default to plowing straight through implementation, no matter how tangled the path. They rarely pause to ask: "Would a preparatory refactor make this change simple instead of hard?" Planning is where that question gets asked. During codebase exploration and plan generation, actively look for structural friction — code that makes the target change awkward, brittle, or overly complex. When you find it, the plan should propose a preparatory step: make the change easy first, then make the change itself. Two clean steps beat one heroic slog.

Purpose

Run a structured requirements interview before planning implementation. This ensures alignment between you and the user by gathering explicit requirements rather than making assumptions.

When Invoked

User calls `/plan-interview <task description>`.

**Skip this skill** if the task is purely research/exploration (not implementation).

Interview Process

Phase 1: Upfront Interview (Before Exploration)

Check for the host's structured question tool (`ask_user`, `AskUserQuestion`, or an equivalent). Use it for focused questions that the user can answer before the next planning step. In hosts without a structured question tool, ask the same question directly in chat and pause for the response. Do not fall back to plain chat merely because the host uses a different tool name. Respect the host schema: if the tool accepts only one question per call, ask the domains sequentially rather than bundling them.

Required Question Domains

Cover ALL four domains before proceeding:

1. **Technical Constraints**

• Performance requirements
• Compatibility needs
• Existing patterns to follow
• Architecture understanding (if codebase is unfamiliar)

2. **Scope Boundaries**

• What's explicitly OUT of scope
• MVP vs full vision
• Dependencies on other work

3. **Risk Tolerance**

• Acceptable tradeoffs (speed vs quality)
• Tech debt tolerance
• Breaking change acceptance

4. **Success Criteria**

• How will we know it's done?
• What defines "working correctly"?
• Testing/validation requirements

Question Generation

• Generate questions **dynamically** based on the task - no fixed template
• Group related questions into thematic batches
• **2-3 questions per batch** (do not exceed)
• Continue until you have **actionable specificity** (can describe concrete implementation steps)

Planning Depth Calibration

Before leaving the interview phase, classify the task and choose a planning depth:

• **Simple/trivial** (small bug fix, isolated change): minimal plan, at most 1 refinement pass
• **Moderate** (feature work in known area): standard plan, usually 1-2 refinement passes
• **Complex/high-risk** (multi-file, new architecture, unfamiliar codebase, migrations, auth, concurrency): deep plan with iterative refinement until improvements flatten

Let the user override this (`fast` vs `deep`) if they have a clear preference.

Handling Edge Cases

| Scenario | Action | |----------|--------| | Contradictory requirements | Make a recommendation with rationale, ask for confirmation | | User pivots requirements | Restart interview fresh with new direction | | Interrupted session | Ask user: continue where we left off or restart? |

Anti-Patterns to Avoid

• Do NOT ask variations of the same question
• Do NOT make major assumptions without asking
• Do NOT over-engineer plans for simple tasks

Phase 2: Codebase Exploration

After interview completes, explore the codebase to understand:

• Existing patterns relevant to the task
• Files that will be affected
• Integration points
• Potential risks
• **Structural friction** — Is the current code shape fighting the planned change? Would a preparatory refactor (rename, extract, restructure) make the actual implementation straightforward? If yes, propose it as a distinct first step in the plan.

For complex or unfamiliar projects, do a brief context refresh before deep planning:

• Re-read `AGENTS.md` and `README.md` if present and relevant
• Identify the current architecture boundaries and conventions before refining the plan
• If the session was interrupted or context drifted, refresh these again before another refinement round

Knowledge Audit (Between Exploration and Planning)

Before writing the plan, explicitly ask: **"Does the knowledge needed to complete this task exist somewhere I can reach?"**

For each significant implementation step, classify where the required knowledge lives:

• **Codebase** — Existing patterns, conventions, or code that demonstrates how to do it. Found during exploration.
• **Prompt/context** — User-provided requirements, constraints, or domain knowledge from the interview.
• **Training data** — General programming knowledge, well-known libraries, standard patterns the model reliably knows.
• **Nowhere reachable** — The knowledge isn't in any of the above. The agent wo