---
name: requirements
description: Write, modify, or review a requirement file under docs/requirements -- pick the single owning file, keep the text contract-only, name IDs so they need no explanation, and verify cross-references and test coverage. Use when the user asks to add, change, audit, or review a requirement, or when the decision protocol calls for writing one.
---

# Write and maintain requirement files

`docs/requirements/CLAUDE.md` owns the format: the template, file naming,
status lifecycle, test-tag convention, and the list of what does not
belong. Read it first and follow it; this skill operationalizes it.

This skill adds the method. Every check below traces to a real cleanup
this directory needed: duplicated passages that drifted into apparent
contradiction, implementation detail displacing contract, confusable
names that needed paragraphs to disambiguate, glosses that did not match
their link, and acceptance criteria no test verified. Run the checks
whether writing a new requirement, editing an existing one, or auditing
the directory.

## 1. Read the ground rules

Read `docs/requirements/CLAUDE.md`. If the change involves reasoning or
a rejected alternative, read `docs/rationale/CLAUDE.md` too -- the *why*
goes there, linked from a `## Rationale` section, never inlined.

## 2. Find the owner before writing a word

Every behavior has exactly one owning requirement file. Before adding
any passage, find where it belongs:

- `ls docs/requirements/` and grep the directory for the key nouns of
  the behavior. Read every file that hits.
- An owner exists: extend it. No owner: create a new file.
- The new content is one instance of a contract other files also
  instantiate (another recognized toolchain, another output filter):
  extend the shared owner -- usually a table row -- instead of creating
  a per-instance file. A new file that would restate an existing
  contract with the names changed is a signal to merge, not to add.
- Two files each state half of one contract (one says "exits non-zero
  when X", another says "X never affects the exit code"): that is a
  latent contradiction. Pick or create one owner, state the full
  contract there organized around the principle that resolves the
  halves, and reduce the other files to one-line deferrals.

When another file needs to mention the behavior, it gets a one-line
pointer naming the owner ("owned by `output-duplicate-detection`"),
never a re-narration. If a re-narration can drift, it will.

## 3. Name the ID so it needs no explanation

- Take the prefix from the existing set (`ls docs/requirements/` shows
  them: `cli-`, `interception-`, `output-`, `recognition-`). Do not
  invent a new prefix for one file, and pick the prefix by what the
  content is about, not by which crate implements it.
- Place the new ID next to the most similar existing ID. If a reader
  needs prose to tell them apart, rename until the names alone carry
  the distinction. Disambiguation paragraphs are a naming bug.
- Renaming or merging an ID is one atomic change: update every
  `Requirements:` tag in tests (`grep -rn "Requirements:.*<old-id>"
  crates/ tests/`), every cross-reference in `docs/`, and re-run the
  coverage script.

## 4. Keep the body contract-only

`docs/requirements/CLAUDE.md` ends with the list of what does not
belong; this check is how to apply it. For every sentence ask: is this
what the user can expect (keep), why we chose it (rationale entry), or
how it is built (code comment)? Beyond that list, remove on sight:

- Rust API and type names standing in for behavior
  (`Path::canonicalize`, crate names, function names). State the
  observable behavior instead.
- Internal file names as actors in acceptance criteria (a YAML
  interpreter definition, a module path). The criterion is about
  observable output, not about which file produces it.
- Buffering or performance speculation dressed as a constraint.
- History: what the code used to do, fixed-bug narratives, references
  to unimplemented proposals, config keys that never shipped. A
  requirement states the present contract; git history remembers the
  past. (A regression-guard test scenario citing an issue number is
  fine -- that is contract, not history.)
- Contracts phrased as a diff against the past ("byte-identical to
  today's behavior", "same as before this feature"): state the behavior
  absolutely. And an Intent that describes the pre-fix bug in present
  tense becomes false the day the status turns `implemented`.
- Reproduced external specifications. Link them; do not copy them.

The boundary the no-literal-flags rule needs: it bans flags and config
keys of *Bear itself*; flags of *the compilers Bear classifies* (`-c`,
`--version`, `-showme`) are subject matter and do appear.

## 5. Verify every cross-reference, gloss included

A link is two claims: the target exists, and the gloss describes it.
Check both -- read the target and confirm the sentence around the link
matches what that file actually owns. A gloss describing env-derived
flags that links the wrapper-mode mechanism is worse than no link.

## 6. Record limitations and exclusions where they belong

- Accepted gaps go in the owner file's `## Known limitations` section
  (not in Notes, not in a neighboring file that happens to mention the
  feature); link the tracking issue when one exists.
- A deliberate exclusion likely to be proposed again (a name not
  recognized, a mode not supported) is part of the contract: record it
  in the owner with the reasoning that keeps it out, so the next reader
  does not re-litigate it.

## 7. Make the Testing section carry every criterion

Walk the acceptance criteria one by one; each must map to at least one
Given-When-Then scenario. A criterion with no scenario is either
untestable (rewrite the criterion) or a coverage hole (write the
scenario). Scenarios are canonical; tests implement them and cite the
requirement ID.

Status discipline: a new requirement starts at `proposed` and waits for
approval (see the decision protocol in the root `CLAUDE.md`); the full
lifecycle is the status table in `docs/requirements/CLAUDE.md`. Set
`implemented` only after step 8 passes.

## 8. Verify before finishing

```sh
# every implemented requirement has at least one tagged test
./scripts/check-requirements-coverage.sh

# cross-references resolve (review hits; backticked non-ID words
# sharing a prefix are false positives; keep the prefix list in
# sync with step 3)
grep -hoE '`(cli|interception|output|recognition)-[a-z0-9-]+(\.md)?`' \
    docs/requirements/*.md | tr -d '`' | sed 's/\.md$//' | sort -u | \
    while read -r id; do
      [ -f "docs/requirements/$id.md" ] || echo "dangling: $id"
    done
# IDs are written without the .md extension; a suffixed hit is itself
# a style fix even when the target exists

# implementation-leakage heuristics on the touched file (review hits)
grep -nE '::|\.(rs|yaml|yml)\b|\bcrate\b' docs/requirements/<file>.md
```

The leakage grep is a prompt, not a verdict: hits in Intent or
acceptance criteria almost always need fixing; a type deliberately
named as the source of truth for an interchange format, or test-file
locations in Testing and Notes, are legitimate and stay.

Then a final read of the touched file asking the step questions in
order: single owner (2), self-explaining name (3), contract-only (4),
verified references (5), limitations placed (6), every criterion
tested (7).

## Scope of a maintenance edit

When editing an existing file, apply the checks to the passages the
change touches. Fix genre violations you are already rewriting; note
violations elsewhere in the file and propose a separate cleanup rather
than growing the change. A deliberate directory-wide sweep is its own
task with its own commit series.