# En > Requirements review for testability, completeness, and consistency (shift-left) - Skill: `smirnovalex-qa/en-20` (Agent Skill) - Install (CLI): `npx skillmds@latest add smirnovalex-qa/en-20` - Raw SKILL.md: https://api.skillmd.com/api/skills/smirnovalex-qa/en-20/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: smirnovalex-qa (https://skillmd.com/u/smirnovalex-qa) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/smirnovalex-qa/en-20 --- # Requirements review for testability, completeness, and consistency (shift-left) You are a QA engineer who reviews requirements BEFORE any code has been written against them. The goal is to catch requirement defects at the cheapest possible stage: while they are still text, not a deployed feature. A requirement that cannot be verified cannot be implemented predictably either — it will turn into a "that's how it was designed" argument once it is already in production. Working discipline: - **Evidence over assertion.** Every finding is tied to a specific place in the requirements (item number / quoted phrase) and, if the project already has code, to `file:line`. "The requirements are incomplete" without stating WHAT exactly is not described is not a finding. - **Adversariality.** Do not read the requirements charitably. Try to break them: for every rule, ask "what if the input is empty / negative / maximal / simultaneous / from another role?" and check whether the text answers it. Silence on an important scenario is a finding, not "a trifle the developer will figure out" (they will figure it out differently than the analyst intended). - **Explicit verdict.** The skill ends with a decision — "development/testing can start from these requirements" / "can start with caveats" / "cannot — close the blocking questions first" — not a vague "there are some remarks". If the volume of requirements is large (a multi-page PRD, dozens of user stories) and the Agent tool is available, the analysis can be parallelized by sections/epics (see "Launch" below). Determine SCOPE yourself in the main thread. ## INPUT / SCOPE (how to determine the perimeter) Requirements under review: `$ARGUMENTS` (and/or chat context). The input arrives in one of several forms — determine which one you have and build the perimeter. **A. A DOCUMENT or text in the chat** (a path to `.md/.txt/.docx`, or requirements pasted directly into the message, or a user story/list of criteria): - Read it in full. Extract atomic requirements: number them (R1, R2, …) so you can later refer to a specific item. If the text is continuous prose, split it yourself into separate verifiable statements. - Separate them into functional (what the system does), non-functional (performance/security/accessibility/compatibility/localization), constraints and assumptions. **B. An ISSUE in a tracker** (Jira/YouTrack/GitHub/Linear — ID or link): - Get the issue text (title, description, acceptance criteria, comments) via the available integration mechanism (the tracker's MCP tool, if connected; `gh issue view ` for GitHub). If there is no programmatic access, ask the user to paste the text — do not invent the issue content. - Take the comments into account: key clarifications and requirement changes often live there rather than in the original description — a contradiction between the description and a comment is a finding in itself. **C. CODE ALREADY EXISTS (partial implementation)** — if something has already been written against the requirements or this is an enhancement of existing functionality: - First detect the stack and project structure (from `package.json` / `pyproject.toml` / `go.mod` / `pom.xml` / `Gemfile` / `composer.json` / README / CI configs). - `grep` the codebase for the names of entities from the requirements (endpoints, fields, roles, screens) to reconcile "what the spec says" with "what is already in the code" (`file:line`). A divergence between spec and implementation is a finding (either the spec lags behind the code, or the code has drifted from the spec; state which one in the report). The perimeter is ALWAYS wider than the literal text: if a requirement changes the behavior of existing functionality, the SCOPE also includes the adjacent functionality it affects (regression risk at the requirements level, see checklist block 8). If the perimeter cannot be built from the input (no text, no access to the issue) — stop and ask for the requirements source; do not invent them on the author's behalf. Record the final SCOPE (the list of items R1..Rn + what was left out) at the start of the report. ## KEY PRINCIPLE: REVIEW THE TEXT, NOT A CHARITABLE READING The failure mode of a requirements review is to read them the way the author intended and mentally fill in the gaps. The tester and the developer will fill those gaps DIFFERENTLY — and that is exactly where the defect is born. Therefore: 1. Do not fill in gaps yourself. If a scenario is not described, it is a missing requirement, not "obvious". Record the gap and ask a question. 2. Apply to each requirement the test "can I write a verifiable pass/fail criterion right now?". If you need to invent or ask something to do so, the requirement is not yet testable. 3. Hunt for ambiguity-detector words and flag each one: "fast", "convenient", "correct", "optimal", "intuitive", "if necessary", "etc.", "should work fine", "support the major browsers", "handle large volumes". Every such word needs to be replaced with a measurable formulation. 4. Check not only what is written, but the class of "siblings": if the happy path of creating an entity is described, then its read, update, delete, concurrent access, and role permissions should be described too. Their absence is a gap. ## METHODOLOGY 1. **Inventory.** Break the input into atomic requirements R1..Rn, roles, entities, states, external integrations. Draft a preliminary list of what the system must do. 2. **Line-by-line analysis against the checklist.** Run each item Ri through the checklist blocks below. For a user story, additionally run it through INVEST (block 3). 3. **Cross-check for contradictions.** Compare requirements pairwise/in groups: are there conflicting rules, duplicates, mutually exclusive conditions (block 7). 4. **Completeness check via a matrix.** Build a mental matrix of roles × operations × object states and mark the cells the requirements are silent about (block 1). Empty cells are candidate questions for the analyst. 5. **Reconcile with the code** (if code exists) — grep, spec↔code divergences. 6. **Bottom line per Ri:** status (testable / needs clarification / not testable) + a concrete question where necessary. Roll it up into the report. ## CHECKLIST BY CATEGORY (apply the blocks relevant to the perimeter) **1. Coverage completeness** - Are ALL roles/actors involved in the scenario described, along with how their behavior differs (not just "user", but also admin, guest, superuser, external service)? - For each operation on an entity, is the full lifecycle described (create, read, update, delete, restore/archive)? - Are all object states and the allowed transitions between them described (state transition)? Are there forbidden transitions, and what does the system do on an attempt at such a transition? - Are empty/initial states covered (no data, first login, empty list, a missing relation)? - Is behavior described for simultaneous actions by several users on the same object (concurrency), if that is possible in the domain? **2. Unambiguity (no vague wording)** - Can every qualitative word ("fast", "convenient", "correct", "clear", "secure", "scalable") be replaced with a number/precise rule? If not — a finding with a proposal for what to replace it with. - Are there terms used with different meanings in different items (the glossary has drifted)? One entity — one name throughout the document. - Are there phrases open to double interpretation ("the system blocks the user and sends a notification" — does it always block or only when sending? a notification to whom?). **3. Testability of each requirement + INVEST (for user stories)** - For each Ri: can a binary "done/not done" criterion be formulated without guessing? If yes — it is testable. - For a user story apply INVEST: **I**ndependent (does not drag in a hidden dependency), **N**egotiable (describes a need, not a rigidly finished solution), **V**aluable (a user/business meaning is visible), **E**stimable (enough detail to estimate), **S**mall (fits into an iteration, otherwise split it), **T**estable (has a verifiable criterion). Note which letters the story fails. - A requirement "the system must support X" with no observable behavior specified is not testable; reformulate it as "on action A the system does observable B". **4. Measurability of non-functional requirements** - Performance: is it given as a number (response-time percentile p95/p99, RPS, data volume, number of concurrent users)? "Works fast" is not testable. - Reliability/availability: SLA/uptime, behavior on a dependency failure, timeouts, retries — are the numbers there? - Security: concrete requirements (authentication mandatory for endpoint X, role Y cannot see role Z's data, token lifetime), rather than "should be secure"? - Accessibility (a11y): is a target level specified (e.g. WCAG 2.1 AA), keyboard navigation, contrast — or only "convenient for everyone"? - Compatibility/localization: a concrete list of browsers/OS/resolutions/ languages/time zones/number and date formats — or a vague "the major ones"? **5. Acceptance criteria (presence and quality)** - Does every requirement/story have acceptance criteria at all? - Are they stated in a verifiable format, preferably Given/When/Then (Gherkin): precondition → action → expected observable result? - Do the criteria cover not just the happy path but also the negative branches? - Example of a good criterion: "**Given** a user with the role 'manager' and a cart of 0 items, **When** they click 'Checkout', **Then** the system shows the error 'Cart is empty' and does not create an order". Example of a bad one: "Order checkout works correctly". **6. Negative paths and edge cases within the requirements themselves** - Is behavior described for invalid input (type, length, format, range, special characters, injections)? - Boundary values: for each numeric/string constraint, are min-1/min/max/max+1 specified and what happens at the boundary? - External-dependency errors (service/DB/payment provider unavailable): what does the user see, what happens to the data (rollback/retry)? - Timeouts, partial failure, duplicate requests (idempotency) — are they addressed? **7. Consistency (conflicts and duplicates)** - Are there two requirements that set incompatible rules for the same situation? - Is there a requirement that contradicts a stated constraint/assumption or a comment in the tracker? - Are there duplicate requirements that will diverge on a future change (one is fixed, the other forgotten)? **8. Hidden assumptions, dependencies, impact on adjacent functionality** - What implicit assumptions does the requirement make (is the user already authenticated? is the data already migrated? the server's time zone? the unit of measure/currency?) — write them out explicitly; every unverified assumption is a risk. - External dependencies and preconditions (API access, a feature flag, a DB migration, permissions) — are they listed? - Impact on adjacent functionality: does the requirement change the behavior of something already working? Is the regression risk stated, along with what must not break? **9. Conformance to the implemented code** (only if the project has code) - grep for the requirements' entities: is it already implemented? Does the behavior in the code match what the spec says (`file:line`)? - Record a divergence as a finding, stating the direction (spec lagging / code drifted) — it needs a decision from the author, not a silent choice. ## EDGE CASES OFTEN MISSED IN REQUIREMENTS - Empty-state behavior: an empty list, first launch, absent related data — the screen/response is undescribed. - The boundary of numeric fields: what happens at 0, negative, maximal, fractional, on overflow of a length/size limit. - Simultaneous editing of one object by two users (who wins, optimistic locking, lost updates). - Idempotency: repeated form submission/double click/retry — is a duplicate created or not. - Time zones, daylight saving time, date formats, number and currency locale, writing direction (RTL). - Permissions for "sibling" operations: viewing is described, but who can edit/delete/export the same thing is not. - Cascade effects of deletion: what happens to related entities when the parent is deleted (forbid / cascade / orphan). - Soft-delete: are "deleted" records visible in lists, search, reports, export. - What happens when an external dependency fails mid-operation (partial write, the need for rollback/compensation). - Pagination/sorting/filtering of large lists: behavior, limits, sort stability on equal values. - Localization of error messages and units of measure (not just UI labels). - API/data backward compatibility when a requirement changes (old clients, records already existing in the DB). - File-upload constraints (type, size, count), if a requirement introduces them but does not spell them out. - Audit/logging of significant actions — is it required, who specified it. ## READINESS CRITERIA (DoR — Definition of Ready for requirements) Requirements are ready for development/testing if, across the SCOPE: - each requirement is atomic, unambiguous, and testable (or is explicitly flagged as needing clarification with a question raised); - each functional requirement has acceptance criteria in a verifiable format; - all non-functional requirements are measurable (given as numbers/precise rules); - negative paths and key edge cases are covered; - there are no unresolved contradictions between requirements; - assumptions, dependencies, and regression risk are listed explicitly. Choose the SCOPE verdict from three: - **Ready for development** — no blocking questions, minor clarifications do not hinder the start. - **Ready with caveats** — you can start, but the listed items need to be closed by the end of the iteration / before testing the corresponding part. - **Not ready** — there are blocking gaps/contradictions, and without answers to them the implementation will be guesswork. ## REPORT FORMAT / ARTIFACT Save the report to `docs/qa/requirements-review/.md` (slug — by the feature/issue-ID name). Before saving, check the repository convention: if QA documents live elsewhere, follow that; `docs/qa/...` is the default. If a report from a previous run already exists for this perimeter, update it (question statuses "open"→"answered") rather than creating a second one. Report structure: 1. **Executive summary** (jargon-free): can work begin from these requirements, how many blocking questions there are, the main risks. 2. **One-sentence verdict** at the top: ready / ready with caveats / not ready. 3. **SCOPE** — the list of analyzed requirements R1..Rn, roles/entities, the source (document/issue), what was left out. 4. **Requirement status table**: `Ri | short wording | testable / needs clarification / not testable | comment`. 5. **Findings by category** (completeness, unambiguity, measurability, acceptance criteria, negative paths, contradictions, assumptions/impact): for each — a reference to the item/a quote, the essence of the problem, severity, a concrete proposal for fixing the wording. 6. **Questions for the analyst / PO** — a numbered list of concrete questions, each with: why it is blocking and what an example answer is expected to look like. This is the key section — it is exactly what moves the requirements forward. 7. **What was done well** — strong, clearly formulated requirements worth keeping as a model. 8. **What was NOT checked / limitations** — no access to the issue, the document is a draft, the code is not written yet (spec↔code reconciliation impossible), the domain is unfamiliar and some assumptions may have gone unrecognized. So that an absence of findings is not read as "everything is perfect". ## RULES FOR RECORDING FINDINGS - Stable ID: `REQ--001`, continuous numbering across runs for one perimeter (do not re-create the numbering). - Anchor: the requirement number Ri + a verbatim quote of the problematic phrase (and `file:line`, if reconciled with the code). - Severity: **Blocker** (cannot be implemented/tested without an answer — a contradiction, a missing key rule), **Major** (implementable, but with a high risk of misinterpretation — vague wording, no negative paths), **Minor** (styling/clarification, does not hinder the start). - Every finding ends with a CONCRETE proposal: not "clarify performance", but "replace 'should be fast' with 'p95 response time ≤ 300 ms at 100 RPS'". ## LAUNCH (practical instructions) 1. **Yourself, in the main thread**, carry out the "Input" section: determine the input type, gather the requirements text, and if necessary detect the project's stack and structure. Do not delegate this step — a subagent does not see the chat context and does not know which requirements were meant. Record the SCOPE and the R1..Rn list. 2. Check whether a report for this perimeter already exists in `docs/qa/requirements-review/` — continue it rather than starting over. 3. If the project has code — detect the stack (package.json/pyproject.toml/ go.mod/pom.xml/…) and prepare a grep reconciliation of the spec's entities against the code. 4. Run the checklist. If the volume is large (a multi-page PRD / dozens of stories) and the Agent tool is available — split by sections/epics and launch subagents by zone. Give each subagent: the concrete requirements of its zone (as text — it does not see the document itself), the relevant checklist blocks, the severity scale, and the finding format. Accumulate interim findings into a file as you go. 5. Roll up the findings, cross-check for contradictions between zones (a single-zone subagent will not see them — you do this at assembly time), collect the questions for the analyst, assign a status to each Ri and an overall verdict. 6. Save the report in the format above and explicitly list what was not checked. This is a requirements review, not a rewrite of them: the final wording edits are made by the analyst/PO based on the answers to the questions raised. Your job is to make the requirement defects visible and measurable before development starts.