requirements-clarity

Overview of requirements-clarity skill

The requirements-clarity skill is a structured clarification workflow for turning vague feature requests into implementation-ready requirements before anyone starts coding. It is best for product managers, tech leads, founders, and AI-assisted developers who often begin with requests like “add login,” “build a dashboard,” or “implement payments” but do not yet have enough detail to estimate, design, or ship safely.

What requirements-clarity is for

The real job-to-be-done is not “write a nicer prompt.” It is to reduce rework by forcing missing decisions into the open: scope boundaries, technical context, acceptance criteria, edge cases, constraints, and success measures. The skill does this through focused questioning and a PRD-style output path rather than a single generic brainstorming response.

Best-fit use cases

requirements-clarity fits best when:

• the request is ambiguous
• the feature is likely larger than a quick patch
• multiple teams or stakeholders are involved
• the stack, integrations, or non-functional constraints are still unclear
• you need something closer to a usable spec than a loose discussion

What makes this skill different from a normal prompt

The differentiator is process. The skill explicitly detects vague requirements, runs a structured gap analysis, asks questions in rounds instead of all at once, and uses a scoring model to judge requirement completeness. That makes it more adoption-worthy than a one-shot “help me refine this feature” prompt if your main problem is missing information, not writing polish.

When requirements-clarity is the wrong tool

Do not reach for requirements-clarity when the task is already code-near and specific, such as:

• a bug with clear reproduction steps
• a change request tied to exact files or line numbers
• a request that already includes code snippets
• work centered on an existing function or class

In those cases, ordinary implementation, debugging, or code review workflows are usually faster.

How to Use requirements-clarity skill

requirements-clarity install context

In the softaworks/agent-toolkit repository, this skill lives at skills/requirements-clarity. If your environment supports Skills installation from GitHub, the practical install pattern is:

npx skills add softaworks/agent-toolkit --skill requirements-clarity

If your agent runtime does not use that installer, read the skill directly from:
https://github.com/softaworks/agent-toolkit/tree/main/skills/requirements-clarity

Start with SKILL.md, then check README.md for the higher-level explanation.

Files to read before first use

Read these in order:

1. skills/requirements-clarity/SKILL.md
2. skills/requirements-clarity/README.md

SKILL.md is the important file for invocation behavior: when the skill should activate, when it should not, and how the questioning flow works. README.md is useful for understanding the scoring concept and expected outcome.

How the skill is meant to be triggered

requirements-clarity is designed for vague requests, not detailed engineering tickets. It should activate when the input lacks enough detail to build confidently. Good trigger examples:

• “Add login to the app”
• “Implement payment support”
• “Create an admin dashboard”
• “We need user management”

These are broad enough that the skill can add real value through clarification.

Inputs that produce the strongest output

The best starting prompt gives the skill just enough context to ask smarter follow-up questions:

• business goal
• target user
• current product or system
• known constraints
• rough deadline or delivery phase
• any must-have integrations
• any known exclusions

A weak input:

• “Build notifications.”

A stronger input:

• “We need in-app notifications for team admins in our SaaS dashboard. Stack is React + Node. MVP should cover system alerts and mention alerts, but not email yet. We need something small enough for this sprint and clear enough to estimate.”

The second version helps requirements-clarity ask fewer generic questions and move faster toward a usable spec.

How to turn a rough goal into a good invocation prompt

Use this shape:

• what the feature is
• why it matters
• who it serves
• where it lives
• technical environment
• constraints
• what you already know
• what is still undecided

Example:

“I need help using requirements-clarity for Requirements Planning. We want to add SSO to our B2B web app for enterprise customers. Current stack is Next.js, Node, and Postgres. We already support email/password login. We need a first-pass PRD covering MVP scope, admin setup flow, acceptance criteria, edge cases, and non-goals. Unknowns include which providers to support first and how provisioning should work.”

That prompt gives the skill something concrete to analyze without pretending the requirement is already finished.

Expected workflow in practice

A practical requirements-clarity usage flow looks like this:

1. Start with the rough feature request.
2. Let the skill identify missing requirement areas.
3. Answer the follow-up questions in small batches.
4. Review the clarified scope and explicit non-goals.
5. Ask for the final PRD-style output.
6. Use that output for estimation, design, or handoff.

The quality comes from completing the dialogue, not just reading the first response.

What the scoring system is good for

The repository describes a 100-point clarity model. The useful part is not the number itself; it is the checklist effect. It helps expose whether your request is missing:

• technical context
• acceptance criteria
• success metrics
• edge cases
• error handling
• scope boundaries

Use the score as a signal for “what still needs answers,” not as a vanity metric.

How many questions to answer at once

The skill’s own method favors one category at a time, usually 2–3 focused questions per round. That matters because dumping every unknown into one response often leads to shallow answers and hidden contradictions. Short rounds improve requirement quality and make stakeholder review easier.

What output to expect from requirements-clarity

A good run should leave you with:

• a clearer feature definition
• explicit assumptions
• boundaries for MVP vs later phases
• acceptance criteria
• notable edge cases
• constraints and dependencies
• a PRD-style artifact you can refine further

If you only get generic recommendations, the starting context was likely too thin or the conversation stopped too early.

Practical tips that improve requirements-clarity usage

• Name the product area clearly: “admin dashboard,” “checkout,” “mobile onboarding.”
• State known exclusions early: “No mobile app in MVP,” “No SAML in phase 1.”
• Include existing system facts: current auth method, current payment provider, current roles.
• Separate business need from implementation preference if both exist.
• Ask the skill to surface unknowns before proposing solutions if the team is still in discovery.

These small changes usually improve specificity more than asking for “more detail.”

requirements-clarity skill FAQ

Is requirements-clarity good for beginners?

Yes, especially for beginners who know the feature goal but do not yet know how to write strong requirements. The structure helps them avoid common omissions like missing edge cases, unclear scope, and absent acceptance criteria. It is also useful for experienced builders who need a repeatable intake process.

How is this different from asking an AI to write a PRD directly?

A direct PRD prompt often invents details to fill gaps. requirements-clarity is better when you want the model to identify ambiguity first, ask targeted questions, and only then move toward a PRD. That reduces false confidence and usually creates a more trustworthy planning document.

Can I use requirements-clarity for Requirements Planning only?

Yes. That is one of the best fits. The skill is especially useful in pre-implementation planning, backlog shaping, product discovery, and cross-functional alignment. You do not need to use it for final documentation only; it is valuable earlier, when the requirement is still unstable.

When should I skip requirements-clarity and use a coding skill instead?

Skip it when the work item already has clear implementation context:

• exact file references
• existing code under discussion
• clear bug steps
• narrow, low-ambiguity changes

If the main unknown is “how do I code this?” rather than “what exactly are we building?”, use a coding or review-oriented skill instead.

Does this skill require a specific tech stack?

No. The workflow is stack-agnostic, but the results improve when you provide the stack. Missing technical context is one of the gaps the skill is meant to detect, so naming your environment up front helps it ask more relevant questions.

Is requirements-clarity suitable for small tasks?

Sometimes, but not always. For tiny changes, the clarification overhead may be unnecessary. The skill is most valuable when the feature is ambiguous, risky, or large enough that rework would be expensive.

How to Improve requirements-clarity skill

Give requirements-clarity better raw material

The fastest improvement is better starting input. Include:

• user type
• business objective
• current workflow
• stack and integration context
• delivery constraints
• what is out of scope

This reduces generic questioning and helps the skill spend time on the real uncertainties.

Common failure mode: asking for solutions too early

Teams often jump straight to UI, database, or vendor choices before the problem and success criteria are clear. With requirements-clarity, ask first for requirement gaps, assumptions, and scope boundaries. Only then ask for solution options. That sequencing makes the output more durable.

Common failure mode: vague nouns

Terms like “dashboard,” “management,” “notifications,” and “enterprise support” hide major scope differences. Improve results by replacing vague nouns with concrete capability lists.

Instead of:

• “Need user management”

Try:

• “Need admin-only controls for inviting users, assigning roles, deactivating access, and viewing audit history”

That single change gives the skill a much better base for clarification.

Ask for explicit non-goals and edge cases

One of the best ways to improve requirements-clarity output is to request two sections every time:

• “What is explicitly out of scope?”
• “Which edge cases still need decisions?”

This helps prevent PRDs that look complete but still create implementation churn.

Iterate after the first draft, not before it

Do one full clarification pass, then refine. A productive iteration loop is:

1. initial request
2. answer follow-up questions
3. review generated requirement draft
4. correct assumptions
5. ask for tightened acceptance criteria and scope wording

That is usually better than trying to write the perfect initial prompt.

Use the final output as a handoff, not a final truth

Even strong requirements-clarity output should be reviewed by product, engineering, and any dependent teams. The skill is best treated as a requirement accelerator and quality gate, not a substitute for stakeholder sign-off. The strongest adoption pattern is: clarify first, review second, implement third.