| name | requirements-engineering |
| description | Interactively elicit, capture, and maintain software/system requirements as a living, traceable repository. Use whenever the user wants to gather, write, refine, or organize requirements — including producing or updating an SRS (software/system requirements specification), writing ADRs / architecture decision records, building a requirements traceability graph (DAG), or keeping a decision ledger. Trigger proactively when the working folder already holds requirements artifacts (a `requirements/` folder of YAML, `decisions/` ADRs, an `srs.md`, or `ledger.md`), or when the user shares documents that are clearly specs, RFCs, or feature briefs and wants them structured. Also use for phrases like "let's spec this out", "interview me about what we're building", "capture these requirements", "write a decision record", or "turn these notes into a spec". Not for project management, code review, application code, dependency manifests like requirements.txt, or hardware "system requirements" (RAM/CPU). |
Requirements Engineering
This skill turns the messy, iterative work of figuring out what to build into a
durable, queryable artifact set. The goal is a living requirements repository:
every requirement is atomic, uniquely identified, verifiable, and traceable to the
need it came from and the decisions that shaped it. Nothing is captured as prose
that should be captured as structure.
The work is fundamentally iterative and conversational. You are not filling in
a form once. You interview the human in focused batches, write artifacts as you go,
and resume from wherever the repository currently stands the next time. Treat the
repository — not the chat — as the source of truth.
The artifact set
Everything lives in a requirements/ working tree (create it in the user's folder
if it doesn't exist; adapt to an existing layout if one is already there):
requirements/
├── srs.md # Human-readable spec, generated/maintained from the YAML. 29148 structure.
├── reqs/ # One YAML file per requirement, named <ID>.yaml. The source of truth.
│ ├── STK-001.yaml
│ ├── SYS-001.yaml
│ └── SW-FUN-001.yaml
├── decisions/ # ADRs in MADR format, named NNNN-kebab-title.md
│ └── 0001-use-postgres.md
├── ledger.md # Append-only audit log of every material change.
└── traceability.mmd # Generated Mermaid DAG of the derivation/dependency graph.
Why this shape: the YAML in reqs/ is structured so the graph and the SRS can both
be generated and validated rather than hand-maintained and drifting. The ledger
gives an audit trail standards bodies and reviewers expect. The ADRs capture the
why behind choices that requirements alone don't explain.
Workflow
Step 0 — Orient before asking anything
Look at the working folder first. Read scripts/validate_requirements.py's output
or just list the tree. Determine which situation you're in:
- Greenfield — no artifacts yet. You'll establish scope, then interview from the
top of the graph (stakeholder needs) downward.
- Existing repository —
requirements/ already has content. Load it, run the
validator to see open gaps and conflicts, and resume. Summarize the current state
back to the user ("You have 23 requirements; 4 are unverifiable, 2 have no parent,
1 dependency cycle") before asking what they want to work on.
- Source documents to ingest — the user dropped in a spec, RFC, brief, or notes.
Read them, extract candidate requirements into the schema, flag what's ambiguous
or missing, then interview to fill the gaps. Don't silently invent details.
Tell the user which situation you detected and what you propose to do next. Then go.
Step 1 — Interview in focused batches
This is the core skill. Read references/interview-playbook.md for the question
banks organized by area (scope & goals, stakeholders, functional capabilities, data,
interfaces & integrations, quality attributes, constraints, assumptions, acceptance,
risks).
How to run it:
- Ask 2–4 related questions at a time from one area, so the human can hold the
context and answer well. A wall of 30 questions gets shallow answers.
- Be adaptive: when an answer is clear, move on; when an answer reveals ambiguity,
risk, or a hidden assumption, drill into that one thread before broadening again.
Following the interesting thread is where real requirements get found.
- Reflect answers back as draft requirement statements ("So: The system shall
notify the assigned technician within 5 minutes of a job being created. Is the
5-minute bound real, or a placeholder?"). This surfaces vagueness immediately and
is how you turn opinions into verifiable requirements.
- Capture decisions and their rationale as they come up — if the human chooses
between real alternatives for an architecturally significant reason, that's an ADR
(see Step 4), not just a requirement.
Don't interrogate endlessly. After each batch, write the artifacts (Step 2),
then continue. The human should see the repository growing, not just answer questions
into a void.
Step 2 — Write requirements as structured YAML
Each requirement is one file in reqs/. Read references/requirement-schema.md for
the full field reference and assets/requirement.schema.json for the validated
schema. The essentials:
id: SW-FUN-001
title: Notify technician on job creation
type: functional
statement: >-
The system shall notify the assigned technician within 5 minutes of a job
being created.
rationale: Technicians miss SLA windows when notifications are delayed.
priority: must
status: proposed
source: Interview 2026-06-18, ops lead
derived_from: [SYS-004]
depends_on: []
verification:
method: test
criterion: >-
Create a job; assert a notification is delivered to the assignee in <5 min.
decisions: []
tags: [notifications, sla]
The rules that make requirements good (and that the validator enforces):
- Atomic — one testable obligation per requirement. "The system shall do X and Y"
is two requirements. Splitting is what makes traceability and verification possible.
- Verifiable — if you can't state how you'd confirm it's met, it's a goal, not a
requirement. Every functional and nonfunctional requirement needs a
verification
block. "Fast", "user-friendly", "robust" must become measurable fit criteria.
- Uniquely identified — IDs never change once assigned and never get reused, even
after deprecation. Other artifacts and the ledger point at them.
- Traceable —
derived_from links a requirement to the higher-level need it
satisfies. This is what builds the DAG and lets you answer "why does this exist?"
and "what breaks if we drop this?"
Step 3 — Maintain the traceability DAG
The graph is implicit in the derived_from and depends_on links — you don't draw
it by hand. After writing or changing requirements, run the validator:
python scripts/validate_requirements.py requirements/reqs --mermaid requirements/traceability.mmd
It checks ID uniqueness and format, flags dangling links, detects cycles (the
graph must stay acyclic — a requirement can't ultimately derive from itself),
warns about orphans (non-stakeholder requirements with no parent) and unverifiable
requirements, and regenerates the Mermaid graph. Surface its findings to the user;
don't just run it silently. A clean validation run is a quality gate before you
consider an area "done".
Step 4 — Record decisions as ADRs
When the human makes an architecturally significant choice — one that's costly to
reverse, constrains future work, or picks among real alternatives for a real reason —
capture it as an ADR in decisions/, numbered sequentially. Use the MADR 4.0.0
format in references/adr-format.md (template in assets/adr-template.md). Link the
ADR from the requirements it affects via their decisions field, and link back from
the ADR to those requirement IDs. The ADR explains the why that the requirement
statement deliberately leaves out.
Step 5 — Append to the ledger
Every material change — new requirement, status change, deprecation, accepted ADR —
gets one line appended to ledger.md (never edit or delete past entries; that's the
point of a ledger):
| 2026-06-18 | added | SW-FUN-001 | New: notify technician on job creation | Interview w/ ops lead |
| 2026-06-18 | accepted | ADR-0001 | Chose PostgreSQL over DynamoDB | See decisions/0001 |
Step 6 — Generate / refresh the SRS
The srs.md is the readable rollup, organized per ISO/IEC/IEEE 29148 (Introduction →
Overall Description → Specific Requirements → Verification). It's generated from the
YAML, not authored independently, so it never drifts. Read
references/srs-structure.md for the section guide and assets/srs-template.md for
the skeleton. Regenerate it when the user wants a document to share, or at the end of
a working session.
Step 7 — Close the session
End by summarizing what changed, what the validator says, and the open threads worth
picking up next time (unanswered questions, unverifiable requirements, areas not yet
covered). Because the repository is the source of truth, the next session — yours or
a colleague's — can resume cleanly from Step 0.
A note on judgment
Standards give you structure, not substance. The value you add is pushing vague
wishes into atomic, verifiable, traceable statements and noticing what the human
hasn't said — the unstated assumption, the missing error case, the quality
attribute nobody mentioned, the requirement with no way to test it. Be the diligent
interviewer who keeps asking "how would we know this is met?" without becoming a
bureaucrat who buries a small project in ceremony. Scale the rigor to the project.
�������������������������������������������������������������������������������������������������������������
