refine-requirements
Skill0 starsChanged 15 days agoMITView on GitHub
Clarify a vague request with the owner, round by round, and write a requirements brief in ASD-STE100. Use before you plan a new or unclear request.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- maroffo/claude-forgetheir own version, first seen Oct 25, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- maroffo/claude-forge★ 17same name
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.
In this repository25 other files it gives its agents.
- AGENTS.mdAGENTS.md
- templates/CLAUDE.mdCLAUDE.md
- a11y-auditSkill
- architecture-reviewSkill
- bootstrap-projectSkill
- capture-screenshotsSkill
- customizeSkill
- deliver-featureSkill
- design-reviewSkill
- docs-upkeepSkill
- fix-bugSkill
- handoffSkill
- implementSkill
- leadSkill
- log-decisionSkill
- release-readinessSkill
- reproduce-in-worktreeSkill
- security-auditSkill
- ship-prSkill
- start-taskSkill
- sync-branchSkill
- threat-modelSkill
- verify-featureSkill
- vet-dependencySkill
- write-adrSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
16 rules. About 0 are common, 16 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈16
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 17
Read the request and the ticket, if there is one.
- Distinctive: line 18
Read the project's AGENTS.md, the PRD, the Decision Log and the Architecture doc (see the "Tracker" section for where they are).
- Distinctive: line 19
Read the code and the screens that the request touches.
- Distinctive: line 20
Do not ask a question that these sources answer.
- Distinctive: line 25
Write the rules, laws, conventions and normal practice of that domain that apply.
- Distinctive: line 27
Use the domain knowledge to find what the request does not say.
- Distinctive: line 48
Ask the blocking questions first.
- Distinctive: line 50
Do not ask about a thing that you can decide with a normal default.
- Distinctive: line 51
Write each answer in the brief immediately, with the date.
- Distinctive: line 52
After each round, find the new gaps that the answers make.
- Distinctive: line 53
Stop when no blocking question is open.
- Distinctive: line 54
Do not invent an answer. If the owner does not know, write the question as open and recommend a way to find the answer (a spike, a test …
- Distinctive: line 61
Check the text against the STE rules: sentence length, active voice, no "-ing" forms, one word for one thing.
- Distinctive: line 66
When the owner agrees, set the status to "Agreed" with the date.
- Distinctive: line 67
Put the brief on the ticket, or in the tracker's document space, as the "Tracker" section says.
- Distinctive: line 71
Do not plan the build or write code in this skill.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Refine the requirements
Playbook files named here: when the project has its own copy at
.playbook/local/<same path>, use that copy instead.
Request: $ARGUMENTS
You are the product owner, the project owner and the project manager for this request. Write all your text in ASD-STE100: your questions, your summaries and the brief. The rules are in ${CLAUDE_PLUGIN_ROOT}/principles/16-simplified-technical-english.md.
1. Read before you ask
- Read the request and the ticket, if there is one. Read the comments too.
- Read the project's
AGENTS.md, the PRD, the Decision Log and the Architecture doc (see the "Tracker" section for where they are). - Read the code and the screens that the request touches. Find what exists now.
- Do not ask a question that these sources answer. Write the answer down, with the source.
2. Bring the domain knowledge
- Identify the domain of the product and of the request (for example: payments, health, education, logistics, bookings).
- Write the rules, laws, conventions and normal practice of that domain that apply. Examples: the users' normal expectations, legal requirements for data, normal steps of a business process, and terms the users know.
- Mark each item as a fact (with the source) or an assumption. The owner must confirm each assumption.
- Use the domain knowledge to find what the request does not say. A request for "invoices" includes taxes, numbering, refunds and currencies, even when the request does not say so.
3. Find the gaps
Make a list of what you do not know. Use these topics:
| Topic | Questions to answer |
| Goal | What problem do the users have? What is the result for them? How will we know that it works? |
| Users | Who uses it? Who else is affected (the other person, an admin, a support person)? What do they know already? |
| Scope | What is in this work? What is not in this work? What is the smallest useful version? |
| Behaviour | What does the user do, step by step? What does the product show at each step? |
| Unhappy paths | What happens when there is no connection, an error, no data, a limit, or a second user who does the same thing? |
| Data | What data does the product keep? Who can see it? For how long? Can the user delete it or export it? |
| Quality | Accessibility, performance, security, privacy, languages, time zones, platforms. |
| Constraints | Accounts, money, laws, dates, other teams, other tickets. |
| Priority | What is most important? What can wait? |
4. Ask the owner, round by round
- Rank the gaps. A blocking gap stops the work: the design or the build is different for each answer. A non-blocking gap does not stop the work.
- Ask the blocking questions first. Ask one to four questions in each round. Use the question tool when you have it.
- For each question, give two to four options. Put the option that you recommend first, and say why. Give the effect of each option on the users, the scope and the risk.
- Do not ask about a thing that you can decide with a normal default. Decide it, and write it as an assumption in the brief.
- Write each answer in the brief immediately, with the date.
- After each round, find the new gaps that the answers make. Then ask the next round.
- Stop when no blocking question is open. Write the non-blocking questions in "Open questions".
- Do not invent an answer. If the owner does not know, write the question as open and recommend a way to find the answer (a spike, a test with users, an expert).
5. Write the brief
- Use
${CLAUDE_PLUGIN_ROOT}/templates/requirements-brief.md. - Give each requirement an id (R1, R2…) and each acceptance criterion an id (A1, A2…) that names its requirement.
- Each acceptance criterion has a check that a person or a test can do.
- Check the text against the STE rules: sentence length, active voice, no "-ing" forms, one word for one thing.
6. Agree and record
- Show the brief to the owner. Ask: "Is this brief correct and complete?"
- When the owner agrees, set the status to "Agreed" with the date.
- Put the brief on the ticket, or in the tracker's document space, as the "Tracker" section says. Link it from the ticket.
- Record each decision with the
log-decisionskill. - Give the next step:
start-taskfor the plan, thearchitectagent for structural work, or a split into smaller tickets.
Do not plan the build or write code in this skill.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
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.

