requirements-engineering

name

requirements-engineering

description

Runs the requirements-engineering phase — the first SDLC step, upstream of design. Through a thorough, area-by-area interview it elicits and specifies the complete requirements for a new application, proactively enumerating the standard sub-requirements for each capability area (for authentication: sign-up, sign-in, verification, password reset, logout) plus all non-functional requirements. Produces a structured SRS (ISO/IEC/IEEE 29148 lineage) in markdown, a separate use-case document in markdown, and a requirements traceability matrix. Also amends a finalized SRS — adding, updating, or removing requirements with stable IDs. Use at the start of a project before architecture and UX, or when changing existing requirements. Trigger on "gather requirements", "write an SRS", "requirements engineering", "specify the requirements", "add a requirement", or "update the requirements". Saves progress incrementally so long sessions can resume.

Requirements Engineering

This skill produces the traditional, structured requirements specification that sits at the very front of the SDLC — upstream of architecture and UX. It is deliberately a detail phase: its job is to capture every requirement comprehensively, so that the documents it produces become the single source of truth the design and planning skills downstream consume.

Two principles define it:

1. Exhaustive enumeration, not transcription. When a capability area comes up, the skill does not merely record what the user mentions. It proactively proposes the full set of standard sub-requirements for that area and has the user confirm, extend, or remove them. "User authentication" is never one line — it expands into sign-up, sign-in, email verification, forgot password, reset password, change password, logout, session expiry, account lockout, rate limiting, and so on. The requirement-catalog.md reference is the engine for this. The same discipline applies to non-functional requirements.

2. Structured and traditional. The output is a formal SRS in the ISO/IEC/IEEE 29148 (IEEE 830) lineage — numbered, uniquely-identified, testable requirements — not an agile backlog. Whatever the SRS calls a unit (function / feature) is fine; epic and feature slicing is deliberately deferred to the downstream implementation-planning skill. This skill owns the problem space, comprehensively.

Because a full requirements interview is long, the skill checkpoints its work incrementally and can resume after an interruption — see Phase 0 and references/checkpointing.md.

Inputs

This is the first skill in the pipeline, so it has no upstream document to consume — it elicits from the user. If the user has an existing brief, notes, or partial requirements, ingest them first and treat them as raw input to confirm and expand, not as finished requirements.

Outputs

Three files (three logical documents), all markdown, written to docs/.

1. docs/srs.md — the comprehensive SRS (the source of truth downstream skills read). Vision & scope, user characteristics, constraints, assumptions, glossary, functional requirements, and non-functional requirements all live here as structured sections.
2. docs/use-cases.md — detailed textual use-case specifications plus a Mermaid use-case diagram (separate document, use-case-centric; no user stories).
3. docs/rtm.md — the Requirements Traceability Matrix (markdown table).

Word/PDF output is out of scope — markdown is the deliverable. Users who want a Word version can convert it themselves (e.g., with pandoc); this skill does not own that.

Plus working files that are not deliverables: docs/.requirements-progress.md (the progress tracker), and the incrementally-built srs.md / use-cases.md drafts themselves (which become deliverables 1 and 2 once finalized).

Workflow

Phase 0 — Mode detection (always first)

Before anything else, look for docs/.requirements-progress.md and docs/srs.md and read references/checkpointing.md. Determine which of three modes applies by combining what's on disk with the user's intent:

• Fresh start — no SRS and no tracker. Create the progress tracker and the SRS skeleton, then begin Phase 1.
• Resume — a tracker exists with pending/in-progress areas (the interview was interrupted). Read both files, summarize what's captured and what remains, and continue from the first pending area.
• Amendment — a finalized SRS exists (tracker shows no pending work, or is marked finalized) and the user wants to change requirements. Switch to amendment handling (Phase A) instead of resuming or restarting.

Detection is automatic — the user passes no special flag. The finalized SRS on disk is the precondition; the user's plain-language intent disambiguates ("add a requirement", "update FR-AUTH-007", "remove…" → amendment; "spec a new project" → fresh; "what does the SRS say…" → just answer). Two firm rules:

• Resume beats amend. If the interview is unfinished and the user asks to add something new, finish the pending areas first, then handle the new request — amending a half-specified SRS invites inconsistency.
• When an SRS exists and intent is ambiguous, confirm before acting — never silently restart. A bare invocation against a finalized SRS gets a short question ("There's a finalized SRS here — v1.2, 47 functional / 19 non-functional. Amend it, ask about it, or start a new one?"), not a guess. The expensive failure is wiping or duplicating a finalized SRS; one cheap question prevents it.

Phase 1 — Frame and scope

Establish the foundation: the product's purpose and vision, business goals and success metrics, the primary stakeholders, the user classes/personas, and the overall scope (what's in, what's out, MVP boundary). Write these into the SRS's introduction and overall-description sections immediately, and mark the area done in the tracker. This section also seeds the user-characteristics content that ux-foundations will later consume.

Phase 2 — Functional requirements, area by area (the detail loop)

This is the core. Read references/elicitation-guide.md and references/requirement-catalog.md. Work through the application one capability area at a time. For each area:

• Propose the standard sub-requirements from the catalog as a checklist, in plain language, and ask the user to confirm / extend / remove.
• Specify each confirmed requirement formally: a unique ID (e.g., FR-AUTH-001), a clear testable statement, priority, and any rules/validation.
• Write the finalized area straight into docs/srs.md, then update the progress tracker before moving to the next area.

Cover every area the application needs — not just the obvious ones. The catalog lists commonly-forgotten areas (audit logging, account deletion, rate limiting, admin/back-office) to prompt with.

Phase 3 — Non-functional requirements

Read the NFR section of references/requirement-catalog.md (organized on the ISO 25010 quality model). Walk each relevant category — performance, scalability, availability/reliability, security, usability/accessibility, compatibility, maintainability, compliance/legal, localization, observability — and specify measurable NFRs with unique IDs (e.g., NFR-PERF-001). Vague NFRs are not acceptable; "fast" becomes a number. Write into the SRS and checkpoint.

Phase 4 — External interface requirements

Capture the external interfaces the SRS lineage expects: user interfaces (at the requirements level), hardware, software/third-party integrations, and communication interfaces. Write into the SRS and checkpoint.

Phase 5 — Use cases

Read references/use-case-guide.md. Derive use cases from the functional requirements. For each use case, write a detailed textual specification (ID, name, actors, preconditions, postconditions, main success scenario, alternate flows, exception flows, and the FRs it traces to) into docs/use-cases.md, and add the Mermaid use-case diagram(s) grouping actors and use cases by the system boundary. Checkpoint as you complete each use case.

Phase 6 — Traceability matrix

Read references/rtm-guide.md and build docs/rtm.md: a table linking every requirement ID to its source and to the use case(s) that exercise it, with placeholder columns for the downstream design and test artifacts. Because every requirement was given a stable ID during specification, this is largely assembly.

Phase 7 — Deliver

Confirm all three files exist. Summarize the requirement counts (e.g., "47 functional across 8 areas, 19 non-functional, 12 use cases") and any open questions or TBDs flagged during elicitation. Note that docs/srs.md is the source of truth the architecture, UX, and planning skills will consume. Mark the SRS finalized in the progress tracker (this is what later distinguishes amendment mode from resume). Offer to proceed to software-architecture.

Phase A — Amending a finalized SRS

Entered from Phase 0 when a finalized SRS exists and the user wants to change requirements. Read references/change-management.md for the full protocol. The cardinal rule: requirement IDs are immutable and never recycled — everything downstream references them. In brief:

1. Classify each change as add, modify, or remove, and apply its rule:
   • Add → assign the next free ID in that area (never reuse a retired number), specify it with the same enumeration discipline, append it.
   • Modify → keep the same ID, change the statement.
   • Remove → do not delete or renumber; mark the requirement Deprecated/Removed and keep the row so traceability and dangling references stay visible.
2. Version and log. Bump the SRS version and add a revision-history entry recording what changed, when, and which IDs were affected.
3. Propagate. Update the use case(s) that trace to the changed ID and update the RTM row(s) so all three markdown files stay consistent. The RTM is the index for what a change touches.
4. Emit a cross-skill impact note. When a finalized requirement that downstream docs were built on is modified or removed, you can't edit those docs, but you must not stay silent: report which downstream documents referenced the affected IDs (architecture, ux-foundations, implementation-plan) so the user knows what to review or re-run.

Amendment reuses the same catalog, templates, and checkpointing as authoring — each amendment is itself written to disk and logged before moving on.

Scope boundaries

It deliberately does not:

• slice requirements into epics/vertical features — that's implementation-planning;
• make architectural or UX design decisions — those are the design-phase skills (which will read this SRS rather than re-eliciting NFRs and personas);
• write user stories — this is use-case-centric by design.

What good looks like

• Every capability area is enumerated to its standard sub-requirements, not just what the user first mentioned.
• Every requirement has a unique, stable ID and is individually testable.
• NFRs are measurable, never vague.
• Work is checkpointed so a stop or network drop never loses captured areas.
• The three outputs are internally consistent and cross-referenced via the RTM.