Specify

specify: Goal → Requirements via Systematic Interview

Overview

Transform a vague goal into structured, traceable requirements through: 0. WHERE Grounding — establish project type, situation, ambition, and risk modifiers 0.5. Context Research (brownfield only) — scan existing codebase before asking the user

1. Interview — systematic Q&A across Business/Interaction/Tech axes (depth-calibrated by WHERE)
2. Extract — parallel requirements extraction by domain experts
3. Cross-check — conflict/gap/duplicate detection
4. Confirmation — user accepts assumptions + final requirements.md committed in cli format

Handoff contract

The final deliverable is <spec_dir>/requirements.md in the format that /blueprint consumes:

• Frontmatter: type (greenfield|feature|refactor|bugfix), goal, non_goals[]
• Body: flat list of ## R-X<num>: parent requirements, each with nested #### R-X<num>.Y: sub-requirements carrying given/when/then
• X in the ID is axis code: B=Business, U=Interaction (user), T=Tech
• Optional ## Open Decisions section with ### OD-N: blocks

All intermediate files (qa-log.md, reqs-business.md, reqs-interaction.md, reqs-tech.md) stay in <spec_dir>/ for traceability but are NOT read by /blueprint.

Runtime Surface

Claude Code

• Use AskUserQuestion for the structured interview forms described below.
• Use Agent(subagent_type="...") for brownfield research and extractor subagents.
• Claude hooks may initialize skill session state, but the durable output remains <spec_dir>/requirements.md.

Codex

• Keep the same interview protocol and output format, but use Codex-native structured input when available; otherwise ask one concise plain-text question at a time.
• Use Bash-first CLI setup through hoyeon-cli req init.
• Use logical Hoyeon subagent names in prompts, mapped to Codex adapters when installed. If adapters are not loaded in the current session, perform the smallest direct research pass needed to complete requirements.md.
• Do not rely on hooks for session initialization or cleanup in Codex v1.

Phase 0: WHERE Grounding

The WHERE is the combination of current situation and intended scope. It calibrates how deep the interview goes on each axis — without it, every project gets the same heavyweight treatment, which over-engineers toys and under-specs production systems.

Step 0.1: Mirror (prove understanding before asking)

Before asking for goal/non-goals, present your understanding of the user's request using this template:

**Mirror — Here's what I understood**

**Understanding:**
<1–2 sentences paraphrasing the user's request in your own words. Not a verbatim echo.>

**Goal:**
- <bullet 1: concrete outcome>

**Non-Goal (explicitly out of scope):**
- <bullet 1: exclusion — at least one must be inferred by you, not stated by user>

**Ambiguous (scope-level unknowns):**
- <ambiguity about what "done" means, what's included, or who the user is>

Then confirm via AskUserQuestion:

AskUserQuestion(
  question: "Does this match your intent?",
  options: [
    { label: "Approve", description: "Proceed to WHERE grounding" },
    { label: "Revise", description: "Fix goal/non-goal/scope" }
  ]
)

Rules:

• At least one Non-Goal and one Ambiguous item must be inferred by you — a pure echo is a violation
• Ambiguous items are scope-level only ("what are we building / for whom / done when?"), NOT tech choices
• Max 2 revision rounds. If still unclear, proceed and record residual ambiguities for Phase 1
• On Approve: extract goal and non_goals from the mirror (no need to re-ask in free-text)

Step 0.2: WHERE Inference (infer-first, ask-only-on-uncertainty)

Default behavior: infer from the working directory and the user's goal. Only ask the user about dimensions you genuinely cannot determine from evidence.

Don't burn 4 cold-start questions on facts the codebase already answers. Most of PROJECT_TYPE, SITUATION, and risk factors are visible to you. Only AMBITION is reliably user-intent-driven.

Step 0.2.a: Gather signals (read-only)

Inspect the repo. Use evidence — file paths, not vibes:

• PROJECT_TYPE signals:
  • package.json + frontend deps (react, vue, svelte, vite) / app/, src/components/ → user-facing
  • package.json + backend deps (express, fastify, nest) / routes/, api/, controllers/ → api-service
  • bin/, cli.ts, pyproject.toml with [project.scripts], single-binary Cargo project → dev-tool
  • terraform/, k8s/, helm/, Dockerfile + no app code → infrastructure
• SITUATION signals:
  • Empty repo or only scaffolding (single README, no src) → greenfield
  • Existing src tree, many files, established conventions → brownfield (extension or refactor depends on user's goal verb)
  • User's goal mentions a new module/feature inside existing project → hybrid
• RISK signals:
  • auth/, session, passport, oauth, cookie, jwt references → sensitive-data candidate
  • prisma/schema.prisma / migrations/ with PII columns (email, phone, ssn) → sensitive-data
  • Payment SDKs (stripe, toss, iamport, paypal) → sensitive-data + external-exposure
  • Public route definitions (no auth middleware), webhooks, /api/public → external-exposure
  • migrations/, destructive scripts, public SDK exports → irreversible
  • Load balancers, queues (kafka, sqs, redis streams), CDN config → high-scale

If brownfield, you may dispatch a quick code-explorer here — but a cheap ls + Read README.md + Glob is often enough for inference. Don't over-spend on Phase 0.

Step 0.2.b: Construct tentative WHERE and present

Build a single block in the Mirror (extend Step 0.1's mirror, or send as follow-up):

**Inferred Context** (confirm or override)

- **PROJECT_TYPE**: <inferred value>
  - Evidence: <file:line or path that supports this>
- **SITUATION**: <inferred value>
  - Evidence: <...>
- **AMBITION**: <best guess, mark confidence>
  - Confidence: low/medium/high — <why>
- **RISK factors**: [<inferred list, or "none detected">]
  - Evidence: <...>

Mark each dimension with confidence:

• high: evidence is unambiguous (e.g., package.json with react = user-facing)
• medium: evidence is suggestive but could be wrong
• low: little to no signal — needs user input

Step 0.2.c: Confirm or drill (single AskUserQuestion)

If ALL dimensions are medium/high confidence:

AskUserQuestion(
  question: "Confirm inferred context?",
  options: [
    { label: "Approve all", description: "Use inferred WHERE as-is" },
    { label: "Override some", description: "Correct one or more dimensions" }
  ]
)

On Override: ask follow-up only for the dimensions the user flags. Use the original option lists below as the menu for those targeted questions.

If ANY dimension is low confidence (typically AMBITION on truly new projects), skip the confirm-or-drill choice and ask only the low-confidence dimensions directly, batched in one AskUserQuestion. Do not re-ask high-confidence dimensions.

Option menus (for targeted drills)

Use these when the user picks "Override some" or when a dimension is low-confidence:

• PROJECT_TYPE: User-facing app / API or Service / Dev tool or Library / Infrastructure
• SITUATION: Greenfield / Brownfield extension / Brownfield refactor / Hybrid
• AMBITION: Toy or Experiment / Feature or MVP / Product
• RISK factors (multiSelect): Sensitive data / External exposure / Irreversible ops / High scale

Definitions match the originals: Toy = days, failure ok; Feature/MVP = 1-2 weeks, core only; Product = long-term, reliability + security matter. Risk factors escalate specific nodes to deep in Step 0.4.

Step 0.3: Spec Name & Output Setup

• Determine spec name (kebab-case, e.g., user-dashboard)
• Decide spec_dir: default .hoyeon/specs/{spec-name}/
• Bootstrap via cli — creates the directory AND writes a requirements.md stub with the correct frontmatter so /blueprint can read it later:

  hoyeon-cli req init <spec_dir> --type <greenfield|feature|refactor|bugfix> --goal "<one-line goal>"

  Map WHERE.SITUATION → --type:
  • greenfield → greenfield
  • brownfield-extension → feature
  • brownfield-refactor → refactor
  • hybrid → feature (or refactor if structural churn dominates) The stub is overwritten at Phase 4.3 once the interview is complete. If <spec_dir>/requirements.md already exists from a prior run, skip req init and proceed (the user is re-running specify on the same spec).
• Read the Q&A log template from ${baseDir}/templates/qa-log.md
• Initialize <spec_dir>/qa-log.md with spec name, goal, non-goals, and the WHERE context filled in

Step 0.4: Derive Axis Depth Calibration

Combine SITUATION × AMBITION × RISK_MODIFIERS to assign each taxonomy node a depth level (light, standard, or deep). Apply rules in order — later rules escalate, never downgrade.

Step A — SITUATION base:

• Greenfield → TECH.ARCH/DATA standard
• Brownfield extension → TECH.ARCH deep, TECH.COMPAT deep; BUSINESS.WHO light
• Brownfield refactor → TECH.ARCH deep, TECH.COMPAT deep, TECH.DATA deep
• Hybrid → blend Greenfield + Extension rules

Step B — AMBITION modulation:

• Toy → TECH.SECURITY light, BUSINESS.RISK light, INTERACTION.ACCESS light. Keep INTERACTION.JOURNEY/HAPPY standard.
• Feature/MVP → default standard; only honor deeps from Step A.
• Product → TECH.SECURITY deep, INTERACTION.ACCESS deep, BUSINESS.RISK deep, TECH.COMPAT deep.

Step C — RISK_MODIFIERS escalation (override Step B downgrades):

• sensitive-data → TECH.SECURITY deep, TECH.DATA deep
• external-exposure → TECH.SECURITY deep, INTERACTION.ACCESS deep
• irreversible → BUSINESS.RISK deep, TECH.COMPAT deep
• high-scale → TECH.INFRA deep, TECH.ARCH deep

Examples:

• User-facing + Greenfield + Toy + no modifiers → light SECURITY/RISK/ACCESS, standard elsewhere
• User-facing + Greenfield + Toy + sensitive-data → SECURITY/DATA escalated to deep (small-but-dangerous)
• API-service + Brownfield-refactor + Product + external-exposure → virtually everything deep

Project-type notes — PROJECT_TYPE doesn't change calibration numbers, but it changes what each INTERACTION node means (the interaction-extractor reads project_type for lens selection).

Write the derived calibration into qa-log.md frontmatter as depth_calibration: so Phase 1 and the gap-auditor can read it.

Phase 0.5: Context Research (brownfield only)

Skip this phase entirely if where.situation == greenfield. Run it for brownfield-extension, brownfield-refactor, and hybrid.

Why: brownfield work depends on existing code that the user may not fully remember. Asking the user "what's the architecture?" when the codebase is right there is wasteful and unreliable. Scan the code first, then interview them on decisions — not facts.

Dispatch subagents in parallel

Task(subagent_type="code-explorer",
     prompt="Goal: {goal}. Find: existing patterns, modules, or files relevant to this change. Report as file:line format with brief summary.")

Task(subagent_type="code-explorer",
     prompt="Find project structure and toolchain: package manifests, build/test/lint commands, entry points, deployment config. Report as file:line format.")

Task(subagent_type="docs-researcher",
     prompt="Goal: {goal}. Search ADRs, READMEs, docs/, CLAUDE.md, config files for conventions, architecture decisions, and constraints relevant to this work. Report as file:line format.")

For brownfield-refactor specifically, add:

Task(subagent_type="code-explorer",
     prompt="Find all call sites and dependents of {the area being refactored}. Report impact surface as file:line format.")

Consolidate into qa-log.md → research: section

Write findings into qa-log.md under a new top-level heading ## Research (before the axis sections). Include:

• Existing architecture summary (1-3 sentences)
• Relevant files/modules (with file:line anchors)
• Toolchain (build/test/lint)
• Existing constraints or conventions discovered
• Potential impact surface (for refactors)

Also add research_done: true to the where: frontmatter block so later phases can rely on it.

Interview uses research as baseline

During Phase 1, when asking Tech axis questions:

• Reference the research findings ("I see you use Vite + TypeScript — is that still the target?" instead of "what's your build tool?")
• Only ask the user for decisions (what they want) and intent (why), not facts (what exists — we already found those)

Phase 1: Interview

Interview Protocol

You are the interviewer. Ask questions one axis at a time, following this taxonomy:

Axis 1: BUSINESS    — WHO, WHY, WHAT, SUCCESS, SCOPE, RISK
Axis 2: INTERACTION — JOURNEY, HAPPY, EDGE, STATE, FEEDBACK, ACCESS
Axis 3: TECH        — ARCH, DATA, INFRA, DEPEND, COMPAT, SECURITY

The INTERACTION axis is consumer-generic. Reinterpret nodes based on where.project_type:

EDGE/STATE are universal: failures & conditional behavior apply everywhere.

Question Rules

PRIMARY: Use AskUserQuestion tool for all interview questions. Free-text prompting should only be a fallback when options genuinely cannot be enumerated.

Why AskUserQuestion

• Directly implements Recognition over Recall — user picks from concrete options
• Options with description field show consequences/trade-offs per choice
• "Other" is auto-added — user can always override with custom answer
• Supports batching (1-4 questions per call) — pair related questions together
• multiSelect: true for non-exclusive choices

Batching Guidance

Batch when:

• Questions are within the same axis node and mutually informative (e.g., WHO + WHAT)
• Questions are orthogonal and won't confuse the user (e.g., STATE + FEEDBACK)
• User has already given broad context and is ready for several specifics

Do NOT batch when:

• A later question's options depend on the answer to an earlier one (ask sequentially)
• The first question is a depth drill that may trigger more drills (go one-at-a-time)
• User seems uncertain — a single focused question is less overwhelming

Max 4 per call (tool limit). Default: batch 2-3 related questions per turn.

Question Construction

Each AskUserQuestion option must have:

• label: 1-5 words (what the user picks)
• description: the consequence/implication of this choice
• First option gets "(Recommended)" suffix only when you genuinely have a recommendation

Example (batched):

questions: [
  {
    question: "Who is the primary user?",
    header: "Primary user",
    options: [
      { label: "Senior developers", description: "Power users; expect depth + customization" },
      { label: "Junior developers", description: "Learning users; expect guidance + safe defaults" },
      { label: "Both equally", description: "Dual-mode UX; complexity to serve both" }
    ]
  },
  {
    question: "What's the success signal?",
    header: "Success metric",
    options: [
      { label: "Team-wide adoption", description: "Qualitative; hard to measure" },
      { label: "Daily active use", description: "Quantitative DAU; needs tracking" },
      { label: "Time saved per task", description: "Efficiency metric; baseline needed" }
    ]
  }
]

Depth Drill: Two Mechanisms

Drills happen at two distinct moments, with different judges. Both are required.

Type A: Inline Drill (You judge, in real time)

When: Immediately after an AskUserQuestion answer arrives.

How: Scan the selected option + any "Other" free-text for these signals. If present, the NEXT AskUserQuestion is a drill on the same node.

Inline drills are fast and subjective — you catch the obvious ones on the spot.