Requirements

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.