tercel/spec-forge/srs-generation

SRS Generation Skill

What Is a Software Requirements Specification?

A Software Requirements Specification (SRS) is a formal document that describes exactly what a software system must do and the constraints under which it must operate. It serves as the contractual bridge between stakeholders who define the product vision (captured in a PRD) and the engineering team that designs, builds, and tests the system. A well-written SRS eliminates ambiguity, reduces rework, and provides a single source of truth for every requirement the system must satisfy.

The two foundational standards for SRS documents are IEEE 830 (IEEE Recommended Practice for Software Requirements Specifications) and ISO/IEC/IEEE 29148 (Systems and Software Engineering -- Life Cycle Processes -- Requirements Engineering). IEEE 830 established the canonical section structure -- introduction, overall description, specific requirements -- and defined the quality attributes every requirement must exhibit: correctness, unambiguity, completeness, consistency, ranking for importance, verifiability, modifiability, and traceability. ISO/IEC/IEEE 29148 modernized this foundation by integrating requirements engineering into the full systems and software lifecycle, emphasizing stakeholder needs analysis, requirements analysis, and requirements validation as continuous activities rather than one-time documentation events. This skill combines the structural rigor of both standards with the pragmatic, metric-driven approach found in Amazon technical specifications, where every requirement must be tied to a measurable outcome.

Generation Workflow

The SRS generation process follows a six-step workflow designed to produce a complete, high-quality document:

Step 1: Scan Context

Before writing a single requirement, scan the project to build context:

@../shared/project-context.md

Execute the Project Context Protocol. Prefer its PC.0 fast path — resolve <sf_scripts> (see @../shared/scripts.md) and run python3 "<sf_scripts>/sf-scan.py" --root "<project_root>", which returns the languages, frameworks, DB/auth signals, test command, and the existing-doc inventory (including any upstream prd.md with its declared IDs) in one pass. Fall back to the manual PC.1–PC.3 scan only if the script is unavailable. Then apply judgement the script does not: label the project profile (PC.3) and pick which non-functional requirement categories are most relevant (e.g., database-backed projects need data integrity NFRs; CLI tools need usability NFRs).

Step 1.5: Doc-First Discipline (Mandatory)

Before locating the upstream PRD or writing any requirements, the doc-first discipline applies. Read the existing documentation, identify what already covers the topic, and decide for each requirement whether to REUSE (reference existing), EXTEND (edit existing in place), or NEW (genuinely missing). The default for any requirement that has coverage in an existing SRS is to extend in place — never to create parallel srs-v2.md files, never to append ## Update blocks, never to leave deprecated requirements strikethrough'd. Requirement IDs are contracts: once issued, they should not be silently re-purposed.

The full discipline, the four rules, the pre-generation checklist, and the anti-patterns to avoid:

@../shared/doc-first.md

You MUST run the pre-generation checklist (the five questions) from doc-first.md before proceeding to Step 2. If existing docs already cover any of the requirements this SRS will discuss, you must:

1. List the existing files and requirement IDs that overlap (with file:line references)
2. Decide REUSE / EXTEND / NEW for each requirement
3. Bias toward EXTEND — opening the existing SRS and modifying it — over NEW
4. Preserve existing requirement IDs. Once a requirement ID has been issued, it must not be silently renumbered. If a requirement is split, the original ID is retained for one of the parts and the new parts get new IDs. If a requirement is removed, its ID is retired (not reused).
5. Surface any downstream documents (tech-design, test-cases, feature specs) this generation will affect, so the user knows the propagation cost

If the project shows signs of doc drift (multiple srs-*.md files, obvious duplication, requirement ID collisions), warn the user before proceeding and recommend they run /spec-forge:analyze or /spec-forge:propagate first.

If a usable existing SRS already covers most of what the user is asking for, the right action is edit it in place, not generate a new file.

Step 2: Find the Upstream PRD

The most critical input to any SRS is the Product Requirements Document. The sf-scan.py inventory from Step 1 already reports any docs/<feature-name>/prd.md (under document_index.prd) and the requirement IDs it declares; read that PRD thoroughly. The PRD provides the product vision, user stories, feature definitions, success metrics, and scope boundaries that the SRS must formalize into precise, testable requirements. If no PRD is found, proceed but flag that traceability to product-level requirements will be limited.

Step 3: Clarify Only What You Cannot Infer

First infer every answer you can from the PRD, the scanned project context, and any existing SRS — and state those inferences as explicit assumptions the user can correct. Then ask the user only the questions whose answers materially change the requirements and cannot be inferred: typically specific NFR thresholds (response-time targets, concurrent-user capacity, data-retention policies), regulatory obligations, and integration contracts. Do not march through a fixed questionnaire or re-ask anything the upstream docs already answer; a strong scan often makes most questions unnecessary.

Step 4: Generate the SRS

Using the template at references/template.md, the skill generates the full SRS document. Every section of the IEEE 830 structure is populated: introduction, overall description, functional requirements, non-functional requirements, data requirements, external interface requirements, and the requirements traceability matrix. Requirements are written following the conventions and quality standards described in the sections below.

This document is the delivery contract. The SRS is what an implementation team — an external vendor, another team, or code-forge — is held to. The upstream PRD answers "is this worth building and for whom"; the SRS answers "exactly what must be built, and how do we settle whether it was". That distinction drives six sections that a merely descriptive requirements document omits, and that this skill treats as mandatory wherever they apply:

Omit any of these only when it genuinely does not apply — a requirement that takes no input needs no field-rule table — and say so explicitly in the document rather than deleting the heading silently. A missing section reads as an oversight; a section marked "N/A: this feature has no entity with a lifecycle" reads as a decision.

Step 5: Traceability

If an upstream PRD was found, build a requirements traceability matrix (RTM) that maps every PRD feature or user story to one or more SRS requirements, with a coverage status (Fully / Partially / Not Covered). Let the script layer do the coverage math: after the SRS is drafted, run

python3 "<sf_scripts>/sf-trace.py" matrix --upstream "<prd.md>" --downstream "<srs.md>"

and use its uncovered_upstream (PRD IDs with no SRS requirement — coverage gaps to close) and orphan_downstream_refs (SRS references to PRD IDs that do not exist — dangling links to fix). The script computes the coverage; you decide whether each gap is intentional (out of scope) or a real omission. Fall back to building the matrix by hand if the script is unavailable.

Step 6: Quality Check

Run the structural gate with the script, then apply judgement with the checklist:

python3 "<sf_scripts>/sf-verify-doc.py" "<srs.md>" --strict

This deterministically confirms the title, recommended IEEE 830 sections, ID format/uniqueness (a heading plus its ID table row count as one definition), and the absence of leftover template placeholders. Fix everything it flags. Then load references/checklist.md and evaluate the items the script cannot judge — requirement unambiguity, testability, whether each NFR target has a real threshold rationale. The document is only written to disk once the structural gate passes and the judgement items hold. (If python3 is unavailable, run every checklist item by hand.)

Requirement ID Conventions

Every requirement receives a unique identifier that encodes its type and module or category:

• Functional Requirements: FR-<MODULE>-<NNN> where <MODULE> is a short uppercase label for the feature module (e.g., AUTH, CART, SEARCH, NOTIFY) and <NNN> is a zero-padded sequential number. Examples: FR-AUTH-001, FR-CART-012, FR-SEARCH-003.
• Non-Functional Requirements: NFR-<CATEGORY>-<NNN> where <CATEGORY> identifies the quality attribute (e.g., PERF, SEC, REL, AVL, MNT, PRT, USB) and <NNN> is a zero-padded sequential number. Examples: NFR-PERF-001, NFR-SEC-003, NFR-REL-002.

These IDs are used throughout the document -- in the requirements traceability matrix, in cross-references between related requirements, and in downstream documents such as technical designs and test plans. Consistent ID formatting is essential for automated traceability and search. When extending an existing SRS, allocate the next free number deterministically instead of guessing: python3 "<sf_scripts>/sf-trace.py" next-id --prefix FR --module AUTH --existing "<srs.md>" returns the next unused FR-AUTH-NNN (respecting existing zero-padding), which avoids collisions and reuse.

Functional Requirements Writing Standards

Each functional requirement is structured as a complete use case specification with the following elements: