Generated from cat-harness/skills/sdlc/sdlc-core/specification-management.md — do not edit here.

✎ Edit this page’s source

Specification and requirements management

Skill id: specification-management · Package: sdlc-core

This skill defines the governance, architectural boundaries, and standards alignment for authoring, tracing, and verifying specifications and requirements across the harness.

1. The two authoring tracks and the single requirement definition

Requirements enter the harness via two distinct, non-blended tracks (distinguished in methodology-adoption and spec-kit):

  1. Platform / Tooling Track (spec-kit): For capabilities raised by tool developers where requirements are content-agnostic (specify → plan → tasks → implement → converge). Requirements are drafted as FR-### with SC-### in issue comments.
  2. Domain / Guideline Track (crdm): For requirements tied to WHO/IG domain content and subject matter requiring formal stakeholder sign-offs (needs → detect → requirements → impact → signoff → close). Authored in docs/requirements/<slug>.md.

They share one underlying definition of a requirement (Issue #2405, FR-007/FR-008; detailed in requirement-definition.md):

PartField in bootstrap/schemas/requirement.schema.jsonObligation
IDid (req:<slug>#<key>)Unique, stable, addressable URI
Title / Labeltitle (doc), label (statement)Concise human-readable name
StatementrequirementExactly one sentence checkable as yes/no
ConformanceconformanceRFC 2119 verb (SHALL, SHOULD, MAY, SHALL NOT)
Rationalebenefit, descriptionClear justification and expected value
ParentderivedFromUpstream requirement lattice link
Success CriteriasuccessCriteria[].criterionObservable, measurable verification conditions (≥ 1)
Verification MethodsuccessCriteria[].verificationOne of test, inspection, review, analysis

2. Standards alignment and statement quality

While the bootstrap schema is deliberately lightweight and zero-dependency, requirements authored in the harness must adhere to proven international notations and quality models evaluated in requirements-standards-assessment:

A. EARS syntax for statement formulation

Requirement statements should follow the Easy Approach to Requirements Syntax (EARS) patterns (Mavin et al., IEEE RE 2009):

  • Ubiquitous: “The <system> shall <response>.”
  • Event-driven: “When <trigger>, the <system> shall <response>.”
  • State-driven: “While <state>, the <system> shall <response>.”
  • Unwanted behavior: “If <error/trigger>, then the <system> shall <response>.”
  • Optional feature: “Where <feature present>, the <system> shall <response>.”

B. ISO/IEC/IEEE 29148:2018 verification quartet

Verification methods declared on success criteria map directly to ISO 29148 Clause 6.4:

  • test: Automated execution against test suites (Bun test, Playwright).
  • inspection: Visual verification of files, schemas, or front-matter declarations.
  • review: Adjudicated human or agent qualitative sign-off.
  • analysis: Deductive proof, simulation, or deterministic measurement.

C. ISO/IEC 25010:2023 for non-functional requirements (NFRs)

For statements where kind: "non-functional", the category field must be classified against the ISO 25010 product quality taxonomy (security, performance-efficiency, compatibility, interaction-capability, reliability, maintainability, portability, safety).

3. Boundary rule: no outside concepts in bootstrap

Per the architectural assessment in requirements-standards-assessment:

  • Bootstrap remains pure: No ReqIF XML types, OSLC RDF vocabularies, or heavy third-party dependencies may be added to bootstrap/.
  • Projection lives above: Higher layers (cat-harness, or a content instance above it) provide conversion tools (e.g. exporting RequirementSet to OMG ReqIF 1.2 XML for DOORS/Polarion, or projecting to OSLC-RM JSON-LD).
  • Markdown front matter is the canonical authoring form: Markdown front matter + JSON schemas in Git provide fast parsing, clean PR diffs, and zero vendor lock-in.

4. RequirementSets, work plans, and sign-offs

A requirements document is governed as a RequirementSet (reqset:<slug>):

  • Stages: draft → proposed → approved → planned → in-progress → delivered → accepted.
  • Work Plan: Requirements connect to execution via beans/. A bean delivering a requirement copies its ## Done when checkboxes from the requirement’s success criteria.
  • Sign-offs: Recorded via adjudication as requirement-signoff attestations referencing the governing GitHub issue comment. check:requirements refuses approved or accepted without a recorded human sign-off.

5. Related skills & methodologies

folio-assistant — code under the Apache License 2.0, documentation under CC BY 3.0. Generated schema and API references are rebuilt from source on every push to main.

deployed dev