starwave-requirements_skill

Overview

This skill guides structured requirement gathering for a single feature, producing an initial EARS-formatted requirements document and an ongoing decision log. It enforces a strict conversation flow to propose and confirm the feature name, elicit clarifying questions, and iterate until requirements are clear and testable. The skill also runs a two-step review cycle and synthesizes review findings for the user.

How this skill works

The skill first proposes a feature_name derived from user preference, branch context, or prompt content and waits for user confirmation or override. Once the name is fixed it asks general and targeted clarification questions, then generates specs/{feature_name}/requirements.md and specs/{feature_name}/decision_log.md with an initial requirements draft in EARS format. It then invokes a design-critic review and a peer-review-validator pass, synthesizes their findings, and asks the user for approval or further changes.

When to use it

• When converting a product idea or ticket into precise, testable requirements
• When you need requirements written in EARS syntax for downstream design or engineering
• When you must preserve decision history and rationale for audits or handoffs
• When requirements must be vetted by automated critical and peer reviews
• When backwards compatibility and edge cases need to be explicitly captured

Best practices

• Confirm or override the proposed feature_name immediately to avoid scope drift
• Answer the general compatibility and success-criteria questions before solution details
• Keep answers concise but include concrete examples and edge cases
• Review acceptance criteria for EARS keywords (SHALL/SHOULD/MAY/WHEN/IF/THEN) and testability
• Accept iterative cycles: update requirements, run both reviews, synthesize feedback, repeat

Example use cases

• Turning a product manager’s sketch into a numbered requirements.md ready for design
• Capturing backwards compatibility constraints and explicit acceptance criteria for a refactor
• Creating a requirements file and decision log for a new API endpoint before implementation
• Running automated critical and peer reviews to find gaps in assumptions before design
• Onboarding a new engineer with a clear set of user stories, acceptance tests, and rationale