requirements-definition
Use for requirement analysis, specification, and clarification, and when running /define. Covers its phase sequence (prepare through document), the investigation gate, read-only agent dispatch, questi
SKILL.mdhome-manager/ai-tools/agent-skills/skills/requirements-definition/SKILL.md
GitHubThe phase sequence /define executes, so the command file does not restate it, plus question design and requirement formatting.
Read-only throughout: no file or memory is created or modified, and no code is written. Return the document in the response. Report any memory candidates for a later write-authorized phase.
Phases
prepare: Load serena-usage before any memory operation and any other companion this run needs: fact-check when a claim needs an external source, workflow-patterns for the shared decision-criteria structure. Then activate the project when Serena is available, check the memory catalog once, and read only relevant entries. If the store is unavailable, continue from repository evidence and report the limitation.
analyze: Extract the core requirements from the request, identify the technical constraints its context implies, name the design decisions that will need user input, and take a first read on feasibility.
investigate: Establish the relevant files, patterns, dependencies, and schema implications. Delegate bounded independent checks only when their value warrants coordination, using the available agent catalog. If a needed role is unavailable, perform its checks yourself and report the limitation; do not substitute a role whose runtime restrictions are unavailable. Verify external library claims with Context7 when available, otherwise with official documentation, rather than recall.
clarify: Prioritize and classify the candidate questions as described under
Which questions to ask first. Ask only when readings differ in a destructive
or externally visible effect (CLAUDE.md work_selection); use the runtime's question tool with its supported
options and one marked (Recommended), or a concise question in text. Every other open question becomes a
recorded assumption in the document, tagged inferred or assumed, and work proceeds.
verify: Cross-check the user's answers against the investigation findings, and read the implementations the chosen approach depends on.
document: Produce the requirements document and the phased task breakdown for /execute. This is the last phase: there is no approval prompt afterwards.
Gate after investigation
- The files and existing patterns the requirement will build on.
- The scope boundary: what is explicitly out of scope.
- Any technical blocker found, or that none was and what was checked.
Unmet: widen the investigation, or record the gap as an assumption. Never write a requirement around an unexamined area.
Unresolved items
Outstanding Issues lists each unresolved item with the assumption taken. Do not ask the user to resolve, defer, or stop. State whether the handoff is ready or partially blocked, naming the tasks that depend on an assumption that could not be checked. Recording an assumption does not verify it or clear a dependent task's gate.
Agents
All read-only. Every delegation carries the scope, the target paths, the explicit prohibition on editing, and the instruction to use the runtime's question tool when available, otherwise a concise question in text.
- explore: relevant files and existing patterns
- design: architectural consistency, dependencies, API design
- infra: schema, migration, and query implications
- general-purpose: requirements completeness, dependency risk, effort in tree-derived units
- verification (read-only reconcile mode): cross-validation when findings conflict
When selected, independent explore, design, and infra checks dispatch together. A general-purpose check of their combined findings follows only when completeness or dependency risk needs a separate review.
Investigate before asking
Establish the current state first: directory structure, the symbol overview of the affected area, keyword and symbol search for the feature's existing neighbours, the reference graph around anything that will change, then the specific files. Verify external library behavior with Context7 when available, otherwise with official documentation, rather than recall.
A question that investigation could have answered spends the user's turn. The point of investigating first is not thoroughness for its own sake: it is that the remaining questions are then exactly the ones only the user can settle.
Which questions to ask first
Rank a candidate question by four considerations, in this order:
- Design branching: how much the answer changes the shape of the solution.
- Irreversibility: how expensive the wrong choice is to undo after implementation.
- Investigation impossibility: whether code investigation could settle it instead. If it could, investigate rather than ask.
- Effort impact: how much the answer moves the size of the work.
A question is critical when it branches the design and the wrong answer is expensive to undo. Record the assumption taken for a critical question prominently in Outstanding Issues; ask only under the destructive or externally visible rule in clarify.
Classify each question
- Spec confirmation: "does the API return null or an empty array for no results?"
- Design choice: "REST or GraphQL?"
- Constraint: "must this support the legacy client?"
- Scope: "are admin features in the first version?"
- Priority: "which of these ships first?"
When a question is asked, use the runtime's question tool, respecting its supported option count and marking a recommendation when supported. If no question tool is available, ask a concise question in the response.
Writing the requirements
Functional requirements carry an identifier, a priority, and acceptance criteria specific enough to test:
FR-001: User Authentication
Priority: mandatory
- Users log in with email and password
- A session expires after 24 hours of inactivity
- Failed attempts are rate-limited to 5 per hour
Mark every requirement mandatory or optional with the reason: treating all requirements as equally important is the same as prioritizing none.
Non-functional requirements carry a measurable target, not an adjective: a response-time percentile and its threshold, a concurrency figure, the encryption at rest, the documented surface. "Fast" and "secure" are not requirements.
Technical specifications carry each design decision with its rationale and its impact scope: what the decision was, why it beat the alternatives, and which parts of the system now depend on it.
Describe what must be achieved, not how to implement it. A requirement that names function names or algorithms has taken a decision away from the implementer under the guise of specifying it.
Document every assumption explicitly where a requirement is unclear, and identify the technical and operational constraints rather than leaving them to be discovered.
Feasibility is a condition, not a score
State which capability was located at which file:line, and which was not found and where it was searched for.
Feasible: the export pipeline this depends on exists at
src/export/pipeline.ts:42. No rate-limiting primitive exists in the codebase (searchedsrc/lib,src/middleware), so that remains an open constraint recorded in Outstanding Issues.
A feasibility number produced in the same pass that wrote the requirement never contradicts that requirement, so nothing downstream ever reads a low score and investigates further.
Record explicit user requests as desired behavior, not as unverified claims about the existing system. Tag factual premises verified (grounded in direct investigation), inferred (derived from something verified but not directly observed), or assumed (unchecked). A factual premise still assumed at handoff time is not ready to support dependent implementation. A partial handoff must name those blocked tasks separately from independent, ready tasks; recording the assumption does not approve it.
Map every requirement to a test
Unit coverage expectations, integration scenarios, and the acceptance criteria as observable behavior. A requirement with no test scenario is a requirement nobody will notice going unmet.
Output
A requirements document carrying what the implementation needs, and omitting empty sections: the request in one sentence with its background and expected outcomes; the current system and stack; functional requirements in FR-001 form marked mandatory or optional; non-functional requirements when applicable; technical specifications with each decision's rationale; test requirements as observable behavior; and Outstanding Issues when any remain.
Feasibility is stated as the observable condition supporting it, per the section above, never as a score. Where a requirement rests on an assumption rather than on investigation, say so at that requirement.
Then the task breakdown: the dependency graph, phased tasks with files and dependencies, and the handoff carrying the decisions made, the references, and the constraints, including what /execute must not assume.
Related
- investigation-patterns: establishing current state and evidence for feasibility
- testing-patterns: turning acceptance criteria into tests
- serena-usage: the memory operations in prepare
- fact-check: verifying an external claim
- execution-workflow: what happens to the handoff afterwards
- workflow-patterns: the decision-criteria template and the numeric-self-assessment prohibition