Aor req

/aor-req — Requirements Authoring

Drafts UN, PR, and SR following EARS-12 patterns, INCOSE C1-C9 quality attributes, and canonical cross-reference syntax. Output is markdown.

Note on skills vs agents. The AOR bundle contains skills at .claude/skills/aor-*/SKILL.md (invocable directly, like this one) and SME agents at .claude/agents/aor-sme-*.md (sub-agent system prompts spawned only by aor-review / aor-review-adhoc). Do NOT invoke an agent as a skill — it will fail with "skill not found".

Operating discipline

Apply throughout. State each at startup so the user sees it.

• Mode (declared at startup): ask whether this is an exploratory session (single requirement, conversational, no files) or a document session (full specification authoring, files written). Default to exploratory if scope arrives as inline text without a file path, document otherwise. The mode controls whether Steps 5–7 write to disk.
• Invocation acknowledgement: the first response of the skill states "Running as aor-req in <mode> mode. Files written to <output path> unless you ask otherwise." Eliminates the "did the skill actually run?" ambiguity.
• Q&A discipline: ask one clarifying question at a time. Wait for the user's answer before asking the next. Do not stack questions. A single AskUserQuestion call presenting one decision with multiple alternatives (e.g., a multi-choice menu) is one question; presenting two unrelated decisions in one call is stacking.
• Failure-disclosure: if any prescribed step cannot be completed (file write blocked, sub-agent invocation failed, reference file unavailable, partial completion, timeout, permission denied), state it in chat. After disclosing, halt and ask whether to retry, fall back to disclosed manual emulation, or abort — do not continue silently. One retry is permitted for clearly transient failures (e.g., network timeout) before mandatory disclosure.

Workflow

Step 1: Establish scope

If the user passed scope text or a file path, use it. Otherwise, ask via AskUserQuestion: "What features or changes should be specified?"

Distinguishing scope text from a file path (REQ-B): treat the input as a path if any of (a) it contains / or \, (b) it ends in .md / .txt / .xlsx / .csv / .docx, or (c) it resolves to an existing file on disk via Read(). Otherwise treat it as scope text — including multi-word descriptions like "patient appointment booking system".

Tie-breaker: if only rule (c) matches (no / or \, no recognized extension, but Read() resolves) AND the input is a single word, confirm with the user before treating as path: "I see a file named <input> exists. Did you mean that file, or is that a scope description?"

For Excel-sourced inputs, expect the host LLM to have transcribed rows into a working markdown buffer before this skill runs (the bundle doesn't parse Excel directly).

Step 1a: Classify the level

If exploratory mode, ask:

"Is this a User Need (UN), Product Requirement (PR), or Software Requirement (SR)?"

Skip unused steps once the level is known: UN review needs Step 2; PR review needs Step 3 + Echo Gate; SR review needs Steps 4–6.

Multi-level input in exploratory mode: if the user provides a UN+PR+SR set (or any combination of multiple levels) instead of selecting one, treat as a multi-level review — walk Steps 2–4 across the provided levels in order, but keep exploratory file-write discipline (no automatic disk writes; surface findings inline).

If document mode, default to walking all three levels (UN → PR → SR) across Steps 2–4 unless the user specifies otherwise.

Step 2: Write User Needs (UN-NNN)

For each distinct stakeholder need, write one UN. Rules:

• Technology-agnostic, stakeholder-voiced
• Plain narrative (NOT EARS syntax)
• Include problem statement (2-3 sentences) + need statement
• Tag a persona via traces_to::UN->Persona [<persona-id>]
• Priority: Critical | High | Medium | Low

See templates.md for format.

Step 3: Write Product Requirements (PR-NNN)

For each UN, derive PRs:

• Technology-agnostic, measurable, objective
• EARS syntax (see ears-guide.md for the 12 patterns)
• Each PR traces backward: derived_from::PR->UN [UN-NNN]
• Each PR traces forward: traces_to::PR->SR [SR-NNN]
• Every happy-path PR must have at least one If/Then (Unwanted) PR companion
• The same If/Then companion rule applies at the SR level in Step 4 — every happy-path SR must have an If/Then SR companion specifying the implementation-level recovery
• Every EARS-N (negative/shall not) PR must have at least one positive companion PR (Ubiquitous, Event-Driven, or State-Driven) specifying the expected correct behaviour; the same rule applies at the SR level

"Happy-path" defined (REQ-E): a PR is happy-path if it uses one of the positive EARS patterns — Ubiquitous, Event-Driven, State-Driven, Optional, Complex, EARS-E, EARS-T, EARS-P. Excluded: Unwanted Behaviour, EARS-N (negative/shall not), EARS-F (failure-mode declarative).

Run Adversarial Error Decomposition for each UN:

1. How does it fail silently?
2. How does it fail noisily?
3. How does it fail under load?
4. How does it fail under malice?
5. How does it fail over time?

Each failure mode becomes either an EARS If/Then PR (tag with [ADV] in the heading; identifier stays canonical, e.g., PR-007 [ADV]) or a note for a separate risk register.

Worked example. UN: "preserve every uploaded file". Failure mode: "fails silently when disk free space is exhausted". Resulting PR:

### PR-007 [ADV]: Reject upload when disk pressure is high
If disk free space drops below 5%, then the system shall reject new uploads
with HTTP 507 Insufficient Storage and return a Retry-After header.
derived_from::PR->UN [UN-001]
traces_to::PR->SR [SR-014]

Note that the failure mode is concrete and quantified (5%, HTTP 507, Retry-After) — that's what makes the PR verifiable (C7).

Step 4: Write Software Requirements (SR-NNN)

For each PR, derive SRs:

• Implementation-specific: name services, APIs, databases, error codes
• EARS syntax with specific component names
• Each SR traces backward: derived_from::SR->PR [PR-NNN]
• Each SR traces forward: traces_to::SR->TC [TC-NNN]
• Use clause-level granularity (SR-NNN.c1, .c2) to consolidate related behaviours under a single SR ID
• Every happy-path SR must have at least one If/Then (Unwanted) SR companion (see Step 3 for the "happy-path" definition)
• Every EARS-N SR must have at least one positive companion SR

Step 5: Field Specification Tables

For features with data input/display, add field specification tables in the SR section:

Field ID	Name	Label	Type	Min	Max	Unit	Default	Required	UI Exposure	Validation Rule	Error Msg	Parent SR

UI Exposure values: editable | display-only | hidden.

Step 6: Echo Gate

For each SR clause, write a one-line testable assertion:

VERIFY: [SR-NNN.c1] — [restatement of the requirement as a testable assertion]

If you cannot write the assertion, the requirement is untestable — rewrite it.

Step 7: Completeness check

Run the checklist in completeness.md before declaring authoring done.

Large input handling

When input exceeds ~200 source items (e.g., a large Excel paste):

1. Split into batches of 50 rows.
2. For each batch: a. Read the batch. b. Transcribe to markdown UN/PR/SR per the steps above. c. Append to the working file (do not overwrite). d. Report progress: "Batch <N> of <M> complete; <K> requirements drafted."
3. After all batches, run the completeness check on the full file.

If a batch contains ambiguous input, pause and ask for clarification before continuing — do not skip rows silently.

Output paths

Default: ./requirements/SPECIFICATION.md for the consolidated UN/PR/SR. The user can override.

When updating an existing file, preserve existing IDs — append new ones with the next sequential number.

Cross-reference syntax (cheat sheet)

relation_type::SOURCE->TARGET [ID-list]

Type	Direction	Use
traces_to	forward	UN→PR, PR→SR, SR→TC, UN→Persona
derived_from	backward	PR→UN, SR→PR, TC→SR
validates	verification	TC→SR
mitigates	risk control	SR→RISK
conflicts_with	contradiction	any→any

Identifier format

Regex: ^(UN|PR|SR|TC)-\d{3}(\.[A-Z])?$

• Base IDs: UN-001, PR-001, SR-001
• Sub-IDs (EARS-P tabular): PR-010.A, PR-010.B
• Clause notation: SR-001.c1, SR-001.c2

Reference files

• ears-guide.md — the 12 EARS patterns
• templates.md — markdown templates for UN/PR/SR sections
• completeness.md — exit checklist (UN→PR→SR coverage)