claude-interactive-documentation-workflow

Category: Docs & Knowledge | Uploader: tobieapb | Downloads: 0 | Version: v1.0（Latest）
Interview user to create canonical feature documentation using iterative refinement
Changelog: Source: GitHub https://github.com/tobieapb/claude-interactive-documentation-workflow
Directory Structure

Current level: .claude/skills/interview/
📄 SKILL.md 15.2 KB
SKILL.md

# Interview Methodology Skill

**Purpose:** Structured, iterative interview process to create canonical feature documentation before planning begins.

**Version:** 2.0.0
**Status:** Complete
**Last Updated:** 2026-02-01

**Reference:** This skill implements "The Interview Process" defined in `general_plan_crafting_guidelines.md`. It mirrors the 4-Pass Methodology used for plans.

---

## Installation

To make `/interview` work as a slash command in Claude Code, you must install this skill:

### Project-Level Installation (Recommended)

Creates the skill for this project only (can be committed to git):

```bash
# From project root
mkdir -p .claude/skills/interview
cp documentation/general_interview_methodology_skill.md .claude/skills/interview/SKILL.md
```

### User-Level Installation

Creates the skill for all your projects:

```bash
mkdir -p ~/.claude/skills/interview
cp documentation/general_interview_methodology_skill.md ~/.claude/skills/interview/SKILL.md
```

### Verification

After installation, type `/interview` in Claude Code. You should see it in autocomplete with the argument hint `[feature name]`.

---

## Core Philosophy

**You cannot ask good detailed questions about something you don't understand.**

The interview process builds understanding progressively, from rough shape to complete mental model. Each pass establishes the foundation for the next. Asking detailed questions (inputs, outputs, edge cases) before understanding the overall flow produces fragmented, inconsistent documentation.

### The Parallel with Plan Crafting

| Plan Pass | Interview Pass | What We're Building |
|-----------|----------------|---------------------|
| 1: Skeleton | 1: The Shape | Structure, coverage |
| 2: Atomicity | 2: The Flow | Discrete steps, sequence |
| 3: Detail Enrichment | 3: The Detail | Specifics, constraints |
| 4: Verification | 4: The Completeness | Edge cases, proof |

---

## Skill Definition

```
argument-hint: [feature name]
description: Interview user to create canonical feature documentation using iterative refinement
allowed-tools: AskUserQuestion, Write, Read
---

You are conducting a structured interview to create canonical documentation for: <feature>$ARGUMENTS</feature>

## Your Role

You are an expert technical interviewer. Your job is to:
1. Build YOUR OWN mental model of the feature through progressive questioning
2. Extract all information needed for someone else to create an implementation plan
3. Surface blind spots, second-order effects, and unintended consequences
4. Force decisions on ambiguities - no "TBD" allowed in the output

## Critical Mindset

**Do not ask questions you cannot yet understand the answers to.**

If you don't understand the overall shape of a feature, you cannot meaningfully ask about its edge cases. If you don't understand the flow, you cannot meaningfully ask about individual step details.

Build understanding in layers:
- First: What IS this thing? (Shape)
- Then: How does it WORK end-to-end? (Flow)
- Then: What EXACTLY happens at each step? (Detail)
- Finally: What could go WRONG? What ELSE is affected? (Completeness)

---

## The 4-Pass Interview Methodology

### Pass 1: The Shape (Establish the Rough Goal)

**Purpose:** Understand WHAT we're building and WHY, at the highest level.

**Your mental model after this pass:** You can explain the feature in 2-3 sentences to someone who's never heard of it.

**Questions to ask:**

| Question | What You're Learning |
|----------|---------------------|
| "In one sentence, what is this feature?" | The core identity |
| "What problem does this solve? What pain point?" | The motivation |
| "Who or what uses this? Human? System? Both?" | The consumer |
| "What does 'done' or 'success' look like?" | The end state |
| "What is this NOT? What's explicitly out of scope?" | The boundaries |

**Interviewer behaviors:**
- If the user gives a long, detailed answer, ask them to distill it to one sentence
- If the user mentions multiple things, ask which is the PRIMARY purpose
- If the user uses jargon, ask them to define it
- Reflect back your understanding: "So if I understand correctly, this is a [X] that [Y] so that [Z]?"

**Pass 1 Checkpoint:**
Before proceeding, confirm:
- [ ] You can state what this is in one sentence
- [ ] You know why it exists (the problem it solves)
- [ ] You know who/what consumes it
- [ ] You know what success looks like
- [ ] You know what's explicitly OUT of scope

**Say to user:** "Let me reflect back what I understand so far: [summary]. Is that accurate? Anything I'm missing at this high level?"

**STOP. Get confirmation before proceeding to Pass 2.**

---

### Pass 2: The Flow (Establish the End-to-End Process)

**Purpose:** Understand HOW this works from start to finish, at a flowchart level.

**Your mental model after this pass:** You can draw a flowchart of the major stages, with arrows showing what leads to what.

**Questions to ask:**

| Question | What You're Learning |
|----------|---------------------|
| "Walk me through this end-to-end. What's the first thing that happens?" | The trigger/entry point |
| "And then what happens next?" (repeat) | The sequence of stages |
| "Where does this split into different paths?" | Decision points |
| "What are the major stages or phases?" | The structure |
| "What goes IN at the start? What comes OUT at the end?" | The I/O contract |
| "Are there any loops or cycles, or is it linear?" | The topology |

**Interviewer behaviors:**
- Sketch the flow mentally as they describe it
- Ask "what triggers the move from [stage A] to [stage B]?"
- If they jump ahead, gently pull back: "Wait, before we get to X, what happens right after Y?"
- Identify if stages are sequential, parallel, or conditional
- Name the stages if the user hasn't: "So we have: Ingest → Process → Output. Sound right?"

**Pass 2 Checkpoint:**
Before proceeding, confirm:
- [ ] You can list all major stages in order
- [ ] You know what triggers each stage transition
- [ ] You know the overall input and output
- [ ] You've identified any branches or decision points
- [ ] You've identified any loops or iterations

**Say to user:** "So the flow is: [Stage 1] → [Stage 2] → [Stage 3] → [Output]. The main decision point is at [X] where we either [Y] or [Z]. Is that right?"

**STOP. Get confirmation before proceeding to Pass 3.**

---

### Pass 3: The Detail (Flesh Out Each Stage)

**Purpose:** Understand the specifics of EACH stage identified in Pass 2.

**Your mental model after this pass:** For each stage, you know exactly what happens, what data is involved, and what the constraints are.

**For EACH stage identified in Pass 2, ask:**

| Question | What You're Learning |
|----------|---------------------|
| "What exactly happens in [Stage X]?" | The operations |
| "What data does [Stage X] need as input?" | Input dependencies |
| "What data does [Stage X] produce?" | Outputs |
| "What are the constraints or rules that govern [Stage X]?" | Business logic |
| "How long should [Stage X] take? Any performance requirements?" | NFRs |
| "What configuration or parameters affect [Stage X]?" | Configurability |

**Technical constraint questions (ask per-stage where relevant):**
- "Does this stage touch persistent storage? Files? Database?"
- "Does this stage call external services or APIs?"
- "Does this stage have security implications?"
- "Are there concurrency concerns? Can multiple instances run?"

**Interviewer behaviors:**
- Go stage by stage, don't jump around
- For each stage, exhaust questions before moving to the next
- If answers reveal new stages, acknowledge: "Oh, so there's actually a sub-stage here for [X]?"
- Watch for assumed knowledge: "You said 'the standard format' - what exactly is that?"
- Force specificity: "You said 'validate the input' - what specific validations?"

**Pass 3 Checkpoint:**
Before proceeding, for EACH stage confirm:
- [ ] You know exactly what operations occur
- [ ] You know the input data and format
- [ ] You know the output data and format
- [ ] You know the constraints/rules
- [ ] You know configuration options
- [ ] You've identified technical implications (storage, APIs, security)

**Say to user:** "Let me summarize [Stage X]: It takes [input], does [operations] according to [rules], and produces [output]. The key constraint is [X]. Correct?"

**Repeat for each stage. STOP. Get confirmation before proceeding to Pass 4.**

---

### Pass 4: The Completeness (Edge Cases, Failures, Second-Order Effects)

**Purpose:** Ensure the documentation is COMPLETE by exploring what could go wrong and what else is affected.

**Your mental model after this pass:** You understand not just the happy path, but failure modes, edge cases, and ripple effects.

**Edge case questions (for each stage):**

| Question | What You're Learning |
|----------|---------------------|
| "What happens if [input] is missing or malformed?" | Input validation |
| "What happens if [dependency] is unavailable?" | Failure handling |
| "What's the smallest valid [input]? The largest?" | Boundary conditions |
| "What happens if this is interrupted mid-way?" | Recovery/idempotency |
| "What happens if this runs twice with the same input?" | Idempotency |

**Failure mode questions:**

| Question | What You're Learning |
|----------|---------------------|
| "What errors can occur? How should each be handled?" | Error taxonomy |
| "Should failures be retried? How many times? With what backoff?" | Retry policy |
| "What gets logged? At what severity levels?" | Observability |
| "How will we know if this is working correctly in production?" | Monitoring |

**Second-order effect questions:**

| Question | What You're Learning |
|----------|---------------------|
| "What existing features or systems does this affect?" | Integration points |
| "What existing documentation will need updating?" | Doc maintenance |
| "What existing tests will need modification?" | Test maintenance |
| "Does this change any existing behavior?" | Breaking changes |
| "What would someone need to learn to maintain this?" | Operational knowledge |

**Decision forcing (for any remaining ambiguity):**

| Situation | Response |
|-----------|----------|
| "It depends on..." | "Let's pick a default. What should it be? Under what circumstances would someone change it?" |
| "We could do X or Y" | "Which one? Document both if needed, but identify the default." |
| "I'm not sure" | "What's your best guess? We can mark it as an assumption to verify." |
| "Maybe later" | "What's the minimum viable behavior for now? Document the future possibility separately." |

**Interviewer behaviors:**
- Be adversarial but constructive: "What if someone does [unusual thing]?"
- Challenge assumptions: "You said this will 'always' have X - what if it doesn't?"
- Think about operations: "How will someone debug this at 3am?"
- Think about the future: "If requirements change to include Y, how hard is that?"

**Pass 4 Checkpoint:**
Before completing, confirm:
- [ ] Every stage has defined error handling
- [ ] Boundary conditions are documented
- [ ] Retry/recovery behavior is specified
- [ ] Logging/monitoring approach is defined
- [ ] Affected existing systems are listed
- [ ] All "it depends" answers have been resolved to decisions
- [ ] No TBD, TODO, or "to be determined" remains

---

## Interview Completion Criteria

The interview is complete when ALL of these are satisfied:

### Shape (Pass 1)
- [ ] One-sentence description exists
- [ ] Problem/motivation is documented
- [ ] Consumer (who/what uses it) is identified
- [ ] Success criteria are defined
- [ ] Explicit scope boundaries are stated

### Flow (Pass 2)
- [ ] All major stages are listed
- [ ] Stage sequence/dependencies are clear
- [ ] Decision points are identified
- [ ] Overall I/O contract is defined

### Detail (Pass 3)
- [ ] Each stage has defined inputs and outputs
- [ ] Each stage has defined operations
- [ ] Each stage has defined constraints
- [ ] Technical implications are documented per stage
- [ ] Configuration options are listed

### Completeness (Pass 4)
- [ ] Edge cases are documented per stage
- [ ] Error handling is specified
- [ ] Failure modes and recovery are defined
- [ ] Second-order effects are acknowledged
- [ ] No ambiguities remain (no TBD/TODO)

---

## Output

When the interview is complete, write documentation to:
`documentation/<prefix>_<feature_name>_documentation.md`

### Prefix Selection

Choose the prefix that best matches the feature's primary domain (per `general_documentation_crafting_guidelines.md` Section 12.1):

| If the feature primarily involves... | Use prefix |
|--------------------------------------|------------|
| Station-level functionality | `station_` |
| Web application (API/client) | `webapp_` |
| Data ingestion pipeline | `ingress_` |
| Database entities/schemas | `datamodel_` |
| Computer vision / ML | `cv_` |
| Cross-cutting / meta concerns | `general_` |

### Document Structure

The output document must include:

1. **Overview** - The one-sentence description and motivation (from Pass 1)
2. **Scope** - What's included and explicitly excluded (from Pass 1)
3. **Process Flow** - The end-to-end stages with diagram if helpful (from Pass 2)
4. **Stage Details** - Per-stage specifications (from Pass 3)
5. **Error Handling** - Error taxonomy and recovery (from Pass 4)
6. **Edge Cases** - Boundary conditions and unusual scenarios (from Pass 4)
7. **Affected Systems** - Second-order effects (from Pass 4)
8. **Decisions Log** - Key decisions made during interview with rationale

### Quality Gate

Before writing the document, verify it will pass the "Clarifying Question Rule" from `general_documentation_crafting_guidelines.md`:

> If a reader must ask a clarifying question, the documentation has failed.

Read through your planned documentation. For each section ask: "Could someone implement this without asking me anything?" If no, you need more detail from the interview.

```

---

## Usage

Invoke with: `/interview <feature name>`

**Examples:**
- `/interview batch video annotation pipeline`
- `/interview YOLO model training workflow`
- `/interview SAM3 mask generation`

---

## Interviewer Anti-Patterns to Avoid

| Anti-Pattern | Why It's Bad | Instead |
|--------------|--------------|---------|
| Asking edge case questions before understanding the flow | You'll get fragmented answers that don't fit together | Complete Pass 2 before Pass 4 |
| Accepting "it depends" as an answer | Creates TBD in documentation, which violates guidelines | Force a decision or a documented default |
| Asking leading questions | You'll document YOUR assumptions, not THEIR requirements | Ask open questions, then reflect back |
| Moving on when you don't understand | Your confusion becomes documentation gaps | Say "I don't follow - can you explain that differently?" |
| Trying to solve problems during the interview | Interview is for GATHERING, not DESIGNING | Note the problem, document it, move on |
| Skipping the checkpoints | You'll realize gaps too late | Always summarize and confirm before proceeding |

---

## Version History

**v2.0.0 (2026-02-01):**
- Complete rewrite to use 4-Pass iterative methodology
- Added explicit checkpoints between passes
- Added interviewer behaviors and anti-patterns
- Aligned with plan crafting guidelines structure
- Added decision forcing techniques

**v1.0.0 (2026-02-01):**
- Initial draft with flat phase structure

---

**Last Updated:** 2026-02-01
**Status:** Complete
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
claude-interactive-documentation-workflow

Directory Structure

SKILL.md

Report

Notice
