| name | intent-discovery |
| description | Use when the user gives a concrete code modification instruction that describes how to do something (specific files, components, functions, APIs) but does not explain why or what problem it solves. Do NOT trigger when the user states their goal, asks a question, iterates on prior work, gives review feedback, or says "just do it" / "直接改" / "别问". Reconstructs likely intent, checks against project architecture (CLAUDE.md + docs/adr/), and surfaces better alternatives before committing to code. |
Intent Discovery
People rarely describe their real problem. They describe the first solution that came to mind. When a user says "add a refresh button to the dashboard," they might need real-time data. When they say "add another config field," they might need smarter defaults. Your job is to catch these moments before writing code — and only intervene when it actually matters.
When to skip this skill entirely
Before any analysis, check whether you should even be here. Abort immediately if the user's instruction falls into any of these buckets:
- User forbids questions. "直接改", "别问", "just do it", "按我说的做", "先做再说" → skip.
- Intent was already established. "接着上一步, 把那个也改了", "这里也要修", "还有一处同样的问题" → the "why" was settled earlier. Don't re-litigate.
- User is reacting to your output. "不对, 改成X", "用Y方法更好", "这里不对" → this is clarification on an ongoing task, not a new request.
- User is in rapid iteration mode. In a single conversation, the user has issued 3+ execution instructions in quick succession without waiting for full completion → they're exploring, not specifying. Skip.
- User gave both the solution AND the reason. "加个缓存, 因为数据库查询太慢了" → the "why" is explicit. No need to reverse-engineer it.
- It's not a code modification request. "这个函数是干什么的?", "帮我查一下哪里用了X", "review 一下这段代码" → questions and analysis don't need intent discovery.
If none of these apply AND the user described a "how" without a "why", proceed.
The core principle
Every user instruction lives on a spectrum:
| User says | What's really happening |
|---|
| "Fix the bug in the login form" | Clear problem + clear location → just do it |
| "Add a cache layer to the API" | Solution described, problem implied → investigate |
| "The dashboard feels slow" | Problem described, solution missing → explore together |
| "I want to improve data loading" | Both vague → full discovery needed |
The middle two rows are where this skill earns its keep. The user handed you a solution; your job is to walk it backward to the problem, then forward to the best solution.
When to intervene: the tier system
Intervention level is determined by quantitative checks first, qualitative signals as upgrades.
Quantitative checks (run these for every instruction)
- File count: how many files would this change touch?
- Module boundary: does it cross a documented module boundary (from project structure or ADRs)?
- Interface change: does it alter an API signature, data model, shared type, or public interface?
- ADR conflict: does the proposal contradict any existing ADR?
Qualitative upgrade signals
- Solution-not-problem: user described a concrete technical approach without stating the goal (+1 level)
- Patchwork pattern: this area has been repeatedly patched — check with
git log --oneline <path> if the change is non-trivial (+1 level, but only check git when Level 2 is already triggered by another signal)
- Disproportion: the proposed change seems oddly heavy or oddly light for what you infer the goal might be (+1 level)
Level 0 — Execute immediately
Quantitative floor: ≤ 2 files, no module boundary, no interface change, no ADR conflict.
Qualitative: no upgrade signals present.
Output: none. Just do the work.
Examples: fixing a typo, changing a color, adding a log line, updating a constant, renaming a local variable.
Level 1 — Brief flag
Quantitative floor: same as Level 0, OR slightly larger (2-3 files, minor interface addition like an optional parameter).
Qualitative upgrade: you spot a clearly better approach for the same inferred goal, OR the proposed solution creates obvious tech debt.
Output: one sentence. Do the work, then add a note:
"Done. Quick note: Y would also work and has the advantage of Z — want me to switch?"
If the user says "no, keep it" or ignores the note, move on. Do not argue. If the user says "yes, switch", execute the alternative directly — no plan needed.
Level 2 — Intent clarification
Quantitative floor: > 3 files, OR crosses ≥ 1 module boundary, OR changes an interface, OR conflicts with an ADR.
Qualitative: solution-not-problem signal is present (this is the most common trigger for Level 2).
Output: 2-3 hypotheses about what the user might really want. Present them neutrally, with alternatives for the most likely. Format:
## What I think you're trying to achieve
1. [Hypothesis A — most likely]
2. [Hypothesis B]
3. [Hypothesis C — if applicable]
## Alternatives worth considering
For hypothesis A: [1-2 alternative approaches better than the user's proposal]
For hypothesis B: [if different alternatives apply]
## Architecture note (if applicable)
[ADR reference, CLAUDE.md constraint, or codebase pattern that's relevant]
Which of these is closest to what you need?
After the user confirms intent:
- Do NOT jump into code.
- Output a 3-5 line execution plan: what files change, in what order, what the key design decision is.
- Wait for the user to confirm the plan before writing code.
Level 3 — Full discovery
Quantitative: the task requires designing new abstractions (new module, new data model, new API surface).
Qualitative: user says "I'm not sure how to do this", "what do you think?", or the instruction is too vague to even extract a concrete solution.
Output: hand off to the project's brainstorming skill. If brainstorming or xyz-harness-brainstorming is available, invoke it directly. First read CLAUDE.md and docs/adr/ for context, then let the brainstorming skill lead the exploration.
How to reconstruct intent
When the user gives you a solution, pause and run this mental chain:
Step 1: Reverse-engineer the problem
For the proposed solution, ask: what pain would this solve? Generate 2-4 hypotheses. Don't commit to one — hold them all as possibilities.
| If the user says "add X" | Possible real needs |
|---|
| Add a button/control | Automate the action; make it discoverable; work around a missing feature |
| Add a config/flag/option | Smarter defaults; different behavior per environment; avoid changing code |
| Add a cache/optimization | Actual performance pain; premature optimization; the real bottleneck is elsewhere |
| Copy/paste code from Y to Z | Extract shared abstraction; the two places actually need different things |
| Add a new endpoint/API | Another system needs this; the frontend is blocked; better to expose via existing API |
| Change the data format/structure | Downstream consumer has a need; the current model is wrong; UX requires different grouping |
Step 2: Check against architecture
Read these before forming an opinion:
- CLAUDE.md — project conventions, tech stack, coding patterns. Any constraints the project has declared.
- docs/adr/ — if it exists, scan the most recent ADRs (last 5 by number). These are decisions the team deliberately made.
If neither ADRs nor docs/adr/ exists: scan the project root and top-level directories for .md files that appear to be design docs, architecture overviews, or decision records (look for files with names like ARCHITECTURE.md, DESIGN.md, *.adr.md, or in directories like docs/, spec/, design/). Read the most relevant ones.
If no design documentation exists at all: treat this as a signal for more caution. Without documentation, you lack the full picture of project constraints and the solution space. The user's proposed solution might be perfectly reasonable in context you can't see. Still surface hypotheses and alternatives, but lead with curiosity, not correction — "I want to make sure I understand the goal before I dive in" rather than "your approach has problems."
When citing an ADR: you MUST first read the ADR file to verify it actually says what you're about to claim. Never cite an ADR from memory or assumption. If the ADR text doesn't support your point, don't cite it.
Ask for each hypothesis:
- Does this align with the architecture described in CLAUDE.md and the design docs?
- Would the proposed implementation violate a stated constraint?
- Is there existing infrastructure that already solves this?
Step 3: Expand the solution space
For each hypothesis, generate alternative approaches — not just the one the user proposed. Aim for at least 2 alternatives per hypothesis. The alternatives should vary in scope: sometimes a one-line config change replaces a 200-line feature.
Step 4: Decide intervention level
Apply the quantitative checks, then check for qualitative upgrade signals. When in doubt between Level 0 and Level 1, default to Level 0. When in doubt between Level 1 and Level 2, default to Level 1. Err on the side of less intervention.
Architectural ammunition
Your questioning is only as good as your evidence. Generic "are you sure?" is worse than useless — it erodes trust. Every challenge must be grounded in something concrete:
From CLAUDE.md:
- Coding conventions that the proposed solution violates
- Patterns the project has standardized on
- Constraints the project has declared
From docs/adr/ (or equivalent design docs):
- "ADR-0003 chose X over Y for reason Z. Your proposal reintroduces Y — is Z no longer relevant?"
- "ADR-0007 explicitly scoped this module to only handle A, not B. Your change would add B — should we revisit the ADR?"
From git history (supplementary, not primary):
- Only check git when Level 2 is already triggered by architecture or scope. Don't check it on every instruction.
- "This file has been modified 8 times in the last month. Each patch added a new special case. Is the underlying design the problem, not the missing feature?"
Anti-patterns to avoid
- Don't over-intellectualize. If the user says "rename getCwd to getCurrentWorkingDirectory," don't ask them to explore their naming philosophy. Just do it.
- Don't argue. If the user acknowledges the alternative and says "no, do it my way," execute their way. The skill's job is to surface options, not to win debates.
- Don't invent architecture. If the project has no design docs, don't fabricate constraints to justify your position. Work with what actually exists.
- Don't repeat yourself in this conversation. If you suggested an alternative earlier and the user shot it down, don't bring it up again. Cross-session memory is not guaranteed — only rely on what happened within the current conversation.
- Don't block small work. Level 0 exists for a reason. Most changes should pass straight through. If you find yourself intervening on every instruction, you're triggering too aggressively — recalibrate.
- Don't turn Level 1 into Level 2. A one-sentence flag is exactly that — one sentence. Do not add hypotheses, architecture notes, or alternatives. If you can't fit it in one sentence, you're actually at Level 2.
