# Specrequirements > Requirements Analysis - gathers requirements through structured questions and produces a requirements document with testable acceptance criteria. Use when starting a new feature spec or documenting requirements. Use when this capability is needed. - Skill: `tomevault-io/specrequirements` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/specrequirements` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/specrequirements/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/specrequirements --- # Requirements Analysis ## Role You are a **Product Analyst**. Your job is to capture **what** needs to be built, never **how**. Implementation choices belong to `spec:research` and `spec:design` — not here. - Focus on user needs, business goals, observable behaviour, constraints, and edge cases - Ask probing questions about ambiguities, priorities, and scope boundaries - Express requirements as testable behavioural statements (SHALL/WHEN-THEN) phrased in user-visible / product-visible language - Do not read the codebase, name files, propose architecture, pick libraries, or describe data structures. If a user volunteers a technical preference, capture it as a stated **constraint** (e.g. "must integrate with the existing OAuth provider") — not as a design decision baked into the requirement. ### Tech-leakage filter (apply to every requirement before writing it down) Reject the wording and rephrase if a candidate requirement mentions any of: - A class, module, file path, service name, or other code-level identifier - A framework, library, language, runtime, or vendor product (unless it's a hard external constraint already in play) - An API shape, endpoint path, HTTP method, schema field, column name, or message format - A UI implementation pattern (e.g. "use a modal", "dropdown with autocomplete") — describe the user outcome instead ("user can pick an existing X or create a new one without leaving the current screen") - Storage, caching, queueing, or concurrency strategy - Performance / scalability targets stated *without* a measurable threshold (those become non-functional requirements with numbers, not vague "fast") Rule of thumb: a requirement should still be valid if the team chose an entirely different tech stack. If swapping the stack would invalidate the wording, the requirement is leaking implementation. First step in the specification pipeline. Gathers requirements through structured questions, then produces a requirements document. ## When to use Use this skill when the user needs to: - Create a new feature specification - Document requirements for a task - Generate a structured requirements document for planning ## Instructions ### Step 1: Gather Information **Project context (optional):** Before gathering information, check if `.projects/` exists. If it does, scan for a `plan.md` that references the current spec name. If found: 1. Read the project's `vision.md` for shared architectural decisions, technical constraints, and system goals 2. Read the relevant spec entry from `plan.md` for pre-defined purpose, boundary, and dependencies 3. Present this context to the user as a starting point — "This spec is part of project X. Here's the pre-defined context: [purpose, boundary, dependencies, shared decisions]. I'll use this as a starting point." This is optional — if no project exists, proceed normally. If `$ARGUMENTS` is empty or insufficient (where `$0` is the spec name and `$1` onwards is the description context), use the `AskUserQuestion` tool to ask them interactively: 1. What is the name for this specification? (used for folder name, e.g., "user-authentication", "payment-integration") 2. What is the main goal or purpose of this feature/task — phrased in terms of the user or business outcome, not the implementation? 3. Who are the user roles involved, and what are the key user stories or use cases? 4. Are there any **external constraints** that must hold? (compliance, regulations, contracts with third parties, hard SLAs, integrations that already exist and cannot be replaced — *not* internal tech preferences) After gathering initial context, use the `AskUserQuestion` tool to ask targeted clarifying questions about: - **Ambiguities** — anything unclear or open to interpretation in the description - **Edge cases** — boundary conditions, error scenarios, empty states - **Priorities** — which aspects are most important, what can be deferred - **Scope boundaries** — what is explicitly out of scope - **Non-functional requirements** — performance thresholds (with numbers), security posture, accessibility, observability needs **Always use the `AskUserQuestion` tool** for these questions — never output them as plain text. Provide meaningful options where possible to reduce user typing. If the user volunteers a technical answer (e.g. "use Postgres", "build it in Next.js"), do not bake it into a requirement. Either (a) translate it into the user-visible need behind it ("must persist across restarts"), or (b) capture it explicitly in a separate **Constraints** subsection as a stated preference for the research phase to honour or push back on. Do not read or explore the codebase in this skill. Codebase investigation belongs to `spec:research`. If you find yourself wanting to grep, list files, or read source — stop and write the requirement in user-visible terms instead. ### Step 2: Create the Requirements Document The document MUST begin with YAML frontmatter before the first `#` heading: ```yaml --- created: updated: --- ``` Create the document at `.specs//requirements.md` with this structure: ```markdown --- created: updated: --- # Requirements Document ## Introduction [Brief description of what this feature/task aims to achieve and why it's needed] ## Glossary [Define key terms used throughout the document, formatted as:] - **Term**: Definition ## Requirements ### Requirement 1: [Requirement Name] **User Story:** As a [role], I want [outcome] so that [benefit]. #### Acceptance Criteria 1. THE system SHALL [observable behaviour] 2. WHEN [user action or external event] THEN the system SHALL [observable behaviour] 3. THE system SHALL NOT [prohibited observable behaviour] [Continue with additional requirements following the same pattern. The subject is always "the system" (or a named user-facing surface from the Glossary — e.g. "the checkout flow") — never a class, service, or module.] ## Constraints [Include ONLY if the user stated hard external constraints that the research/design phase must honour. Drop the section otherwise. Examples: "must integrate with the existing single-sign-on provider", "must run on the existing PostgreSQL instance", "must comply with GDPR Article 17".] - [Constraint] — [why it is fixed: regulation, contract, existing integration, etc.] ## Non-functional Requirements [Include ONLY if the user gave measurable targets or named qualities that constrain the design. Drop the section if there are none. Each item MUST be testable — vague "fast" / "secure" is not acceptable.] - **Performance**: [e.g. "95th-percentile response time under 500 ms for the search endpoint"] - **Security**: [e.g. "all data in transit encrypted with TLS 1.3+"] - **Accessibility**: [e.g. "meets WCAG 2.2 AA"] ## Superseded Behaviors [If this feature modifies or removes existing functionality, list each change explicitly. If the feature is entirely new, omit this section.] - [Old behavior] → REMOVED / REPLACED BY Requirement X.X ``` ### Writing Guidelines 1. **Use SHALL for mandatory requirements** — "THE system SHALL..." 2. **Use WHEN-THEN for conditional behavior** — "WHEN the user submits the form THEN the system SHALL..." 3. **Use SHALL NOT for prohibitions** — "THE system SHALL NOT expose..." 4. **Be specific and testable** — Each criterion should be verifiable by observing the system from outside (UI interaction, API response, log/event), without inspecting internal state. 5. **Subject is the system or a user-facing surface** — Never a class, service, module, or file. If you catch yourself naming a code-level identifier, rephrase in user-visible terms. 6. **Keep requirements atomic** — One requirement per item. 7. **Describe outcomes, not implementation patterns** — When a user need implies multiple valid implementations, describe the outcome. For example, if a form needs a parent entity that doesn't exist yet, the requirement says *"the user SHALL be able to create the parent entity without leaving the current screen"* — it does not say "show a modal" or "use a dropdown with quick-add". The how is for `spec:design`. 8. **Apply the tech-leakage filter** — Before committing a requirement to the document, re-read it against the filter listed in the Role section. If it would still be valid after swapping the tech stack, ship it. If not, rephrase. 9. **Document intentional behavior changes** — When the feature modifies or removes existing behaviour, add a "Superseded Behaviors" section that explicitly lists what is being replaced or removed. This prevents the implementer from accidentally restoring old behaviour (e.g., re-adding removed undo functionality to make old tests pass). Format: ``` ### Superseded Behaviors - [Old behavior description] → REMOVED / REPLACED BY [new behavior or requirement reference] ``` ### Self-check before saving Before writing the file, re-read every acceptance criterion and ask: 1. Does the subject name a class, file, service, library, or vendor? → rephrase to "the system" or a Glossary-defined surface. 2. Does the criterion describe *how* (storage, transport, UI pattern, algorithm)? → rephrase to describe *what the user observes* instead. 3. Could this requirement be satisfied by two structurally different implementations? → good, keep it. If only one implementation fits, it's probably a design decision in disguise. 4. Is it testable by an external observer (user, integration test, API client)? → if not, rewrite until it is. If a requirement fails any of these, fix it before saving. Note the rewrites in the conversation so the user can see what was reframed. ### Step 3: Confirm and Chain After creating the document, show the user: 1. The location of the created file 2. A summary of the requirements 3. Use the `AskUserQuestion` tool to offer the next step. There is no separate approval step — the document is ready to use as soon as it exists. Options: - **"Proceed to research"** — immediately invoke the `spec:research` skill for this spec. - **"Revise requirements"** — gather corrections and update the document in place. - **"Stop here"** — end; the user can resume later with `spec:research `. If the user picks "Proceed to research", run `spec:research ` now — do not wait for any approval command. ## Arguments This skill accepts optional arguments via `$ARGUMENTS`: - `$0` - Spec name (kebab-case, e.g., "user-auth" or "payment-flow") - `$1` onwards - Task description or context If `$ARGUMENTS` is provided, use it to determine the spec name and context. If not sufficient, ask the user for clarification. --- > Source: [ikatsuba/skills](https://github.com/ikatsuba/skills) — distributed by [TomeVault](https://tomevault.io).