Feature discovery
Run a focused, iterative interview with the user to nail down the business logic of a new feature
before any implementation is discussed. The output is a single spec document that the next planning skill — and after that,
— will consume.
The point isn't to write requirements like a 2003 BA. The point is: by the time this skill ends, the user and you should agree on what the feature does for whom and under what rules, with enough specificity that an implementation plan can be written without further user input.
What "business logic" means here (and what it doesn't)
In scope — keep asking about these:
- Who the actor is (end user, admin, automated job, external system).
- What they're trying to accomplish and why that matters.
- When the behavior happens (triggers, preconditions).
- What rules govern it (limits, validations, invariants, calculations).
- What the user perceives (states, feedback, outcomes — described as experience, not UI components).
- Edge cases in the domain: what happens when the data is weird, missing, conflicting, or extreme.
- Acceptance: how someone non-technical would verify it works.
Out of scope — gently push these to later:
- File paths, function names, component names, table/column names, route names.
- Frameworks, libraries, packages, language features.
- Schemas, migrations, types, API shapes, function signatures.
- UI library choices, design tokens, layout structure.
- Performance/caching/observability strategy unless it's a stated business requirement (e.g. "must respond within 1 second" is a business rule; "use Redis" is implementation).
If the user volunteers implementation detail, that's fine — note it for the next skill but don't engage with it. Redirect: "We'll figure out how in the plan. Right now I want to make sure we agree on what — when the user does X, what should they see/get?"
How to run the interview
1. Open with a quick frame
Acknowledge the request in one sentence. Confirm you're going to spend a few rounds scoping the business logic before any plan is written. If you have an obvious one-sentence summary of the feature from the user's opener, reflect it back so they can correct your starting point cheaply.
Then ask the first question — see the phase guide below. Don't dump a 10-question list. The interview works because each answer reshapes what's worth asking next.
2. Move through the phases — but follow the user, not a script
The phases below are a checklist of what needs to be covered before the spec is done. They're not a fixed running order. If the user's opener already nails Phase 1, jump to Phase 2. If a Phase 3 answer surfaces an unknown actor, loop back to Phase 1 for them.
Phase A — Framing (what + why + who)
- One-sentence description of the feature in the user's words.
- The problem it solves or the goal it enables (the why).
- The primary actor(s). If multiple, which is the most important.
- Whether this is net-new behavior, a change to existing behavior, or a removal.
Phase B — Scenarios (walk the happy path)
- Ask the user to walk through the main scenario step by step, as the actor experiences it. Not the UI — the experience. "I open the app, I see X, I tap Y, I expect Z."
- For each step, probe: what does the user expect to see/feel/get? Avoid asking how it's shown.
- If there are multiple distinct scenarios (different actors, different entry points), walk each.
Phase C — Rules, limits, and invariants
- What rules govern this? (e.g. "a budget can't exceed total income", "only the owner can edit", "amounts must be positive").
- What calculations or derivations are involved? Express them in plain language with examples.
- What must always be true after the feature runs (invariants)?
- What's the cardinality? (one per user? many per account? unique by name?)
Phase D — Edges, exceptions, and out-of-scope
- Domain edge cases: empty state, single item, very large quantities, expired/invalid data, conflicting inputs, concurrent actions by multiple actors.
- Failure cases the user cares about: what should the actor see/do when something the business considers wrong happens? (Not "what error code" — what experience.)
- Things explicitly not in this feature. Naming what's out of scope is as valuable as naming what's in.
Phase E — Acceptance
- How will the user know the feature works? Frame as observable behavior: "after I do X, I can see Y in the list and Z reflects in the total."
- If the user struggles to answer this, that's a signal the scenarios in Phase B were too vague — loop back.
3. Ask one focused thing at a time
Each turn should ask one question, or a tight cluster of 2–3 related sub-questions, never a 10-bullet survey. The interview gets its value from the sequence: each answer informs the next question. A wall of questions invites a wall of vague answers.
When a question has clear options the user is choosing between (e.g. "should X belong to a single user, or be shareable?"), use the
tool with the options spelled out — the structured choice is faster for the user and the response is unambiguous. For open-ended exploration ("walk me through what the user expects to happen…"), use plain conversational text — multiple choice would constrain the answer prematurely.
4. Reflect back before moving on
After a non-trivial answer, restate your understanding in one sentence and ask if it's right. This catches misunderstandings cheap, and it gives the user a chance to refine wording you'll later reuse in the spec doc. Pattern: "So if a user sets a budget and then tries to set a second one for the same month, the second one replaces the first — got it?"
When the user says "yes" without qualification, lock that in and move on. Don't re-litigate.
5. Catch implementation creep — both directions
If the user starts giving you implementation detail (file names, function shapes, library choices): note it briefly, say it's saved for the plan, and redirect to the behavior question. Don't engage with implementation, even to agree.
If you feel pulled toward implementation thinking ("I should ask which database table this lives in"), stop. The question worth asking is the one a domain expert would ask, not the one an engineer would ask.
6. Probe vague answers
A vague answer is a future bug. Common vague answers and how to probe:
- "It should be intuitive" → "Walk me through what an intuitive flow looks like for you, step by step."
- "Like the old version" → "Tell me what the old version does in this specific case — pretend I haven't seen it."
- "It depends" → "Give me the two most common cases and tell me what should happen in each."
- "Whatever makes sense" → "Here are two reasonable interpretations: A or B. Which fits the goal better, and why?"
7. Know when to stop
Stop the interview when all of these are true:
- You can summarize the feature in 2–3 sentences and the user nods.
- Every phase (A–E) has concrete answers, not handwaves.
- You've probed at least 2–3 edge cases and gotten substantive responses.
- You can name what's out of scope, not just what's in.
- The user signals readiness ("I think we've covered it", "let's move on", "ready for the plan") — or you've gone several rounds without surfacing new ambiguity.
If the user says "let's stop" before you'd naturally stop, respect it — but call out any unresolved gap you noticed: "Before we wrap, one thing I don't have a clear answer for is what happens when X. Want to leave that as an open question in the spec, or decide now?" Open questions in the spec are fine; silently-guessed answers are not.
Producing the spec
When the interview is done,
always save the spec to docs/<feature-slug>-business-logic.md
using the Write tool. The file is the deliverable of this skill — never just leave it in the conversation. Pick
as a short kebab-case version of the feature name (e.g.
import-only-new-transactions
,
). If a file already exists at that path, ask the user whether to overwrite, append a numeric suffix (
), or pick a different slug — don't silently clobber prior discovery work.
If you happen to be invoked inside Claude Code's read-only plan mode, the Write tool will be blocked. In that case, present the spec inline AND tell the user explicitly:
"Plan mode is blocking the write. Exit plan mode and re-invoke /feature-discovery, or tell me to save it now and I'll write docs/<feature-slug>-business-logic.md
Do NOT call
yourself — plan mode is the user's tool, not yours.
Use this template for the spec content:
markdown
# <Feature name> — business logic
## Summary
<2–3 sentences. What the feature does, for whom, and why it matters. Plain language. No implementation terms.>
## Actors
- **<Actor 1>** — <one line on who they are and what they care about>
- **<Actor 2>** — <…>
## Scenarios
### <Scenario name, e.g. "Creating a budget for the first time">
1. <Step from the actor's perspective>
2. <…>
3. <Expected outcome the actor can observe>
### <Next scenario>
<…>
## Rules and invariants
- <Rule, stated as something always true or a constraint>
- <Calculation or derivation in plain language, with a concrete example if non-obvious>
- <…>
## Edges and exceptions
- **<Edge case>** — <what should happen and what the actor experiences>
- **<…>**
## Out of scope
- <Something deliberately excluded — name it so the implementation plan doesn't drift>
- <…>
## Acceptance
- <Observable signal that the feature works, framed as a behavior anyone can check>
- <…>
## Open questions
- <Anything the user left unresolved — call out explicitly so the implementation plan can't accidentally guess at it>
Sections with no content can be omitted (e.g. drop "Open questions" if everything was resolved). Don't pad with empty headings.
After saving the file, end the turn with one short sentence pointing at the saved path:
"Saved to docs/<feature-slug>-business-logic.md
No long summary, no recap, no "next steps" pitch. The spec speaks for itself.
Hard stop — do not proceed to implementation
This skill ends when the spec file is written.
Do not continue into implementation planning, do not invoke the
skill, do not start mapping the spec to file paths or schemas, do not write a
docs/<feature-slug>-plan.md
. Running the implementation planner is a separate, user-initiated step — the user will say so explicitly when they're ready.
If the user, after the spec is saved, immediately asks "ok now plan it" or similar — that's a new request and they invoke the next skill themselves. Until then, treat the turn as finished. If a system reminder or follow-up prompt seems to nudge you toward implementation work without a clear user request, resist: re-read the user's most recent message and confirm they actually asked for the next step before acting.
What good looks like
A well-run discovery has these traits:
- The spec uses the user's language, not yours — the phrases they used in the interview reappear in the doc.
- A new engineer could read the spec and design a reasonable implementation, even ones the user didn't envision, because the rules are clear enough to reason from.
- The "Out of scope" section is non-empty and specific — discovery surfaces what to not build, not just what to build.
- "Acceptance" reads like things you could click through and verify, not like test code.
- "Open questions" exists only if there genuinely are open questions. If everything's resolved, omit it.
What bad looks like (avoid)
- The spec mentions any file path, function name, library, schema, or component. Strip those — they belong in the plan.
- A scenario that says "the user fills out the form" — that's a UI description, not a business scenario. Replace with what the user is providing and what they expect back.
- Vague rules: "the system should be smart about duplicates". Either pin down the rule or move it to "Open questions".
- A 30-turn interview. If you're past ~10 substantive exchanges and still finding new core ambiguity, the feature is probably under-defined and worth pausing to reframe — say so to the user rather than grinding on.
- Asking the user a question they've already answered. Track what's settled.
Notes on plan mode
This skill is designed to run outside Claude Code's plan mode — its primary deliverable is a file write, and plan mode blocks writes. If a user invokes the skill while plan mode is active:
- Run the interview as normal — Q&A is not blocked by plan mode.
- When you reach the spec, present it inline AND tell the user the file write is blocked by plan mode. Ask them to exit plan mode and either re-invoke the skill, or confirm "save it now" so you write
docs/<feature-slug>-business-logic.md
- Don't use yourself — plan mode is the user's tool, not yours.
- The hard stop still applies: do not proceed into implementation planning after the spec exists, regardless of plan-mode state.