/clarify

name: clarify
description: |
  "/clarify", "clarify this", "keep asking until clear", "remove ambiguity",
  "clarify requirements", "clarify design", "clarify the plan",
  "질문 계속해", "모호한 게 없게", "명확해질 때까지", "계속 물어봐",
  "Q&A로 정리", "질문답변 기록", "요구사항 명확화", "설계 명확화".
  Relentless ambiguity-resolution interview that records Q&A under
  .hoyeon/clarify/<topic>/ and hands off to specify/blueprint/docs when clear.
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
  - Task
  - Write
  - Edit
  - AskUserQuestion
validate_prompt: |
  Must ask one question at a time, provide a recommended answer, record Q&A,
  and continue until the auditor finds no material ambiguity or the user stops.
  Must not implement code or write final requirements/plan files.

/clarify — Ambiguity Resolution Interview

`clarify` is a pre-spec interview loop. It is closer to `grill-me` than `specify`: ask one precise question at a time, recommend an answer, record the answer, and keep going until material ambiguity is gone.

Do not implement, plan execution, or generate final requirements. The output is traceable context for the next workflow.

Runtime Surface

Claude Code

• Use `AskUserQuestion` for mode selection and branching decisions.
• Use `Task(subagent_type="clarity-auditor")` at audit boundaries.
• Use `Task(subagent_type="code-explorer")` when a question can be answered

from the codebase instead of asking the user.

Codex

• Use Codex-native structured input when available; otherwise ask one concise

plain-text question at a time.

• Use `hoyeon-clarity-auditor` when native adapters are loaded.
• Use `hoyeon-code-explorer` when codebase exploration can answer the question.
• If native adapters are unavailable, perform the smallest direct read-only

pass and record that fallback in `qa-log.md`.

Artifacts

Create a topic directory:

.hoyeon/clarify/<topic-slug>/
├── qa-log.md
└── clarity-summary.md

Read templates when writing artifacts:

• `templates/qa-log.md`
• `templates/clarity-summary.md`

Use a short kebab-case topic slug. If the current repo already has a Hoyeon spec directory for the same work, mention it in frontmatter as `related_spec`.

Modes

Infer the mode from the user's request. If uncertain, ask first.

| Mode | Use For | Main Question Lens | Clear Enough When | |------|---------|--------------------|-------------------| | `requirements` | Product/feature intent before `/specify` | users, goal, non-goals, success, scope, flows, edge cases, constraints | `$hoyeon-specify --context clarity-summary.md` can start without guessing | | `design` | Architecture or implementation direction before planning | alternatives, boundaries, interfaces, data flow, trade-offs, risks, reversibility, verification | chosen direction, rejected alternatives, risks, and validation are explicit | | `domain` | Terms, concepts, and domain model | canonical terms, definitions, relationships, edge cases, conflicts with docs/code | key terms have stable definitions and unresolved terms are listed | | `plan` | Work sequencing before blueprint/execution | dependencies, acceptance criteria, blocking decisions, validation, rollback, ownership | no blocking execution decision remains |

Frontmatter fields:

mode: requirements | design | domain | plan
status: active | complete | paused
target_handoff: hoyeon-specify | hoyeon-blueprint | docs | none

Default mode is `requirements`.

Core Loop

1. **Mirror** — State the current understanding in 2-4 bullets. 2. **Map ambiguity branches** — List the active ambiguity branches in memory: vague terms, hidden assumptions, unresolved forks, missing criteria, external facts/code facts to verify. 3. **Ask one question** — Ask exactly one question. Include:

• why this question matters
• your recommended answer
• the trade-off behind the recommendation

4. **Explore instead of asking** — If the answer is discoverable from the codebase or existing docs, explore first and ask only if evidence conflicts. 5. **Record immediately** — Append to `qa-log.md` after every exchange. 6. **Classify** — Mark the branch as `resolved`, `ambiguous`, `assumption`, or `deferred`. 7. **Audit** — After 3-5 Q&A turns, after each major branch, and before summary, call the clarity auditor with the full `qa-log.md`. 8. **Continue or summarize** — If auditor returns `CONTINUE`, ask the next suggested question. If `SUFFICIENT`, write `clarity-summary.md`.

Question Rules

• Ask one question at a time.
• Always provide a recommended answer unless the question is purely factual and

must be discovered.

• Prefer concrete options over open-ended prompts, but allow "Other".
• Do not ask the user for facts that code/docs can answer.
• Do not repeat a question. If the user does not know, choose a tentative

default, mark it `assumption` or `deferred`, and move on.

• Keep pressure on vague words: "fast", "simple", "good", "production-ready",

"secure", "later", "nice UX", "admin", "sync", "done".

Mode-Specific Checks

requirements

Required branches:

• primary user or actor
• problem and desired outcome
• explicit non-goals
• success criteria
• core happy path
• important edge/failure states
• constraints and risk modifiers

design

Required branches:

• candidate approaches
• chosen direction and why
• rejected alternatives and why
• boundaries and interfaces
• state/data flow
• failure modes
• reversibility and migration
• verification strategy

domain

Required branches:

• canonical terms
• term definitions
• relationships between terms
• overloaded or conflicting terms
• boundary scenarios
• code/doc contradictions, if a repo exists
• doc target: `CONTEXT.md`, ADR, glossary, or no docs

Do not update `CONTEXT.md` or ADRs unless the user explicitly asks for docs-mode updates. By default, write candidates into `clarity-summary.md`.

plan

Required branches:

• acceptance criteria
• task dependencies
• blocking decisions
• vali