sharkitect-solutions/deep-interview

Deep Interview: Socratic Requirements Clarification

Expose what the user hasn't thought about BEFORE any code gets written. This skill uses structured Socratic questioning to transform vague ideas into buildable requirements briefs.

File Index

| File | Load When | Do NOT Load | |---|---|---| | references/dimension-rubric.md | Scoring clarity, assessing thresholds, weighting dimensions | Questioning phase (focus on asking, not scoring) | | references/question-bank.md | Need specific probing questions for a dimension | Already past the questioning phase | | references/assumption-patterns.md | Identifying hidden assumptions by domain | Simple, well-scoped requests | | references/ontology-tracking.md | Entities shifting across rounds, need convergence method | Entities already stable for 2+ rounds |

Scope Boundary

| Request | This Skill | Use Instead | |---|---|---| | "I want to build X" (vague) | YES | - | | "Help me think through this idea" | YES | - | | "/deep-interview" | YES | - | | "What am I missing?" | YES | - | | "Build X with these exact specs [detailed]" | NO | superpowers:brainstorming or writing-plans | | "Fix this bug" | NO | superpowers:systematic-debugging | | "Review this code" | NO | code-reviewer | | "Plan the implementation of [clear spec]" | NO | superpowers:writing-plans | | "Explore approaches for [clear requirement]" | NO | superpowers:brainstorming |

<HARD-GATE> Do NOT start implementation, write code, create files, scaffold projects, or invoke any build skill until the interview produces a requirements brief with ALL dimensions scoring 7+ out of 10. If the user says "just build it" mid-interview, present the current clarity scores and explain which gaps will cause rework. Let them decide, but make the cost visible. </HARD-GATE>

When to Auto-Suggest

Detect these signals and suggest a deep interview before proceeding:

• Request uses abstract nouns without specifics ("a system", "a platform", "a tool")
• No success criteria mentioned (how will we know it works?)
• No constraints mentioned (timeline, budget, tech stack, users)
• Scope is unbounded ("and also...", "with everything", "full-featured")
• User references something they saw without specifying what they want from it
• Multiple independent subsystems in a single sentence

Auto-suggest phrasing: "This sounds like it has some undefined dimensions. Want me to run a quick deep interview to surface what we might be missing? It takes 3-5 questions."

The Six Clarity Dimensions

Every requirement has six dimensions. Score each 1-10 during the interview.

| Dimension | Weight | What It Measures | Score 1 (Vague) | Score 10 (Crystal) | |---|---|---|---|---| | Scope | 25% | What's in, what's out | "Build me an app" | "CRUD API for tasks with 3 endpoints, no auth" | | Success Criteria | 20% | How we know it's done | "It should work well" | "Returns 200 on valid input, 422 on bad input, <100ms p95" | | Constraints | 20% | What limits the solution | None mentioned | "Python stdlib only, must run on Windows, no external APIs" | | Edge Cases | 15% | What happens when things go wrong | Not considered | "Empty input returns [], malformed JSON returns 400, rate-limited after 100 req/min" | | Dependencies | 10% | What this connects to | Unknown | "Reads from Supabase tasks table, called by n8n webhook node" | | User Context | 10% | Who uses this and why | "Users" | "Internal team of 3, accessed via CLI, used daily for task triage" |

Clarity threshold: Weighted average >= 7.0. Below 7.0, keep asking. Above 7.0, present the brief and transition to brainstorming.

The Interview Process

Phase 1: Quick Assessment (1 message)

Brownfield detection: Before scoring, check if the request involves modifying an existing system. Look for signals: the CWD has source code, the user references existing files/features, or says "add to", "change", "extend", "fix". If brownfield:

• Use Glob/Grep/Read to explore the relevant codebase area FIRST
• Cite what you found when asking questions: "I see JWT auth in src/auth/. Should this feature extend that, or use a different approach?" Never ask the user what the code already reveals.
• Brownfield projects score Dependencies higher (existing integrations matter more)

Read the user's request. Internally score all six dimensions. Identify the 2-3 lowest-scoring dimensions. Do NOT dump all six scores on the user -- pick the biggest gaps.

Phase 2: Socratic Probing (3-7 questions)

Ask ONE question at a time. Each question targets the lowest-scoring dimension.

Question targeting rule: Always probe the dimension where (weight * gap_to_10) is largest. A scope dimension at 4 (weight 25%, gap 6) contributes 1.5 to the deficit. A user context dimension at 4 (weight 10%, gap 6) contributes 0.6. Probe scope first -- it moves the needle 2.5x more per question.

Rules for questions:

1. One question per message. Never batch questions. Wait for the answer.
2. Offer choices when possible. "Would this be (a) internal tool, (b) customer-facing, or (c) both?" is better than "Who uses this?"
3. Reflect back before asking. "So it sounds like [X]. Given that, [question]?" shows you're listening.
4. Name the assumption you're testing. "I'm assuming [X] -- is that right, or...?" surfaces hidden assumptions the user didn't know they had.
5. Stop when clarity threshold is met. Don't over-interview. 7.0 weighted average means GO.
6. Escalate, don't repeat. If a dimension stays vague after 2 questions, flag it explicitly: "We still don't have clear [dimension]. This will cause rework later. Should we define it now or accept the risk?"
7. Cap at 7 questions. If clarity is 6.5+ after 5 questions, present the brief with noted risks rather than drilling further. See "The Over-Interviewer" anti-pattern below.
8. Track entity stability. After each answer, note the key entities (nouns) the user has named: systems, objects, users, data types. If the same concept gets different names across answers ("workflow" then "pipeline" then "queue"), the user's mental model is unstable. When entities shift across 2+ rounds, stop asking about features and ask: "You've described this as [X], [Y], and [Z]. Which one IS it, and which are views of the same thing?" Stable entities = ready to move forward. Shifting entities = keep probing scope. See references/ontology-tracking.md for the full convergence method.

Phase 3: Assumption Exposure

After scoring hits 6.0+, present the assumptions you've detected:

## Detected Assumptions

1. **[Assumption]** -- You haven't explicitly stated [X]. I'm assuming [Y].
   Is that correct, or should we define this differently?

2. **[Assumption]** -- The request implies [X], but [alternative Z] is also
   possible. Which do you intend?

3. **[Assumption]** -- No mention of [X]. Common pitfall: teams skip this
   and discover it during integration. Want to address it now?

Each assumption the user confirms or corrects improves the clarity score.

Phase 4: Requirements Brief

When clarity threshold (7.0) is reached, produce this deliverable:

## Requirements Brief: [Title]

**Clarity Score:** [weighted average] / 10

### Scope
- **In scope:** [bullet list]
- **Out of scope:** [bullet list]
- **Deferred:** [bullet list with reasoning]

### Success Criteria
- [ ] [Measurable criterion 1]
- [ ] [Measurable criterion 2]
- [ ] [Measurable criterion 3]

### Constraints
- [Constraint 1]
- [Constraint 2]

### Edge Cases
- [Edge case 1] -> [Expected behavior]
- [Edge case 2] -> [Expected behavior]

### Dependencies
- [Dependency 1] -- [status: exists/needs-building/unknown]
- [Dependency 2] -- [status]

### User Context
- **Who:** [description]
- **How:** [access method]
- **When:** [frequency/triggers]
- **Why:** [motivation]

### Assumptions (Confirmed)
- [Assumption 1] -- confirmed by user
- [Assumption 2] -- confirmed by user

### Risks
- [Risk 1] -- [mitigation or accepted]

Phase 5: Handoff

After the user approves the brief:

1. Save the brief to docs/superpowers/specs/YYYY-MM-DD-<topic>-requirements.md
2. Invoke superpowers:brainstorming with the brief as input context
3. The brainstorming skill handles design exploration from there

State Persistence

Save after every round. Write interview state to .tmp/deep-interview-state.json:

{
  "topic": "brief title",
  "started": "2026-04-12T14:30:00Z",
  "round": 3,
  "scores": {"scope": 8, "success": 5, "constraints": 7, "edge_cases": 3, "dependencies": 6, "user_context": 9},
  "weighted_avg": 6.2,
  "entities": ["Task", "User", "Workflow"],
  "entity_stable_rounds": 1,
  "brownfield": false,
  "qa_pairs": [{"q": "...", "a": "..."}, ...]
}

Resume on re-invocation. If .tmp/deep-interview-state.json exists when the skill loads, offer: "Found an in-progress interview about [topic] (round [N], clarity [X]/10). Resume or start fresh?" If resume, load the state and continue from the next question.

Clean up on completion. Delete the state file after the requirements brief is saved and approved. Don't leave stale state for the next interview.

Anti-Pattern: "The Premature Builder"

The #1 failure mode: skipping requirements clarification because the task SEEMS clear.

Detection signals:

• You feel confident you understand after reading one sentence
• The request uses familiar words (API, dashboard, workflow) so you assume standard patterns
• The user is excited and you don't want to slow them down
• You've built something similar before

Why it's wrong: Familiar words mask different intentions. "Build me a dashboard" means wildly different things depending on who's looking at it, what decisions it informs, how often it updates, and what actions it enables. The 5 minutes spent interviewing saves the 2 hours spent rebuilding when assumptions are wrong.

Anti-Pattern: "The Over-Interviewer"

The #2 failure mode: asking so many questions the user disengages.

Detection signals:

• You've asked 5+ questions and clarity is already above 6.5
• The user's answers are getting shorter or more impatient
• You're probing low-weight dimensions (dependencies, user context) when high-weight ones are clear
• You're asking for precision beyond what the task requires (exact millisecond SLAs for an internal script)

Why it's wrong: The interview exists to prevent rework, not to produce a perfect spec. A brief with two noted risks ships faster than a brief that never gets written because the user said "forget it, just build something." Know when 80% clarity is enough to start.

The rule: 7 questions maximum for a moderately scoped request. If you hit question 5 with a weighted average of 6.5+, present the brief with explicit risk notes on the weak dimensions. Let the user decide whether to clarify further or accept the risks.

Rationalization Table

| Rationalization | When It Appears | Why It Is Wrong | |---|---|---| | "The user seems to know what they want" | User speaks confidently about a vague idea | Confidence about WHAT doesn't mean clarity about HOW, WHEN, WHO, or edge cases. Interview the gaps. | | "This is straightforward, no interview needed" | Familiar problem domain | Familiar domains have the MOST hidden assumptions because you fill gaps with your own defaults instead of asking. | | "I don't want to slow the user down with questions" | User seems eager to start | 5 minutes of questions saves 2 hours of rework. The user will thank you for surfacing the blind spot they missed. | | "I'll figure out the details as I build" | Ambiguous scope but clear starting point | Discovering requirements during implementation means rework. Every assumption you don't validate is a potential rebuild. | | "The brainstorming skill will handle requirements" | Requirements overlap with design | Brainstorming explores HOW given clear requirements. This skill defines WHAT. Skipping WHAT makes HOW meaningless. | | "One quick question is enough" | Time pressure | One question covers one dimension. Six dimensions need targeted probing. Under-interviewing leaves 5 blind spots. |

Red Flags Checklist

Before transitioning to brainstorming, verify NONE of these are true:

• [ ] Any dimension scores below 5 (critical gap -- must address)
• [ ] Weighted average below 7.0 (keep interviewing)
• [ ] User said something contradictory that wasn't resolved
• [ ] Scope includes multiple independent systems without decomposition plan
• [ ] Success criteria are subjective ("should work well", "looks good")
• [ ] No edge cases identified (every system has them -- dig harder)
• [ ] Dependencies listed as "unknown" without a plan to resolve
• [ ] Assumptions presented but user didn't confirm or deny
• [ ] Brief was produced but user didn't review and approve it

Integration with Workflow

User Request (vague)
       |
  [deep-interview]  <-- YOU ARE HERE
       |
  Requirements Brief (approved)
       |
  [superpowers:brainstorming]
       |
  Design Spec (approved)
       |
  [superpowers:writing-plans]
       |
  Implementation Plan
       |
  [execution skills]

The deep interview is the FIRST gate. It feeds brainstorming, which feeds planning, which feeds execution. Skipping this gate means every downstream stage inherits unvalidated assumptions.

Example: Before and After

User request: "I want to build a notification system"

Without deep interview: Claude starts building an email notification system with SMTP, HTML templates, and a queue. User wanted Telegram alerts for their 3-person team. 2 hours wasted.

With deep interview (3 questions):

Q1: "Would this be (a) email notifications, (b) push notifications, (c) chat alerts (Slack/Telegram/Discord), or (d) in-app notifications?" A: "Telegram alerts for our team"

Q2: "What triggers an alert? Is it (a) a scheduled check, (b) an event from another system, or (c) manual? And how urgent -- real-time or batched?" A: "When a gap report lands in the inbox. Real-time."

Q3: "I'm assuming the Telegram bot already exists and we just need to send to it. Is that right, or do we need to set up the bot too?" A: "Bot exists, just need the send function"

Clarity scores after 3 questions: Scope: 9, Success: 7, Constraints: 8, Edge Cases: 5, Dependencies: 8, User Context: 9. Weighted average: 7.8. Threshold met.

Result: Requirements brief produced in 2 minutes. Correct system built on first attempt.