zeikar/hyperclaude / skills/hyper-interview
hyper-interview
UnverifiedUse when starting from a vague or under-specified idea and want requirements clarified before planning — "interview me", "ask me what you need", "clarify requirements first", "I'm not sure exactly what I want", "make sure you understand before building". Also when the user invokes /hyperclaude:hyper-interview. Runs a short one-question-at-a-time interview and writes a spec to .hyperclaude/specs/ — the front-end input to /hyperclaude:hyper-research and /hyperclaude:hyper-plan. Distinct from /hyperclaude:hyper-plan, which decomposes an ALREADY-CLEAR task into tasks.
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 a light interview: a conversational flow that aims each question at the least-clear requirement dimension, judged qualitatively, with no state kept beyond the spec file.
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 dispatchimplementerfor one step (passrun_in_background: falsefor the result inline). - 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.
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
- 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. - Greenfield vs brownfield. Dispatch the
Exploreagent (read-only) ONCE withrun_in_background: false(the greenfield/brownfield verdict and area map gate Step 2's questions, which cite Explore's findings; result awaited inline) 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:
| Dimension | Clear once it can be stated as… |
|---|---|
| Goal | the core outcome in one sentence — the key noun and what happens to it |
| Constraints | the boundaries, environment, and explicit non-goals |
| Success | how to verify it's done — concrete, testable acceptance |
| Context (brownfield only) | how it fits the existing code without breaking it |
Each round:
- Target the weakest dimension. Name it in one line first: "Goal is clear; constraints are still fuzzy → next question targets constraints."
- 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 insrc/auth/; extend it or diverge?") - 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
-
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 frontmatterslug:line is the bare key with an empty value:slug:(key, colon, single space, nothing after — NOTslug: "").
- No-ASCII fallback (e.g. an all-Korean idea): the filename is the timestamp only (
-
Resolve the path:
mkdir -p .hyperclaude/specs date -u +%Y%m%d-%H%MBase path
.hyperclaude/specs/<timestamp>-<slug>.md; if it exists, append-2,-3, … until free. -
Write the spec with the Write tool. Author NO
plugin-versionline — 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
-
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.
-
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-loop/hyper-plan/hyper-researchderive their slug from$ARGUMENTSwith the same rule used in Step 4, so the same idea text yields the same slug and theresearch → plan → plan-reviewtrace stays linked. A reworded Goal would derive a different slug and silently break the trace. (The planning skills do not readspecs/— the slug match is what links them, plus the spec content you already hold in context.)- Straight to planning →
/hyperclaude:hyper-plan-loop <original idea>(plan ↔ review until clean;/hyperclaude:hyper-planwhen the user wants round-by-round control). For an oversized spec (beyond ~10–12 tasks, or several independent milestones) →/hyperclaude:hyper-plan <original idea>instead: the loop always produces one detailed plan, whilehyper-plansplits an oversized task into an epic roadmap. Either way, 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 the planning skill chosen above.
Default recommendation:
hyper-plan-loop(hyper-planfor an oversized spec); prependhyper-researchwhen the approach has real unknowns. - Straight to planning →
Anti-patterns
- Calling Codex / the bridge. This gate is Claude-only; review is downstream (
hyper-plan-review,hyper-code-review). - 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.mdsibling. 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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |