hyper-interview

Requirements-clarification gate. Turns a vague idea into a clear spec through a short Socratic interview — one targeted question at a time, aimed at whichever requirement dimension is least clear — then writes the spec to .hyperclaude/specs/<YYYYMMDD-HHMM>-<slug>.md. The spec is the front-end input to hyper-research / hyper-plan; the slug it mints is derived from the idea text the same way those skills derive theirs, so handing the same idea forward keeps the research → plan → plan-review trace linked.

Claude-only — no Codex. Critique belongs downstream, where it has something concrete to critique (hyper-plan-review on the plan, hyper-code-review on the diff). This gate's job is clarity, not review: get the requirements right so the plan isn't built on guesses. Anything off in the spec is caught when the plan is reviewed.

This is the light interview — the brainstorming-style conversational flow with deep-interview's weakest-dimension targeting, minus the heavy machinery (no numeric ambiguity scoring, no topology/ontology bookkeeping, no challenge-mode state machine, no resume).

When to use

• User typed /hyperclaude:hyper-interview <idea>.
• The idea is vague or under-specified and jumping straight to a plan would guess at scope ("interview me", "ask me what you need", "not sure exactly what I want", "make sure you understand before building").

Skip when:

• The request is already concrete (file paths, function names, acceptance criteria) — go to hyper-plan, or dispatch implementer for one step.
• The user pasted a PRD / spec / plan and wants it executed — use hyper-plan / hyper-implement.
• The user says "just do it" / "skip the questions" — respect it. Don't interrogate; proceed to the work they asked for.

<HARD-GATE> Do NOT write code, scaffold anything, or invoke an implementation skill until the spec is written AND the user approves it — however simple the idea looks. The interview's only outputs are the spec file and the handoff. "Simple" ideas are exactly where unexamined assumptions waste the most work. </HARD-GATE>

How to invoke

--resume is not supported. Refine in place during the session (Step 5 overwrites the file written in Step 4); a separate fresh run mints a new timestamped spec (same slug if the idea is unchanged) — there's no resume keyed on the path, so that's harmless.

Invocation argument: $ARGUMENTS

Step 1 — Resolve the idea + project context

1. The idea is $ARGUMENTS. If empty, fall back to the user's most recent build/implement intent in this conversation; if none exists, ask "What do you want to build?" and stop.
2. Greenfield vs brownfield. Dispatch the Explore agent (read-only) ONCE to check whether the cwd has source code bearing on the idea:

• Relevant code exists → brownfield: have Explore map the relevant area (paths, key symbols, patterns) so the questions can cite repo evidence instead of asking the user what the code already reveals.
• Otherwise → greenfield.
• Keep this to a single Explore dispatch; don't fan out. If exploration fails, proceed as greenfield and note the limitation.

Step 2 — Interview loop (one question at a time)

Track clarity qualitatively across a few dimensions — no numeric scoring:

Each round:

1. Target the weakest dimension. Name it in one line first: "Goal is clear; constraints are still fuzzy → next question targets constraints."
2. Ask exactly ONE question via AskUserQuestion, with concrete options plus free-text. Aim it to expose an assumption, not to collect a feature list. (Brownfield: cite the file/symbol that prompted the question — "I found JWT auth in `src/auth/`; extend it or diverge?")
3. Fold the answer in and re-judge that dimension.

When the idea is nearly clear, take one simplifier pass: "What's the simplest version that's still valuable?" / "Is `<constraint>` a real requirement or an assumption?" Then move to the spec.

Stop the loop when every applicable dimension is clear enough to write testable acceptance criteria, OR the user says "enough / let's go / build it" (allow after ~2 rounds). On early exit, name in one line what's still fuzzy so the gap is on record.

Soft cap: if the loop reaches ~8 rounds without converging, summarize what's clear, flag what isn't, and ask whether to proceed or keep going. Don't loop forever.

Step 3 — Approaches (only when there's a real fork)

If the idea has a genuine design fork (e.g. native app vs PWA, polling vs webhook), present 2–3 approaches with trade-offs and a recommendation in one message, and let the user pick. Skip this entirely when the idea is a requirement to clarify rather than a design to choose.

Do NOT produce a task breakdown here — decomposition into ## Task N: blocks is hyper-plan's job. The spec states what, not the task list.

Step 4 — Write the spec

1. Derive the slug from the idea, same rule as hyper-plan / hyper-research: lowercase, ASCII only, alphanumerics + hyphen, first 5 words of the idea joined by -. Example: "Add OAuth login to the API" → add-oauth-login-to-the.

• No-ASCII fallback (e.g. an all-Korean idea): the filename is the timestamp only (<timestamp>.md), and the frontmatter slug: line is the bare key with an empty value: slug: (key, colon, single space, nothing after — NOT slug: "").

1. Resolve the path:

   mkdir -p .hyperclaude/specs
   date -u +%Y%m%d-%H%M

Base path .hyperclaude/specs/<timestamp>-<slug>.md; if it exists, append -2, -3, … until free.

1. Write the spec with the Write tool. Author NO plugin-version line — the PostToolUse stamp hook adds it post-write. Frontmatter keys, in this order:

   ---
   mode: interview
   idea: |-
     <idea, each line 2-space indented>
   slug: <slug>
   generated: <ISO-8601 timestamp>
   type: greenfield|brownfield
   ---
   # Spec: <title>

   ## Goal
   <one crisp paragraph — the core outcome, covering the whole idea>

   ## Constraints
   - <constraint>

   ## Non-Goals
   - <explicitly excluded scope>

   ## Acceptance Criteria
   - [ ] <testable criterion>

   ## Assumptions Resolved
   | Assumption | Resolution |
   |---|---|
   | <what was assumed / surfaced> | <what was decided> |

   ## Context
   <brownfield: the cited code findings (paths/symbols) this builds on or diverges from.
   greenfield: technology choices and constraints. Omit this section if empty.>

Scale each section to the idea — a small idea gets a few lines per section, not padding. The spec captures the interview's conclusions, not its transcript.

Step 5 — User review + handoff

1. Tell the user the spec path and ask them to review it. Wait for approval (the HARD-GATE). If they request changes, revise the spec at the same path and re-confirm.
2. On approval, hand off — do NOT implement here. Pass the ORIGINAL idea text as the task argument — verbatim, the same text recorded in the spec's idea: frontmatter — NOT the reworded Goal. This is what keeps the slug aligned: hyper-plan / hyper-research derive their slug from $ARGUMENTS with the same rule used in Step 4, so the same idea text yields the same slug and the research → plan → plan-review trace stays linked. A reworded Goal would derive a different slug and silently break the trace. (hyper-plan does not read specs/ — the slug match is what links them, plus the spec content you already hold in context.)

• Straight to planning → /hyperclaude:hyper-plan <original idea>. The spec's resolved requirements (Goal / Constraints / Acceptance Criteria) are already in this conversation from Step 4 — feed them to the planner as context.
• Research first (when prior-art / pitfalls matter) → /hyperclaude:hyper-research <original idea>, then hyper-plan.

Default recommendation: hyper-plan; prepend hyper-research when the approach has real unknowns.

Anti-patterns

• Calling Codex / the bridge. This gate is Claude-only; review is downstream (hyper-plan-review, hyper-code-review).
• Numeric ambiguity scoring, topology/ontology bookkeeping, challenge-mode state machines, resume state. Out of scope — this is the light interview, deliberately not deep-interview.
• Batching questions. One per round; multiple at once produces shallow answers and blurs which dimension is being improved.
• Asking what the code already tells you. Explore first (brownfield) and cite the evidence in the question.
• Decomposing into tasks. That's hyper-plan. The spec states what to build and how success is verified — not the ordered task list.
• Implementing before spec approval. The HARD-GATE is absolute regardless of perceived simplicity.
• Hand-authoring a `<spec>-v2.md` sibling. In-session revisions overwrite the Step-4 path in place (Step 5); a separate re-run getting a new timestamped path is expected, not something to encode by hand.