Skip to content

zeikar/hyperclaude / skills/hyper-interview

hyper-interview

Unverified

Use 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 dispatch implementer for one step (pass run_in_background: false for 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

  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 with run_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:

DimensionClear once it can be stated as…
Goalthe core outcome in one sentence — the key noun and what happens to it
Constraintsthe boundaries, environment, and explicit non-goals
Successhow to verify it's done — concrete, testable acceptance
Context (brownfield only)how it fits the existing code without breaking it

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: "").
  2. 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.

  3. 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-loop / 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. (The planning skills do 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-loop <original idea> (plan ↔ review until clean; /hyperclaude:hyper-plan when 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, while hyper-plan splits 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-plan for an oversized spec); 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).
  • 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.
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: 319kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall
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: 196kUpdated Claude CodeCodexVerifiedInstall