team-attentionteam-attention/hoyeon/skills/clarify/SKILL.md

clarify

Skill173 starsChanged 8 months agoMITView on GitHub

"/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.

We split this skill into the rules it gives an agent

23 rules. 0 are common, 10 are distinctive, and 13 are very specific to this project.

0
Common
Most of the 78 edited versions we read keep these.
10
Distinctive
This author's own choices. Worth a look.
13
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Do not implement, plan execution, or generate final requirements.
line 31
Very specific:
Use AskUserQuestion for mode selection and branching decisions.
line 38
Very specific:
Use Task(subagent_type="clarity-auditor") at audit boundaries.
line 39
Very specific:
Use Task(subagent_type="code-explorer") when a question can be answered from the codebase instead of asking the user.
line 40
Distinctive:
Use Codex-native structured input when available.
line 45
Very specific:
Use hoyeon-clarity-auditor when native adapters are loaded.
line 47
Very specific:
Use hoyeon-code-explorer when codebase exploration can answer the question.
line 48
Very specific:
If native adapters are unavailable, perform the smallest direct read-only pass and record that fallback in qa-log.md.
line 49
Distinctive:
Create a topic directory:
line 54
Distinctive:
Read templates when writing artifacts:
line 62
Very specific:
Use a short kebab-case topic slug.
line 66
Very specific:
Default mode is requirements.
line 88
Distinctive:
Ask one question at a time.
line 112
Distinctive:
Always provide a recommended answer unless the question is purely factual and must be discovered.
line 113
Distinctive:
Prefer concrete options over open-ended prompts, but allow "Other".
line 115
Distinctive:
Do not ask the user for facts that code/docs can answer.
line 116
Very specific:
Do not repeat a question. If the user does not know, choose a tentative default, mark it assumption or deferred, and move on.
line 117
Distinctive:
Keep pressure on vague words: "fast", "simple", "good", "production-ready", "secure", "later", "nice UX", "admin", "sync", "done".
line 119
Very specific:
Do not update CONTEXT.md or ADRs unless the user explicitly asks for docs-mode updates.
line 158
Very specific:
Only stop as complete when the auditor says SUFFICIENT or the user explicitly stops.
line 201
Very specific:
After SUFFICIENT, write clarity-summary.md and present one next action:
line 206
Distinctive:
Do not run the handoff workflow unless the user asks.
line 215
Very specific:
No final requirements.md, plan.json, or ADR unless explicitly requested.
line 220

“Common” is measured: kept by at least 6 in 10 of the 78 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

/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

Mirror — State the current understanding in 2-4 bullets.
Map ambiguity branches — List the active ambiguity branches in memory: vague terms, hidden assumptions, unresolved forks, missing criteria, external facts/code facts to verify.
Ask one question — Ask exactly one question. Include:
- why this question matters
- your recommended answer
- the trade-off behind the recommendation
Explore instead of asking — If the answer is discoverable from the codebase or existing docs, explore first and ask only if evidence conflicts.
Record immediately — Append to qa-log.md after every exchange.
Classify — Mark the branch as resolved, ambiguous, assumption, or deferred.
Audit — After 3-5 Q&A turns, after each major branch, and before summary, call the clarity auditor with the full qa-log.md.
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
validation evidence
rollback/recovery
ownership or handoff
out-of-scope work

Q&A Log Format

Append entries under ## Q&A:

### Q<N>: <short branch title>
- mode: <mode>
- branch: <branch id or name>
- status: resolved | ambiguous | assumption | deferred
- asked: <question>
- recommended: <recommended answer>
- answer: <user answer or discovered evidence>
- rationale: <why this resolves or does not resolve ambiguity>

Maintain ## Open Ambiguities as the current queue. Remove resolved items.

Auditor Contract

Send the auditor:

full qa-log.md
mode
current branch, if any
question count since last audit

Auditor returns:

CONTINUE with material ambiguities and suggested next question, or
SUFFICIENT with remaining non-blocking assumptions.

Only stop as complete when the auditor says SUFFICIENT or the user explicitly stops. If the user stops early, set status to paused.

Handoff

After SUFFICIENT, write clarity-summary.md and present one next action:

Mode	Default Handoff
`requirements`	`$hoyeon-specify --context .hoyeon/clarify/<topic>/clarity-summary.md "<topic>"`
`design`	`$hoyeon-blueprint --context .hoyeon/clarify/<topic>/clarity-summary.md` or ADR candidate
`domain`	docs/glossary update, if requested
`plan`	`$hoyeon-blueprint` or direct execution planning

Do not run the handoff workflow unless the user asks.

Hard Rules

No implementation.
No final requirements.md, plan.json, or ADR unless explicitly requested.
One question at a time.
Recommended answer required for each user-facing question.
Record each exchange before asking the next question.
Continue until SUFFICIENT, paused, or explicit user stop.

Download now (ZIP)

Other versions82 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 82
antonio-orionus/Arroxy★ 610same name
spool-lab/spool★ 592same name
paperboytm/spool★ 590same name
talesofai/cohub★ 571same name
ZaxbyHub/opencode-swarm★ 517same name
zaxbysauce/opencode-swarm★ 503same name
nexmoe/DayBee★ 424same name
nexmoe/eve★ 421same name
educlopez/ui-craft★ 398same name
ryanthedev/code-foundations★ 381same name
72 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
Used alongsideProjects with it also use quieter, delight and 10 more.
Other files people use alongside this one.
- HK-hubSkill
  quieter
  Tones down visually aggressive or overstimulating designs, reducing intensity while preserving quality. Use when the user mentions too bold, too loud, overwhelming, aggressive, garish, or wants a calmer, more refined aesthetic.
  Also in 28 projects that use this
- HK-hubSkill
  delight
  Add moments of joy, personality, and unexpected touches that make interfaces memorable and enjoyable to use. Elevates functional to delightful. Use when the user asks to add polish, personality, animations, micro-interactions, delight, or make an interface feel fun or memorable.
  Also in 27 projects that use this
- zwy123zwySkill
  normalize
  将用户随意输入的提示词规范化为结构清晰、便于大模型执行的标准化提示词。适用于需要整理、统一提示词格式时调用。
  Also in 18 projects that use this
- owshq-mecSkill
  layout
  Improve layout, spacing, and visual rhythm. Fixes monotonous grids, inconsistent spacing, and weak visual hierarchy. Use when the user mentions layout feeling off, spacing issues, visual hierarchy, crowded UI, alignment problems, or wanting better composition.
  Also in 8 projects that use this
- jovijoviSkill
  extract
  Extract content from specific URLs using Tavily's extraction API. Returns clean markdown/text from web pages. Use when you have specific URLs and need their content without writing code.
  Also in 19 projects that use this
- +7 more from HK-hub
In this repository27 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- analyze-ossSkill
- blueprintSkill
- browser-workSkill
- bugfixSkill
- checkSkill
- compoundSkill
- councilSkill
- deep-researchSkill
- dev-scanSkill
- discussSkill
- executeSkill
- google-searchSkill
- issueSkill
- mirrorSkill
- qaSkill
- ralphSkill
- reference-seekSkill
- rulphSkill
- scaffoldSkill
- skill-session-analyzerSkill
- specifySkill
- stepbackSkill
- tech-decisionSkill
- tribunalSkill
- ultraworkSkill
- verifySkill

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free

23 rules. 0 are common, 10 are distinctive, and 13 are very specific to this project.

/clarify — Ambiguity Resolution Interview

Runtime Surface

Claude Code

Codex

Artifacts

Modes

Core Loop

Question Rules

Mode-Specific Checks

requirements

design

domain

plan

Q&A Log Format

Auditor Contract

Handoff

Hard Rules

Word for word · 0

Edited · 0

Wrote their own version · 82

quieter

delight

normalize

layout

extract

Does it work?

Your trail

Now do this for your own.