Skip to content

skillWorkflow

Requirements Clarification

Turns a vague request into a few pointed questions and written acceptance criteria before any code is written.

npx workspacetemplates add requirements-clarification --tool claude-code

Writes 1 file to .claude/skills/requirements-clarification/

.claude/skills/requirements-clarification/SKILL.md28 lines · 1.7 KBFile
---
name: requirements-clarification
description: Turns a vague request into a few pointed questions and written acceptance criteria before any code is written.
---

# Requirements clarification

Clarify before building. Write no production code in this skill.

## Steps

1. Read the request twice. Underline words that can mean two things: "fast", "users", "export", "better", "soon".
2. Look in the code and docs for answers first: existing behavior, similar features, roles and permissions, limits, and data that already exists. Do not ask a question the repository can answer.
3. Sort what is unknown into three bins. Blocks the design: ask. Changes effort but not the design: ask if cheap, otherwise assume. Detail that can be changed later: assume.
4. Ask at most five questions, most important first. Make each one concrete and answerable in a line, offer your best guess as the default, and show what each answer changes. Prefer "Should export include archived projects? Default: no, because the list view hides them" over "What should export include?".
5. Cover these areas: who does it and with which permission, the trigger and the inputs, the result and where it appears, edge cases (empty, huge, duplicate, concurrent, failed), what must not change, and scale or time limits.
6. When answers arrive, write acceptance criteria in plain Given, When, Then lines, each testable by a person or an automated test. Add explicit non-goals.
7. List remaining assumptions and who should confirm each.

## Rules

- Never invent business rules and present them as facts.
- Never exceed five questions in one round.
- Do not propose technology unless a requirement forces it.

## Report

Questions with defaults, then after answers: acceptance criteria, non-goals and assumptions.

What it does

Most rework starts with a request that sounded clear and was not. This skill has the agent check the code for what it can learn alone, then ask only the questions that would change the design, and finish with acceptance criteria you can test.

You get a short document the requester can agree to in a minute. If they cannot answer a question, it becomes a recorded assumption instead of a silent guess.

Example

you › Product wants 'export to CSV' on the reports page. Clarify it.

agent › Code check: reports page filters by date and team, and the API already pages at 500 rows. Questions: 1. Export the current filtered view or all data? Default: filtered view. 2. Columns as shown or all fields? Default: as shown. 3. Over 50,000 rows, block or send by email? Default: email link. Draft criteria: Given a filter is set, When I click Export, Then the file has exactly the rows the table shows.

Questions

Why limit it to five questions?
A long list gets skimmed or ignored. Five ranked questions with defaults usually get answered in one reply, and the rest become assumptions.
What if nobody answers?
The defaults you were shown are written into the document as assumptions with an owner, so work can start and any wrong guess is visible early.
  • Bug Report Triage

    SkillWorkflow

    Free
  • Codebase Onboarding

    SkillWorkflow

    Free
  • Context Management

    SkillWorkflow

    Free
  • Library Selection

    SkillWorkflow

    Free