Document types

Product Requirements Document PRD-NNN

The top of the chain. One per product. States what the product is, who it’s for, what it does, and what it deliberately doesn’t do. Holds the requirements list as its main payload. Out-of-scope sections matter as much as in-scope. Lives as a single document; section headings handle internal structure.

References: none upward. Referenced by every Requirement.

Requirement REQ-NNN

A short statement of something the product must do. Carries a category (functional, non-functional, regulatory), a priority (must, should, could), and a domain (auth, billing, search, whatever the product is made of). Requirements describe what, never how. Lives inside the PRD’s requirements list.

References: belongs to one PRD. Generates one or more User Stories.

User Story US-NNN

A requirement expressed through an actor and outcome. The familiar “as a [role] I want [action] so that [outcome]” structure. Stories give a requirement a concrete actor and a stated outcome, which is what acceptance criteria can then test against. A requirement usually generates a small handful of stories, not dozens.

References: belongs to one Requirement. Carries one or more Acceptance Criteria. Belongs to one Functional Build Specification via its fbsId field, with the FBS’s storyScope as the canonical mapping.

Acceptance Criterion AC-NNN-NN

The central primitive of the methodology. A Given/When/Then sentence that names a precondition, an event, and an observable expectation. ACs are scoped to the story they sit on; the second-segment number is the criterion’s position within that story. AC text must be testable as written. If it isn’t, it isn’t a real AC.

References: belongs to one User Story. Verified by exactly one Test Case, which lives inside the Test Suite on that story. See Acceptance criteria as the contract.

Technical Architecture Document TAD-NNN

One per product, top of the architecture arm and sibling to the PRD. Describes the systems and components the product needs: services, data stores, external integrations, the cross-cutting decisions about how data flows and where state lives. The TAD is a single logical artefact, and can include: written sections, diagrams, wireframes, schema definitions, and a decisions section that lists the ADRs. Logical boundary, not file-based.

References: top of the architecture arm. Contains the list of ADRs. Referenced by Functional Build Specifications via the buildContext.tadSections field.

Architectural Decision Record ADR-NNN

One significant architectural choice: context, decision, alternatives considered, consequences and status. ADRs sit under the TAD on the architecture arm and preserve the reasoning for later engineers. Superseded records remain unchanged. A new ADR records the change and links back. See Architectural decisions and ADRs.

References: belongs to one TAD. Referenced by Functional Build Specifications via the buildContext.adrs field. May supersede a prior ADR.

Build Sequence BS-NNN

The plan for getting from nothing to shipped. A directed acyclic graph: each node is a Functional Build Specification, each edge is a dependency between them. One per product. The sequence decides what gets built when. Vertical-slice sequencing (ship working behaviour as early as possible) is the usual target; foundation-first sequencing (stand up shared infrastructure before slices) is the common alternative when there’s real shared work to do. Read the build sequence page for how the order is chosen and what the queue decides once building starts.

References: contains all the Functional Build Specifications for the product. Each FBS declares its dependencies on others.

Functional Build Specification FBS-NNN

The unit of work. One slice of the product, sized so it can be built, tested, and shipped in one go. Carries the slice’s scope (which stories, which ACs), its dependencies (other FBSs that must finish first), its declared build context (PRD sections, TAD components, code modules, schemas, external docs the worker will need), its testable outcomes (the in-scope ACs restated), and its status. The FBS is also what the build cycle (Define → Build → Review → Test → Finalise) runs against.

References: belongs to one Build Sequence. Has zero or more dependency FBSs. Has a storyScope mapping it to specific user stories and ACs.

Test Suite TS-NNN

A named container of test cases sitting on a single User Story, at a stated test level (unit, integration, system, and so on). Verifies one or more of the story’s acceptance criteria via the cases inside it. The suite ID shares the story’s numeric segment (TS-088 sits on US-088), which makes it greppable. The one-to-one binding in RCF is at the case layer: each Test Case pins to exactly one AC.

References: hangs off one User Story. Lists the AC IDs it verifies. Contains one or more Test Cases.

Test Case TC-NNN-NN-NN

The scenario that proves one criterion. Each case pins to exactly one AC via its acId, and each AC has exactly one case that proves it. That is the one-to-one anchor of the framework, and it is what makes coverage attributable per criterion. Cases live inside the suite on the parent user story.

References: belongs to one Test Suite; verifies exactly one Acceptance Criterion.

Code Node CN-NNN

The eleventh and newest kind, added to the schema after the rest. A Code Node makes a piece of source, a file or a single symbol inside one, a first-class node in the graph. Its identity is the path (optionally a #symbol suffix), not a slot on the chain: where every other artefact sits somewhere on the intent, architecture, or build lines, a Code Node hangs off the acceptance criteria it implements, the same way a test suite hangs off its AC. It records the link from a criterion to the code that satisfies it, so that link is something the tooling walks rather than an unchecked comment.

A Code Node may name several acceptance criteria, and several Code Nodes may implement one criterion. It may also name none: a utility, a bit of glue, or wiring with no direct criterion is a legitimate orphan, not an error. When rcf validate runs, it checks every Code Node’s path against the working tree; a rename, move, or delete that breaks the link surfaces as a staleness error naming the node, and the fix is a one-field edit. What it won’t catch is a function that keeps its name while its behaviour changes. That is semantic drift, and it stays the test suite’s job.

References: anchors to zero or more Acceptance Criteria via its implementsAcIds field, and may depend on other Code Nodes through its dependencies field. Like every other document in the chain, it carries a lifecycle status of draft, approved, or deprecated.