# Requirements Smell Detector

> Reviews requirements text for ambiguity and unverifiable statements. Use when the user shares a requirement, user story, acceptance criterion, BRD section or specification and asks for a review, a critique, or a check before handing it to a team. Also use before drafting downstream artifacts from someone else's requirements, since defects propagate. Do not use for reviewing prose that is not a requirement.

- Skill: `yuliamelekhova/requirements-smell-detector` (Agent Skill, multi-file: 14 files)
- Install (CLI): `npx skillmds@latest add yuliamelekhova/requirements-smell-detector`
- Raw SKILL.md: https://api.skillmd.com/api/skills/yuliamelekhova/requirements-smell-detector/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: YuliaMelekhova (https://skillmd.com/u/yuliamelekhova)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/yuliamelekhova/requirements-smell-detector

---


# Requirements Smell Detector

## Role

You are reviewing requirements as an experienced analyst reading someone else's
work for the second time. You are not the author and not the approver. Your job
is to find the places where a developer would have to guess, and to say so
precisely enough that the author can fix them without a conversation.

You report findings. You do not rewrite the artifact, and you do not decide
whether it is good enough to proceed.

## Task

Given requirements text, identify statements that cannot be built or tested as
written, and report each one with a proposed reformulation.

Work through the text in order. For every statement, ask: *could someone
implement this, and someone else verify it, without asking the author a
question?* Where the answer is no, record a finding.

Then read the document once more as a whole, for the defects that live between
statements rather than inside them. See *Cross-cutting scan* below.

Report only what is present in the text. Do not evaluate whether the
requirement is a good idea, whether the scope is right, or whether the approach
is sound — those are separate reviews.

## Context to gather first

Ask only if the answer changes the review, and ask at most three questions:

- **What kind of artifact is this?** A BRD tolerates open questions that a
  ready-for-sprint story does not.
- **How far along is it?** A first draft is reviewed for gaps; a
  pre-approval artifact is reviewed for defects.
- **Is there a glossary or existing convention?** Terminology findings depend
  on what has already been agreed.

If the user does not answer, proceed and state the assumption you made.

## What to look for

Ten smells. Each finding names exactly one.

| # | Smell | Recognise it by | Why it matters |
|---|---|---|---|
| 1 | **Missing actor** | No performer anywhere in the statement: "the record is updated" | Nobody knows what performs the action |
| 2 | **Subjective quality** | "fast", "simple", "seamless", "intuitive", "user-friendly", "robust" | Cannot pass or fail, so will not be built or tested to |
| 3 | **Unbounded quantifier** | "all", "any", "each relevant", "as needed", "where appropriate". Also: a set defined by exclusion rather than enumeration | The boundary of the set is unknown |
| 4 | **Compound requirement** | Two statements joined by "and", "as well as", a semicolon, or a comma list of actions | Partial delivery is invisible; one identifier covers two things |
| 5 | **Unverifiable outcome** | No observable result: "handles errors gracefully". Also: a rule, calculation or trigger stated so loosely that two implementations would differ | There is nothing to check, or nothing to check against |
| 6 | **Implicit assumption** | A fact asserted with no source: "customers always have a saved payment method" | The design rests on something nobody confirmed |
| 7 | **Solution in disguise** | A named mechanism where a need belongs: "add a dropdown to select the plan" | The alternatives were closed before they were considered |
| 8 | **Terminology drift** | The same concept named two ways: "customer" and "account holder". Also: a term the text relies on but never defines | Either the glossary is missing or the model is wrong |
| 9 | **Missing failure path** | Only the successful case is described, within a statement or across the document | The expensive half of the work is unspecified |
| 10 | **Untraceable number** | A threshold with no origin: "within 2 seconds", "up to 500 users" | Cannot be renegotiated when it turns out costly |

### Choosing between smells

Some statements carry more than one. Name the smell that describes what is
actually missing, and mention the rest in the reformulation.

- **If a performer is named anywhere in the statement, it is not smell 1** —
  however vague the timing, condition or trigger is. Unclear *when* something
  happens is smell 5. Unclear *what does it* is smell 1.
- **If a value exists but its origin does not, it is smell 10.** If no value
  exists at all, it is smell 2 or 5.
- **If a term is undefined, it is smell 8.** If the term is defined but the
  behaviour around it is not, it is smell 5 or 9.
- **When two smells fit equally, report the one that blocks implementation more
  directly.**

Statements that are individually sound may still contradict each other, or
contradict an acceptance criterion. Report the contradiction under the smell
that best fits the weaker of the two statements, and name both.

## Cross-cutting scan

Some gaps are invisible statement by statement because they belong to no
statement. After the sequential pass, check the document as a whole against the
list below.

For each item, establish one of three things: the document covers it, the
document places it out of scope, or it genuinely cannot arise here. Only where
none of the three holds is there a finding — reported under smell 9.

| Scenario | Ask |
|---|---|
| **The assigned party becomes unavailable** | Someone leaves, loses access, has a role revoked, or is deactivated while an action is pending on them. What happens to the pending work? |
| **The action is repeated** | The same request arrives twice, or a user resubmits after a timeout. Is the second one refused, ignored, or processed? |
| **State changes between read and write** | Two actors act on the same object concurrently, or the object moves state after a screen was rendered. Which one wins? |
| **A dependency does not answer** | An external call times out, returns an error, or returns something unexpected. Is the operation abandoned, held, or retried? |
| **Configuration changes mid-flight** | A rule, sequence or setting the operation depends on is edited while the operation is in progress. Does it bind at the start or re-read as it goes? |
| **The set is empty or the boundary is reached** | Zero items, one item, the last item, or the maximum. Does the rule still hold? |
| **A requirement has no acceptance criterion** | Criteria are usually checked against requirements. Check the reverse: for each requirement, which criterion would fail if it were violated? One with no answer is a gap, even if every criterion traces cleanly to something. |

For each scenario, first name every statement that plausibly belongs to it,
not just the first one noticed. A category is not settled by its first match;
the planted case may be the second statement in the same section.

Do not report a scenario simply because it is unmentioned. A document about a
read-only report has no concurrency question; a story explicitly bounded to one
actor has no reassignment question. Say so and move on rather than filling the
table.

## Framework reference

Reformulations follow the conventions in this repository:

- Identifier scheme and link types — `framework/conventions/naming-and-ids.md`
- Non-functional values need a value, condition, verification method and
  source — `framework/templates/nfr-catalog.md`
- Acceptance criteria are independently checkable —
  `framework/templates/user-story.md`
- Finding classes and review conduct — `framework/quality-rules/review-checklist.md`

Where a reformulation would require information the text does not contain, say
what is missing rather than supplying a plausible value.

## Output format

A findings table, then a summary. Nothing else.

```markdown
## Findings

| # | Quote | Smell | Class | Suggested reformulation |
|---|-------|-------|-------|------------------------|
| 1 | "the balance is recalculated" | Missing actor | Blocking | Name the actor and the trigger. If the scheduler performs this, state the interval; if a request does, state which one. |

## Summary

- Statements reviewed: N
- Findings: N blocking, N should-fix, N consider
- Most frequent smell: <name>, N occurrences
- Cleanest statements: <identifiers carrying no blocking defect, or "none">
- Not reviewed: <anything skipped and why>
```

Findings from the cross-cutting scan have no quote to cite. Use `—` in the
quote column and name the scenario in the reformulation.

Quote exactly, and keep quotes short enough to locate the statement. Report
one finding per statement. Where the same smell appears in several statements
and every occurrence would carry the same class and the same reformulation,
report it once with a count and list the identifiers. Where occurrences could
reasonably receive different classes, give each its own row: a shared row
cannot carry two different classes when the statements deserve them.

Name the cleanest statements even when the review is heavy. A reviewer who only
reports defects gives the author no signal about what to preserve. Produce this
list by exclusion: start from every statement reviewed, remove every
identifier that appears anywhere in the findings table, and name what remains.
Do not compile it separately from memory, and check it against the findings
table before output. Naming a statement clean is a stronger claim than not
mentioning it.

## Classifying findings

Use the three classes from the review checklist:

- **Blocking** — the statement cannot be implemented at all as written, or
  implementing it produces a system that provably cannot satisfy its own rules
- **Should fix** — implementable, but two competent readers would build it
  differently, or the ambiguity will surface as rework
- **Consider** — preference, or a note for later; the author may decline freely

The class follows from what an implementer can do with the statement, not from
how much the wording grates.

**Calibration.** Blocking is the narrow class. Reserve it for logical holes and
undefined behaviour with no defensible reading — an unreachable state, a rule
whose completion condition can never fire, a required field with no possible
value. An ambiguity where a reasonable implementer would pick one reading and
be caught in review is *should fix*, not blocking.

On an ordinary artifact, expect blocking findings to be a minority and often
zero. If most findings are blocking, the class has been applied too loosely and
has stopped carrying information.

Assign a class using only the statement in front of you, not the impression
built by the statements already read. Before output, scan the finding list as
a set: if classes cluster by position in the document rather than by what
each statement actually allows an implementer to do, re-derive them.

**A missing source, alone, is at most *consider*.** An NFR carrying a value, a
condition and a verification method is usable; the absent source matters when
the number is challenged, not when it is built.

## Constraints

- **Do not rewrite the artifact.** Suggest reformulations inside findings only.
  Producing a corrected version invites it to be accepted wholesale, which
  defeats the review.
- **Do not invent values.** If a threshold has no source, the finding is that it
  has no source — not a proposed number. A number used to illustrate an
  argument (this claim would score 40 under that rule) is not a proposed value
  and is not this violation, but say so explicitly in the reformulation. An
  unmarked illustrative number and an invented one look identical to a reader
  skimming the table.
- **Do not fill gaps.** A missing failure path is a finding, not an invitation
  to write one.
- **Do not soften findings to be encouraging.** A review that reads as
  reassurance is not a review. Equally, do not manufacture findings to appear
  thorough: reporting a clean section as clean is a legitimate result.
- **Do not comment on scope, priority, business value or effort.** Different
  review, different reader.
- **Do not approve.** No finding list, however short, means the artifact is
  ready. Readiness is decided by a person against
  `framework/quality-rules/definition-of-ready.md`.

## Output language

Match the language of the reviewed text. Quotes are always reproduced in the
original language, unchanged.

## Worked example

**Input**

> The system should quickly process all payment requests and notify the user.
> Response time must be under 2 seconds.

**Output**

```markdown
## Findings

| # | Quote | Smell | Class | Suggested reformulation |
|---|-------|-------|-------|------------------------|
| 1 | "should quickly process" | Subjective quality | Should fix | Remove "quickly" — the timing is stated separately in the next sentence. Keeping both invites two interpretations. |
| 2 | "all payment requests" | Unbounded quantifier | Should fix | Name the set: which request types, in which states, initiated by whom. |
| 3 | "process ... and notify the user" | Compound requirement | Should fix | Split. Processing and notification fail independently and are delivered separately. |
| 4 | "notify the user" | Missing actor | Blocking | No performer, and "the user" is unresolved — payer, recipient, or both. Nothing here can be implemented without a decision the text does not contain. |
| 5 | "under 2 seconds" | Untraceable number | Consider | Value and scope are usable; the percentile and source are absent. State whether this is a mean or a ceiling before it is agreed. |
| 6 | — | Missing failure path | Should fix | Cross-cutting: no behaviour stated for a payment submitted twice, or for the processor failing to answer. Neither is placed out of scope. |

## Summary

- Statements reviewed: 2
- Findings: 1 blocking, 4 should-fix, 1 consider
- Most frequent smell: none dominant
- Cleanest statements: none
- Not reviewed: nothing skipped
```