SKILL.md

v1.0.0 · 1891 B · text/markdown

---
name: spec-interview
description: Use before starting an ambiguous or architecturally significant task - flips the dynamic so the agent interviews the human until every design branch is resolved, before writing any code
---

# Spec Interview

For genuinely ambiguous or high-stakes work, proposing a plan first means
guessing at requirements the human hasn't stated. This skill inverts that:
the agent interviews the human, one question at a time, until the design
space is fully resolved.

## How to run the interview

1. **Map the decision tree first**, privately — architecture choices, data
model shape, UX behavior, edge cases, non-goals. Don't show this list
yet.
2. **Ask one question at a time.** Never batch multiple open questions into
one message — each answer can change what the next question should even
be.
3. **Offer a suggested default** with every question ("I'd default to X
because Y — does that work, or do you want something else?"). This gives
the human a fast path to agree instead of having to invent an answer
from nothing.
4. **Track resolved vs. open branches explicitly.** Before finishing, list
what's been decided and what, if anything, is still open.
5. **Only after every branch is resolved**, summarize the full spec back
and get explicit confirmation before any code is written.

## What counts as "resolved enough"

A branch is resolved when the answer is concrete enough that two different
implementers would build the same thing from it. "Make it fast" is not
resolved. "Cache the result for 5 minutes, evict on write" is.

## When not to use this

Well-scoped, unambiguous tasks don't need an interview — asking questions
whose answers are already obvious from context just adds friction. Reach
for this specifically when the task is architecturally significant AND the
requirements are genuinely underspecified.