# Deep Interview

> Use when the user has a vague, complex, or ambiguous idea that needs thorough requirements gathering before implementation. Triggers on phrases like "deep interview", "interview me", "ask me everything", "don't assume", "make sure you understand", "I have a vague idea", "not sure exactly what I want", or when the user wants mathematically-validated clarity before committing to execution. This is…

- **Type:** Skill
- **Install:** `agentstack add skill-codefriar-claude-skills-deep-interview`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [codefriar](https://agentstack.voostack.com/s/codefriar)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [codefriar](https://github.com/codefriar)
- **Source:** https://github.com/codefriar/claude-skills/tree/main/plugins/deep-interview/skills/deep-interview

## Install

```sh
agentstack add skill-codefriar-claude-skills-deep-interview
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Deep Interview

## Overview

Socratic deep interview with mathematical ambiguity gating. Replaces vague ideas with crystal-clear specifications by asking targeted questions that expose hidden assumptions, measuring clarity across weighted dimensions, and refusing to proceed until ambiguity drops below a configurable threshold (default: 20%).

**Announce at start:** "I'm using the deep-interview skill to thoroughly explore your requirements before planning."

**Relationship to brainstorming:** This skill coexists with `superpowers:brainstorming`. Brainstorming is the standard path for most projects. Deep-interview is for when the idea is genuinely vague, the stakes are high, or the user explicitly wants rigorous requirements gathering with mathematical clarity tracking. Both produce a spec/design doc that feeds into `superpowers:writing-plans`.

**Save specs to:** `docs/plans/YYYY-MM-DD--deep-interview.md`

**Save state to:** `.deep-interview/state.json` (for session resume)

Inspired by the [Ouroboros project](https://github.com/Q00/ouroboros) which demonstrated that specification quality is the primary bottleneck in AI-assisted development.

## When To Use This vs Brainstorming

| Signal | Use brainstorming | Use deep-interview |
|--------|------------------|--------------------|
| User knows roughly what they want | ✅ | |
| User says "I have a vague idea" | | ✅ |
| Simple feature addition | ✅ | |
| Complex system with many unknowns | | ✅ |
| User says "don't assume anything" | | ✅ |
| User wants quick turnaround | ✅ | |
| User wants mathematical clarity tracking | | ✅ |
| Standard project, clear domain | ✅ | |
| Novel domain, unclear entities | | ✅ |

## Core Rules

- Ask **ONE question at a time** — never batch multiple questions
- Target the **WEAKEST clarity dimension** with each question
- Make targeting explicit every round: name the weakest dimension, state its score, explain why the next question aims there
- Gather codebase facts via subagent **BEFORE** asking the user about them
- For brownfield confirmation questions, **cite the repo evidence** (file path, symbol, pattern) instead of asking the user to rediscover it
- Score ambiguity **after every answer** — display transparently
- Do not proceed to spec generation until ambiguity ≤ threshold (default 0.2)
- Allow early exit with a clear warning if ambiguity is still high

## Process

### Phase 1: Initialize

1. **Parse the user's idea** from their message
2. **Detect brownfield vs greenfield:**
   - Dispatch a subagent to check if cwd has existing source code, package files, or git history
   - If source files exist AND the user's idea references modifying/extending something: **brownfield**
   - Otherwise: **greenfield**
3. **For brownfield:** Dispatch subagent to map relevant codebase areas, store as `codebase_context`
4. **Initialize state** — write to `.deep-interview/state.json`:

```json
{
  "interview_id": "",
  "type": "greenfield|brownfield",
  "initial_idea": "",
  "rounds": [],
  "current_ambiguity": 1.0,
  "threshold": 0.2,
  "codebase_context": null,
  "challenge_modes_used": [],
  "ontology_snapshots": []
}
```

5. **Announce the interview:**

> Starting deep interview. I'll ask targeted questions to understand your idea thoroughly before building anything. After each answer, I'll show your clarity score. We'll proceed to planning once ambiguity drops below 20%.
>
> **Your idea:** "{initial_idea}"
> **Project type:** {greenfield|brownfield}
> **Current ambiguity:** 100% (we haven't started yet)

### Phase 2: Interview Loop

Repeat until `ambiguity ≤ threshold` OR user exits early:

#### Step 2a: Generate Next Question

Identify the dimension with the LOWEST clarity score. Generate a question that specifically improves that dimension. State, in one sentence before the question, why this dimension is the bottleneck.

**Question targeting by dimension:**

| Dimension | Question Style | Example |
|-----------|---------------|---------|
| Goal Clarity | "What exactly happens when...?" | "When you say 'manage tasks', what specific action does a user take first?" |
| Constraint Clarity | "What are the boundaries?" | "Should this work offline, or is internet assumed?" |
| Success Criteria | "How do we know it works?" | "If I showed you the finished product, what would make you say 'yes, that's it'?" |
| Context Clarity (brownfield) | "How does this fit?" | "I found JWT auth in `src/auth/` using passport. Should this feature extend that or diverge?" |
| Scope-fuzzy / ontology | "What IS the core thing?" | "You've named Tasks, Projects, and Workspaces. Which is the core entity?" |

Questions should expose **ASSUMPTIONS**, not gather feature lists. If the scope is conceptually fuzzy (entities keep shifting, the user is naming symptoms, the core noun is unstable), switch to an ontology-style question that asks what the thing fundamentally IS.

#### Step 2b: Ask the Question

Present clearly with ambiguity context:

```
Round {n} | Targeting: {weakest_dimension} | Why now: {one_sentence_rationale} | Ambiguity: {score}%

{question}
```

#### Step 2c: Score Ambiguity

After receiving the answer, score clarity across all dimensions (0.0 to 1.0 each):

**Dimensions:**
1. **Goal Clarity** — Is the primary objective unambiguous? Can you state it in one sentence? Can you name key entities and their relationships without ambiguity?
2. **Constraint Clarity** — Are boundaries, limitations, and non-goals clear?
3. **Success Criteria Clarity** — Could you write a test that verifies success? Are acceptance criteria concrete?
4. **Context Clarity** (brownfield only) — Do we understand the existing system well enough to modify it safely?

For each dimension provide: score, one-sentence justification, and what's still unclear (if score 50% field overlap (renamed, not new+removed)
- `new_entities`: not matched by name or fuzzy-match
- `removed_entities`: in previous round, not matched in current
- `stability_ratio`: (stable + changed) / total_entities

Show matching reasoning before reporting stability numbers so the user can sanity-check.

Store ontology snapshot in state.

#### Step 2d: Report Progress

```
Round {n} complete.

| Dimension | Score | Weight | Weighted | Gap |
|-----------|-------|--------|----------|-----|
| Goal | {s} | {w} | {s×w} | {gap or "Clear"} |
| Constraints | {s} | {w} | {s×w} | {gap or "Clear"} |
| Success Criteria | {s} | {w} | {s×w} | {gap or "Clear"} |
| Context (brownfield) | {s} | {w} | {s×w} | {gap or "Clear"} |
| **Ambiguity** | | | **{score}%** | |

**Ontology:** {entity_count} entities | Stability: {ratio} | New: {n} | Changed: {n} | Stable: {n}

**Next target:** {weakest_dimension} — {rationale}

{score ≤ threshold ? "✅ Clarity threshold met! Ready to proceed." : "Focusing next question on: {weakest_dimension}"}
```

#### Step 2e: Update State

Write updated interview state to `.deep-interview/state.json`.

#### Step 2f: Check Soft Limits

- **Round 3+**: Allow early exit if user says "enough", "let's go", "build it"
- **Round 10**: Soft warning: "We're at 10 rounds. Current ambiguity: {score}%. Continue or proceed with current clarity?"
- **Round 20**: Hard cap: "Maximum interview rounds reached. Proceeding with current clarity level ({score}%)."

### Phase 3: Challenge Agents

At specific round thresholds, shift the questioning perspective. Each mode is used **once**, then return to normal Socratic questioning.

**Round 4+ — Contrarian Mode:**
Challenge the user's core assumption. Ask "What if the opposite were true?" or "What if this constraint doesn't actually exist?" Test whether the framing is correct or habitual.

**Round 6+ — Simplifier Mode:**
Probe whether complexity can be removed. Ask "What's the simplest version that would still be valuable?" or "Which constraints are necessary vs. assumed?" Find the minimal viable specification.

**Round 8+ — Ontologist Mode** (if ambiguity still > 0.3):
The tracked entities so far may reveal we're addressing symptoms rather than the core problem. Ask "What IS this, really?" or "Looking at these entities, which one is the CORE concept?" Find the essence by examining the ontology.

### Phase 4: Crystallize Spec

When ambiguity ≤ threshold (or hard cap / early exit), generate the specification and write to `docs/plans/YYYY-MM-DD--deep-interview.md`.

**Spec structure:**

```markdown
# Deep Interview Spec: {title}

## Metadata
- Interview ID: {uuid}
- Rounds: {count}
- Final Ambiguity Score: {score}%
- Type: greenfield | brownfield
- Generated: {timestamp}
- Threshold: {threshold}
- Status: {PASSED | BELOW_THRESHOLD_EARLY_EXIT}

## Clarity Breakdown
| Dimension | Score | Weight | Weighted |
|-----------|-------|--------|----------|
| Goal Clarity | {s} | {w} | {s×w} |
| Constraint Clarity | {s} | {w} | {s×w} |
| Success Criteria | {s} | {w} | {s×w} |
| Context Clarity | {s} | {w} | {s×w} |
| **Total Clarity** | | | **{total}** |
| **Ambiguity** | | | **{1-total}** |

## Goal
{crystal-clear goal statement derived from interview}

## Constraints
- {constraint 1}
- {constraint 2}

## Non-Goals
- {explicitly excluded scope 1}
- {explicitly excluded scope 2}

## Acceptance Criteria
- [ ] {testable criterion 1}
- [ ] {testable criterion 2}
- [ ] {testable criterion 3}

## Assumptions Exposed & Resolved
| Assumption | Challenge | Resolution |
|------------|-----------|------------|
| {assumption} | {how it was questioned} | {what was decided} |

## Technical Context
{brownfield: relevant codebase findings from subagent exploration}
{greenfield: technology choices and constraints}

## Ontology (Key Entities)
| Entity | Type | Fields | Relationships |
|--------|------|--------|---------------|
| {name} | {type} | {fields} | {relationships} |

## Ontology Convergence
| Round | Entity Count | New | Changed | Stable | Stability Ratio |
|-------|-------------|-----|---------|--------|----------------|
| 1 | {n} | {n} | - | - | - |
| 2 | {n} | {new} | {changed} | {stable} | {ratio}% |

## Interview Transcript

Full Q&A ({n} rounds)

### Round 1
**Q:** {question}
**A:** {answer}
**Ambiguity:** {score}% (Goal: {g}, Constraints: {c}, Criteria: {cr})

```

### Phase 5: Handoff to Writing-Plans

After the spec is written, commit the spec file and present execution options:

**"Your spec is ready (ambiguity: {score}%). How would you like to proceed?"**

1. **Write implementation plan (recommended)** — Invoke `superpowers:writing-plans` with the spec file. This creates a detailed implementation plan with bite-sized tasks, then hands off to `superpowers:subagent-driven-development` or `superpowers:executing-plans`.

2. **Refine further** — Continue interviewing to improve clarity (current: {score}%).

**The terminal state is invoking `superpowers:writing-plans`.** Do NOT invoke any implementation skill directly. The deep-interview skill is a requirements skill, not an execution skill.

This mirrors the Superpowers pipeline:
```
deep-interview → writing-plans → subagent-driven-development
```

## Escalation and Stop Conditions

- **Hard cap at 20 rounds**: Proceed with whatever clarity exists, noting the risk
- **Soft warning at 10 rounds**: Offer to continue or proceed
- **Early exit (round 3+)**: Allow with warning if ambiguity > threshold
- **User says "stop", "cancel", "abort"**: Stop immediately, save state for resume
- **Ambiguity stalls** (same score ±0.05 for 3 rounds): Activate Ontologist mode to reframe
- **All dimensions at 0.9+**: Skip to spec generation even if not at round minimum

## Resume

If interrupted, the skill reads state from `.deep-interview/state.json` and resumes from the last completed round. If the user says "continue the interview" or "resume deep interview", check for existing state first.

## Ambiguity Score Interpretation

| Score Range | Meaning | Action |
|-------------|---------|--------|
| 0.0 – 0.1 | Crystal clear | Proceed immediately |
| 0.1 – 0.2 | Clear enough | Proceed (default threshold) |
| 0.2 – 0.4 | Some gaps | Continue interviewing |
| 0.4 – 0.6 | Significant gaps | Focus on weakest dimensions |
| 0.6 – 0.8 | Very unclear | May need reframing (Ontologist) |
| 0.8 – 1.0 | Almost nothing known | Early stages, keep going |

## Examples

### Good: Targeting weakest dimension
```
Scores: Goal=0.9, Constraints=0.4, Criteria=0.7
Next question targets Constraints (lowest at 0.4):

Round 3 | Targeting: Constraints | Why now: goal is clear but we have no boundaries defined | Ambiguity: 42%

"You mentioned this should 'work on mobile'. Does that mean a native app,
a responsive web app, or a PWA? And are there specific devices or OS
versions you need to support?"
```

### Good: Gathering codebase facts before asking
```
[dispatches subagent: "find authentication implementation"]
[receives: "Auth is in src/auth/ using JWT with passport.js"]

Round 4 | Targeting: Context | Why now: we need to understand how this fits the existing auth system | Ambiguity: 35%

"I found JWT authentication with passport.js in `src/auth/`.
For this new feature, should we extend the existing auth middleware
or create a separate authentication flow?"
```

### Good: Contrarian mode
```
Round 5 | Contrarian Mode | Targeting: Constraints | Ambiguity: 42%

"You've said this needs to support 10,000 concurrent users. What if it
only needed to handle 100? Would the architecture change fundamentally,
or is the 10K number an assumption rather than a measured requirement?"
```

### Good: Early exit with warning
```
User: "That's enough, just build it"

Current ambiguity is 35% (threshold: 20%). Areas still unclear:
  - Success Criteria: 0.5 (How do we verify the search ranking works correctly?)
  - Constraints: 0.6 (No performance targets defined yet)

Proceeding may require rework. Continue anyway?
  [Yes, proceed] [Ask 2-3 more questions] [Cancel]
```

### Good: Ontology convergence
```
Round 3 entities: User, Task, Project (stability: N/A → first comparison)
Round 4 entities: User, Task, Project, Tag (stability: 75% — 3 stable, 1 new)
Round 5 entities: User, Task, Project, Tag (stability: 100% — all 4 stable)

"Ontology has converged — same 4 entities in 2 consecutive rounds
with no changes. The domain model is stable."
```

### Bad: Batching multiple questions
```
"What's the target audience? And what tech stack? And how should auth work?
Also, what's the deployment target?"
```
Four questions at once — causes shallow answers, makes scoring inaccurate.

### Bad: Asking about codebase facts
```
"What database does your project use?"
```
Should have dispatched a subagent to find this. Never ask the user what the code already reveals.

### Bad: Proceeding despite high ambiguity
```
"Ambiguity is at 45% but we've done 5 rounds, so let's start building."
```
45% ambiguity means nearly half the requirements are unclear. The mathematical gate exists to prevent this.

## Key Principles

- **One question at a time** — Don't overwhelm with multiple questions
- **Expose assumptions, don't gather features** — Questions should challenge, not just collect
- **YAGNI ruthlessly** — The Simplifier challenge agent enforces this
- **Mathematical gating** — Ambiguity score is a hard gate, not a suggestion
- **Transparency** — Show all scores, weights, and reasoning after every round
- **Codebase-first for brownfield** — Always explore before asking

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [codefriar](https://github.com/codefriar)
- **Source:** [codefriar/claude-skills](https://github.com/codefriar/claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-codefriar-claude-skills-deep-interview
- Seller: https://agentstack.voostack.com/s/codefriar
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.