Requirements Clarification skill for Claude Code

Clarification is done when the user has confirmed a one-page brief: the goal in one sentence, acceptance criteria that can be checked, explicit scope and non-goals, and an assumptions log where every assumption is either confirmed or marked as a known risk. The aim is the fewest questions that remove the most risk, not an interrogation.

When to clarify vs. just proceed

Situation	Action
Clear request, one reasonable interpretation, cheap to change	Proceed; state assumptions in one line
Several interpretations with different code, or expensive to redo	Clarify first
Touches money, security, data deletion, public APIs, migrations	Clarify first, always
User said “you decide” and options differ in user-visible behavior	Propose a default with trade-offs; get a yes
You can answer it by reading the code, docs, or data	Do not ask; look it up

Workflow

- [ ] 1. Restate the request in one sentence; list every ambiguous noun and verb
- [ ] 2. Research what the codebase, docs, tickets, and data already answer
- [ ] 3. Rank remaining unknowns by (cost if wrong) x (likelihood of being wrong)
- [ ] 4. Ask 3-7 questions in one batch, each with a proposed default
- [ ] 5. Write the brief: goal, acceptance criteria, scope, non-goals, assumptions
- [ ] 6. Get explicit confirmation; then hand off to planning or implementation

1. Find the ambiguity

Underline words that hide decisions. “Add CSV export to the reports page”:

Word	Hidden decisions
add	New button, menu item, or API? Who can see it (roles)?
CSV	Delimiter, encoding (UTF-8 with BOM for Excel?), date and number formats
export	Current filtered view or all data? Sync download or emailed file for large sets?
reports page	Which of the 6 report types? All columns or visible ones?

Also check the five dimensions that most often go unstated: who (users, roles), when/scale (data volume, frequency), quality bars (latency, accuracy), failure behavior (errors, partial results, retries), constraints (deadline, compatibility, compliance).

2. Research before asking

rg -n "export|csv" src/ --glob '!**/*.test.*' | head -30     # existing patterns or half-built features
gh issue list --search "csv export" --state all --limit 10    # prior requests, decisions
ls docs/ docs/adr/ 2>/dev/null

Look at similar features for conventions (how other downloads work, permission checks, size limits). Every question you answer yourself is one the user does not have to.

3. Rank unknowns

Ask about high cost x high uncertainty first. Defer or assume the rest:

Unknown	Cost if wrong	Uncertainty	Handle
Filtered view vs. all rows	High (different query + perf)	High	Ask
Max rows	High (sync vs. async design)	Medium	Ask with default
Delimiter	Low	Low	Assume comma, log it
Button placement	Low	Medium	Assume next to Filter, log it

4. Ask well

One message, numbered, each question answerable in a word or two, each with your recommended default and why. Offer options, not open-ended prompts.

Before I build CSV export, five decisions. My default is in bold; reply "defaults ok" or override by number.

1. Rows: **the current filtered view** / all rows in the report?
2. Size: largest reports have ~400k rows. **Sync download up to 50k rows, otherwise email a link** / always sync / always email?
3. Columns: **visible columns in current order** / all columns?
4. Access: **same roles that can view the report** / admins only?
5. Excel compatibility: **UTF-8 with BOM so Excel shows accents correctly** / plain UTF-8?

Assuming (tell me if wrong): comma delimiter, ISO 8601 dates, filename `report-<name>-<date>.csv`.

Avoid: asking things the code answers, asking one question per message, yes/no questions that hide the real choice (“Should it be fast?”), and leading with implementation details the user does not care about.

5. The brief

# CSV export for reports — brief (confirmed 2026-10-20)

**Goal:** Analysts can download what they see in a report as a CSV that opens correctly in Excel.

**Acceptance criteria**
- AC1 Export button on all 6 report types, visible to anyone who can view the report.
- AC2 File contains the current filtered rows and visible columns in on-screen order.
- AC3 Up to 50,000 rows downloads within 10 s; larger exports email a link valid 24 h.
- AC4 Accented characters display correctly when opened in Excel (UTF-8 BOM).
- AC5 Export is recorded in the audit log with user, report, row count.

**In scope:** reports page UI, export endpoint, async job for large exports.
**Non-goals:** XLSX format, scheduled exports, API access for exports.

**Assumptions**
| # | Assumption | Status |
|---|---|---|
| A1 | Comma delimiter, ISO 8601 dates | confirmed |
| A2 | Existing email service can send links | confirmed by code (src/mail/send.ts) |
| A3 | 400k-row export completes in under 5 min as a job | RISK: unverified, spike in task 1 |

**Open questions:** none blocking.

Acceptance criteria rules: observable from outside (UI, API, file, metric), with numbers where quality matters, one behavior each, and testable by someone who did not write the code. “Fast” and “user-friendly” are not criteria.

6. Confirm and hand off

Ask for an explicit yes on the brief. Then continue with task-decomposition-plans for the plan or spec-driven-development for a larger feature. If new ambiguity appears during implementation, add it to the assumptions log and ask again rather than deciding silently.

Gotchas

• Asking too much: more than ~7 questions means you have not researched or ranked. Assume the low-cost items and log them.
• Asking too little on irreversible things: data deletion, money movement, public API shape, and migrations always get an explicit confirmation.
• Accepting the proposed solution as the requirement (“add a cache”) without the problem (“page loads in 6 s, target 1 s”). Ask what outcome they need; offer the solution as one option.
• Silent assumptions discovered at review time are the most expensive kind. Log them.
• Users often answer the question asked, not the one that matters. Restate the decision in their words in the brief so misreadings surface.

Output

The confirmed brief (template above), plus a one-line handoff: “Brief confirmed; next: plan in plans/csv-export.md, starting with the A3 performance spike.”