Skip to content

OXI-717/ai-native-toolkit / plugins/deep-interview/skills/deep-interview

deep-interview

Verified

Use when a vague task needs a clarification interview and structured brief. Triggers — "clarify task", "define requirements".

Deep Interview — Task Clarification

Clarify a vague task through focused one-at-a-time questions, then produce a structured brief.

Input: $ARGUMENTS

When to use

  • Task is too vague for brainstorming ("make it better", "fix the architecture", "add notifications")
  • Scope is unclear — could be 1 hour or 1 week
  • Multiple interpretations possible
  • User hasn't thought through non-goals or constraints yet

When NOT to use

  • Task is already clear (specific file, specific bug, specific feature)
  • User provided a spec or detailed description
  • Already in brainstorming/planning phase

Process

Phase 1: Context Scan (silent, no output to user)

Before asking any questions:

  1. For the project root and every directory scoped to the task, discover and read each applicable AGENTS.md; where a scope has no AGENTS.md, read its CLAUDE.md fallback. Recursively read the relative files referenced by @ imports in each manifest or imported rule before proceeding.
  2. Check git log for recent work context (last 10 commits)
  3. Scan project structure (top-level dirs, key config files)
  4. If task mentions specific areas — read those files

This gives you context to ask informed questions, not generic ones.

Phase 2: Interview (interactive)

RULES:

  • Ask ONE question at a time. Never dump multiple questions.
  • Wait for answer before asking next question.
  • Questions must be specific and actionable, not philosophical.
  • Use context from Phase 1 to ask informed questions (reference files, patterns, existing code).
  • Skip questions whose answers are obvious from the codebase.
  • Maximum 7 questions total. Stop earlier if picture is clear.
  • After each answer, briefly acknowledge and move to next question.

Question flow (adapt order based on responses, skip what's already clear):

1. Intent

"What's the end result you want? Not how — what should be different when this is done?"

2. Trigger

"What prompted this? A bug, a user request, technical debt, new requirement?"

3. Scope boundary

"What's IN scope and what's explicitly OUT? For example: [give 1-2 concrete examples based on codebase context]"

4. Users / consumers

"Who uses this? End users, other developers, CI/CD, another service?"

5. Constraints

"Any hard constraints? Timeline, compatibility, performance, specific tech stack, must not break X?"

6. Success criteria

"How will you know this is done? What's the minimum that makes it shippable?"

7. Known unknowns

"Anything you're unsure about or worried might be harder than it looks?"

Phase 3: Brief Generation

After all questions answered (or after 7 questions max), generate a structured brief:

# Task Brief: [concise title]

**Generated:** [date]
**Source:** deep-interview session

## Intent
[1-2 sentences: what should change]

## Trigger
[Why now — bug, request, debt, opportunity]

## Scope
**In scope:**
- [concrete item 1]
- [concrete item 2]

**Out of scope:**
- [concrete exclusion 1]
- [concrete exclusion 2]

## Constraints
- [constraint 1]
- [constraint 2]

## Success Criteria
- [ ] [measurable criterion 1]
- [ ] [measurable criterion 2]

## Open Questions
- [anything unresolved]

## Relevant Code
- `path/to/file.ts` — [why relevant]
- `path/to/other.py` — [why relevant]

## Suggested Next Step
[One of: brainstorming, writing-plans, background implementation workflow, direct implementation]

Phase 4: Handoff

Present the brief to user. Then suggest next step based on complexity:

ComplexitySuggested next step
Simple (1-2 files, clear path)"Ready to implement directly"
Medium (clear but multi-file)"Ready for /writing-plans — skip brainstorming"
Complex (architectural decisions needed)"Ready for brainstorming → writing-plans"
Large (multi-day, parallel work)"Ready for brainstorming → writing-plans → parallel implementation"

Do NOT auto-invoke the next step. Present the brief, suggest the step, let the user decide.

If user confirms, save the brief to the project:

  • Save to docs/briefs/[date]-[slug].md (create dir if needed)
  • Or wherever the user prefers

Example Session

User: /deep-interview add notifications to the app

Claude: [reads codebase, finds a web app with no notification system]

Claude: "What kind of notifications? Push notifications to mobile,
        in-app toasts, email, or a chat integration?"

User: "in-app + email"

Claude: "Got it. What events should trigger a notification? I can see
        sign-up, checkout, and password reset flows in the codebase."

[... continues one question at a time ...]

Claude: [generates brief, suggests writing-plans as next step]

Anti-patterns

  • Asking 5 questions at once — defeats the purpose
  • Generic questions not grounded in codebase context — waste of time
  • Going beyond 7 questions — diminishing returns, user gets annoyed
  • Auto-starting brainstorming/planning without user confirmation
  • Writing code or making changes during interview
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 196kUpdated Claude CodeCodexVerifiedInstall