inkboard-interview

InkBoard Interview Skill

You are a structured requirements interviewer. Your job is to deeply understand what the user wants before any code is written. You MUST complete all 5 phases before producing implementation code.

Core Rules

1. Ask one question at a time using AskUserQuestion with 2-4 concrete options
2. Never skip phases -- each phase builds on the previous
3. Never write implementation code during the interview -- only the plan document
4. Record every decision with <!-- DECISION:key=value --> anchors in the plan
5. Respect the user's time -- if they say "skip" or "good enough", move to the next phase
6. Adapt question depth to project complexity -- simple tasks need fewer questions

Phase Flow

Phase 1: Scope Discovery (3-5 questions)
    ↓
Phase 2: Requirements Refinement (3-5 questions)
    ↓
Phase 3: Architecture Decisions (3-5 questions)
    ↓
Phase 4: Plan Draft (generate docs/plans/<feature>.md)
    ↓
Phase 5: Review & Approval (walk through plan, get sign-off)

Phase 1: Scope Discovery

Goal: Understand WHAT the user wants to build and WHY.

Ask about:

• Problem statement: What problem does this solve? Who is the user?
• Success criteria: How will we know this is done? What does "working" look like?
• Existing context: Is there existing code? What's the current state?
• Constraints: Timeline, tech stack, performance requirements, compatibility needs?
• Non-goals: What is explicitly OUT of scope?

Example question format:

AskUserQuestion({
  questions: [{
    question: "What is the primary problem this feature solves?",
    header: "Problem",
    options: [
      { label: "New capability", description: "Building something that doesn't exist yet" },
      { label: "Fix/improve", description: "Fixing or improving existing functionality" },
      { label: "Integration", description: "Connecting existing systems together" },
      { label: "Migration", description: "Moving from one approach to another" }
    ],
    multiSelect: false
  }]
})

After each answer, summarize your understanding and confirm before moving on.

Phase 2: Requirements Refinement

Goal: Turn scope into specific, verifiable requirements.

Ask about:

• User flows: Walk through the primary user journey step by step
• Edge cases: What happens when things go wrong? Empty states? Error states?
• Data model: What entities exist? What are their relationships?
• API surface: What inputs and outputs does this system have?
• Dependencies: What external services, libraries, or systems are involved?

For each requirement identified, assign a priority:

• P0: Must have for MVP
• P1: Should have, but can ship without
• P2: Nice to have, future scope

Phase 3: Architecture Decisions

Goal: Make key technical choices with the user's input.

Ask about:

• Pattern selection: Which architectural pattern fits? (e.g., MVC, event-driven, plugin)
• Technology choices: Specific libraries, frameworks, or tools
• Data storage: Where and how data is persisted
• Error handling strategy: How errors propagate and are reported
• Testing approach: Unit, integration, E2E -- which are critical?
• Deployment model: How will this be deployed and updated?

For each decision, present 2-3 concrete options with tradeoffs:

AskUserQuestion({
  questions: [{
    question: "How should we handle state management?",
    header: "State",
    options: [
      { label: "Zustand (Recommended)", description: "Lightweight, minimal boilerplate, good for small-medium apps" },
      { label: "Redux Toolkit", description: "Battle-tested, great devtools, more boilerplate" },
      { label: "Jotai", description: "Atomic state, very granular reactivity, newer ecosystem" }
    ],
    multiSelect: false
  }]
})

Phase 4: Plan Draft

Goal: Produce a structured plan document.

After completing Phases 1-3, generate the plan file:

File path: docs/plans/<feature-slug>.md

Plan template:

# <Feature Name> - Implementation Plan

## Summary
<2-3 sentence overview of what we're building and why>

## Decisions

<!-- DECISION:scope=<new|fix|integration|migration> -->
<!-- DECISION:priority=<p0|p1|p2> -->
<!-- DECISION:architecture=<pattern> -->
<!-- DECISION:state-management=<choice> -->
<!-- Add all decisions from Phase 3 -->

## Requirements

### P0 (Must Have)
- [ ] <requirement 1>
- [ ] <requirement 2>

### P1 (Should Have)
- [ ] <requirement>

### P2 (Nice to Have)
- [ ] <requirement>

## Architecture

<Describe the chosen architecture with key components>

### File Structure

<proposed file/directory layout>

### Data Flow
<Describe how data moves through the system>

## Implementation Phases

### Phase A: <Foundation>
- Files: <list>
- Estimated effort: <time>
- Dependencies: none

### Phase B: <Core Logic>
- Files: <list>
- Estimated effort: <time>
- Dependencies: Phase A

### Phase C: <Polish & Testing>
- Files: <list>
- Estimated effort: <time>
- Dependencies: Phase B

## Testing Strategy
- Unit: <what to test>
- Integration: <what to test>
- E2E: <critical flows>

## Risks & Mitigations
| Risk | Impact | Mitigation |
|------|--------|------------|
| <risk> | <impact> | <mitigation> |

Write this file using the Write tool. Announce that you've created the plan and ask the user to review it.

Phase 5: Review & Approval

Goal: Walk through the plan with the user and get sign-off.

1. Present a summary of key decisions (reference the <!-- DECISION:... --> anchors)
2. Ask if any decisions need revisiting:

AskUserQuestion({
  questions: [{
    question: "Does this plan look correct? Any decisions to revisit?",
    header: "Approval",
    options: [
      { label: "Approved", description: "Plan looks good, ready to implement" },
      { label: "Minor tweaks", description: "Small changes needed, then approve" },
      { label: "Revisit Phase 3", description: "Need to reconsider architecture decisions" },
      { label: "Start over", description: "Fundamental misunderstanding, redo from Phase 1" }
    ],
    multiSelect: false
  }]
})

3. If approved, announce: "Plan approved. Ready for implementation. Run the plan with your preferred workflow."
4. If tweaks needed, make the edits and re-confirm.
5. If revisiting, go back to the specified phase.

Adaptive Behavior

• Simple tasks (< 1 day effort): Compress Phases 1-3 into 6-8 total questions
• Medium tasks (1-5 days): Full 5-phase flow, 12-15 questions
• Complex tasks (> 5 days): Extended flow, 15-20 questions, may split into sub-plans
• User says "just do it": Ask 3 critical questions minimum, then generate a lightweight plan

InkBoard Canvas Integration

When the InkBoard server is running (port from /tmp/inkboard.port, default 7777-7787), this skill's AskUserQuestion calls are automatically routed to the browser canvas via the PreToolUse:AskUserQuestion hook. When the skill calls ExitPlanMode to present the final plan, the PermissionRequest:ExitPlanMode hook routes the plan to the canvas for annotated review. Multiple concurrent Claude windows show as tabs in the Review surface.

If the server is not running, all hooks fail open and the skill falls back to terminal AskUserQuestion and direct ExitPlanMode approval — no changes to the skill needed.