USDM Requirements Decomposition

Core Concepts

Requirement (REQ-NNN) — WHAT the stakeholder needs
├── Reason            — WHY this requirement exists
├── Description       — Context, scope, constraints
├── Requirement (REQ-NNN) — sub-requirement (recursive decomposition)
│   ├── Reason
│   ├── Description
│   ├── Requirement ...
│   └── Specification (SPEC-NNN)
└── Specification (SPEC-NNN) — HOW to verify, in measurable terms
    └── (nested SPEC allowed, max 2 levels)

• Requirement: A stakeholder need expressed from the user's perspective. A requirement MAY contain sub-requirements for recursive decomposition.
• Reason: The business value, regulation, or user benefit that justifies the requirement.
• Description: Contextual information, scope boundaries, and constraints.
• Specification: A verifiable, unambiguous behavior statement using "shall". Write in EARS format when applicable.

Input Sources

gh issue view <number>

get_task

get_tasks

Workflow

Step 1: Source Collection & Scope Confirmation

1. Collect all input material (user text, ticket content, attached documents).
2. Identify the system/product scope.
3. Confirm scope with the user before proceeding:
   • What is the system being specified?
   • What is in scope / out of scope?
   • Who are the stakeholders?

Step 2: Hidden Verb Discovery & Requirement Extraction

references/hidden-verb-discovery.md

1. Nominalization detection: Find nouns that hide verbs (e.g., "authentication" → authenticate).
2. Compound statement splitting: Split "and"/"or" into separate requirements.
3. Passive voice conversion: Recover the actor (who does what).
4. Adjective expansion: Convert vague adjectives ("secure", "fast") into measurable behaviors.
5. Exception discovery: For each happy-path requirement, identify error/edge cases.
6. Temporal verb discovery: Identify WHEN/WHILE triggers hidden in time expressions.

Step 3: USDM Hierarchy Construction

1. Write the Requirement as a stakeholder need (not a solution).
2. Write the Reason as a causal statement ("Because..." / "In order to...").
3. Write the Description with context, scope, and constraints.
4. Decompose into sub-requirements if the requirement is too broad or contains multiple distinct concerns. Apply the 4 decomposition criteria in order to systematically break down requirements:

   #	Criterion	Focus	Strategy
   1	Temporal	Verbs and process flow	Decompose along the time axis. Use this first to establish the happy-path sequence.
   2	Structural	UI elements, components, data entities	Capture variations and configurations outside the main flow.
   3	State-based	State transitions (idle, processing, error)	Cover error cases, edge cases, and constraint-driven behaviors.
   4	Common	Shared processing across requirements	Extract cross-cutting concerns into shared sub-requirements.

   Decomposition rules:
   • Each sub-requirement MUST have its own Reason, Description, and at least one Specification.
   • Use hierarchical IDs: REQ-001 → REQ-001-1, REQ-001-2, etc.
   • Stop decomposing when a requirement can be covered by a small set of directly testable specifications.
5. Write Specifications following these rules:
   • Use "shall" for mandatory, "may" for optional behavior.
   • One specification = one testable behavior.
   • Use EARS patterns (see

     ../ears/SKILL.md

     ) for specifications with triggers or conditions.
   • Avoid all words on the ambiguity blacklist (see

     references/usdm-writing-guide.md

     ).

Step 4: Verification

1. Traceability: Every SPEC traces to a REQ; every REQ traces to a source.
2. Completeness: No orphan requirements or specifications.
3. Consistency: No contradicting specifications.
4. Ambiguity check: No blacklisted words in specifications.
5. Verifiability: Every specification can be tested (test, inspection, analysis, or demonstration).
6. Granularity: Each specification states a single behavior.

Step 5: Output

Option A: Markdown Document (default)

1. Apply the template from

   templates/usdm-requirements.md

   .
2. Fill in all metadata fields (document ID, date, author, stakeholders).
3. Include ticket references if sourced from a ticket system.
4. Generate the traceability matrix.
5. List any open questions discovered during analysis.
6. Save the document with the naming convention:

   REQ-DOC-{YYYYMMDD}-{NNN}-{short-name}.md

Option B: GitHub Issues

references/github-issues-mapping.md

1. Create

   usdm:req

   and

   usdm:spec

   labels if they do not exist.
2. For each top-level REQ, create an Issue with label

   usdm:req

   .
3. For each sub-requirement, create a sub-issue under the parent REQ Issue with label

   usdm:req

   .
4. For each SPEC, create a sub-issue under its parent REQ Issue with label

   usdm:spec

   .
5. Verify the hierarchy with

   gh sub-issue list

   .

Writing Rules

ID Convention

Ambiguity Blacklist

references/usdm-writing-guide.md

appropriate, suitable, fast, slow, easy, simple, etc., some, several, as needed, user-friendly, flexible, support, handle, properly, correctly, reasonable, efficiently, should (in specs)

Anti-Patterns

References

• references/usdm-writing-guide.md

  — Naming conventions, quality criteria, review checklist

• references/hidden-verb-discovery.md

  — Techniques for uncovering hidden requirements

• references/github-issues-mapping.md

  — GitHub Issues USDM mapping and sub-issue workflow

• examples/usdm-example.md

  — Complete before/after transformation example

• templates/usdm-requirements.md

  — Output document template