The document chainCopy link

Most software documentation is shaped wrong. There’s usually too much of it, organised by who wrote it rather than by what it’s for, and the connections between documents are stored in people’s heads instead of on the page. By the time you need to ask “why does this function exist,” half the relevant documents have rotted past usefulness and the other half are describing a version of the product that was deprecated six months ago.

RCF’s document chain is the set of artefacts that closes that gap, with the relationships between them made explicit. The chain has two upstream arms that meet at the build:

• The intent arm: PRD → requirements → user stories → acceptance criteria. What must be true.
• The architecture arm: TAD → components → ADRs. The system in which it must be true.

The two arms converge at the build chain: build sequence → functional build specification → test suite → test case. The FBS is the explicit join point. It pulls in the in-scope ACs from the intent arm and the in-scope TAD components and ADRs from the architecture arm, and turns the two into a buildable slice. This is also the point in the chain where spec-driven development (SDD) typically starts; RCF inherits SDD’s spec-as-primary-artefact framing but anchors the spec earlier, in the requirements layer of the intent arm, so the spec-of-intent runs from PRD all the way through to the FBS rather than appearing only at the build boundary.

The artefacts the chain is built from are listed below in reading order. The PRD and TAD originate upstream of RCF as currently scoped. The scoping page covers what that means and what work is coming to address it. From the PRD-and-TAD-agreed point onwards, the chain runs the same shape on every project.

The intent armCopy link

PRD: the productCopy link

The product requirements document sits at the top of the intent arm. It says what the product is, who it’s for, what it does, and what it deliberately doesn’t. The out-of-scope section is a record of decisions the team took to leave certain things out: items the team considered and deliberately chose not to do, with the reasoning attached. That’s different from a defence against change. Scope decisions don’t survive a six-month project intact. They get revisited, sometimes reversed, and they should. The out-of-scope record makes the reversal a deliberate act, with an audit trail of what changed and why, rather than a quiet drift the team rationalises later.

Inside the PRD lives the requirements list. Each requirement is a short statement of what the product must do, with a category (functional, non-functional, regulatory), a priority (must, should, could), and a domain (auth, billing, search, whatever the product is made of). Requirements aren’t where you describe how something works. They’re where you commit to what works.

User stories: the human shape of a requirementCopy link

A requirement on its own is hard to build against. It’s a statement of intent, not a description of behaviour. So each requirement breaks down into user stories, the familiar “as a [role] I want [action] so that [outcome]” shape.

The story’s job is to give the requirement a human shape. A requirement that says “the product supports OAuth sign-in” might break into stories about first-time signup, returning sign-in, account linking, and sign-out, each with its own actor and outcome. The stories are what a product owner thinks in. The requirement is what they commit to.

Acceptance criteria: the contractCopy link

Each story carries one or more acceptance criteria. The AC is where things get specific. A criterion is a Given/When/Then sentence: given a precondition, when an event happens, then an observable thing must be true. AC text is what tests are built from, one to one.

ACs are the central primitive of the methodology, and they get their own page: Acceptance criteria as the contract. The short version is that AC is the layer at which intent becomes verifiable. Most ACs are verified by an automated test suite, and that’s the default the methodology is built around. A few land on a human-attested check instead: a k8s cluster following a naming convention, a deployed manifest matching a target shape, anything where the verification step is a human reviewer reading a real artefact against the rule. The rule is verifiability, not test-automation. If the criterion can’t be verified at all, it isn’t a real AC.

The architecture armCopy link

The architecture arm runs in parallel to the intent arm and produces the system the requirements have to be true in. Same Y-shape, same chain discipline, different content.

TAD: the system the requirements needCopy link

The technical architecture document is the top of the architecture arm. It 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. One per product, sibling to the PRD.

The TAD’s job is to make sure that when somebody builds a slice, they build it against a system that exists. It does for the architecture what the PRD does for intent: it’s the artefact that the rest of the arm hangs from.

TAD components: the moving partsCopy link

Under the TAD sit its components: the named services, data stores, queues, integrations, and shared modules the architecture is made of. Each one is a technical architecture component, with its own opaque ID prefixed TAC-, so it sits next to TAD and ADR in the chain’s ID scheme rather than under an ad-hoc letter of its own. TACs get referenced from FBSs by ID, the same way ACs do. A TAC is the architecture-arm equivalent of a story on the intent arm: the named unit the build slice depends on.

ADRs: the decisions that shaped the systemCopy link

Architectural Decision Records sit at the bottom of the architecture arm. Each ADR captures one consequential choice: the context, the decision, the alternatives considered, the consequences. All in a form that survives the conversation that produced it. ADRs reference the TAD they sit under and the components they constrain. FBSs reference them as build context the worker needs. The ADR pages are at architectural decisions.

The build chainCopy link

Both arms feed into the build chain. The FBS is the explicit join: it takes the in-scope ACs from the intent arm and the in-scope TAD components and ADRs from the architecture arm, and turns them into a slice the agent or team can build. From the FBS downwards, the chain is linear again.

Build sequence: the planCopy link

The build sequence is the directed acyclic graph that gets you from nothing to shipped. Each node on the graph is a functional build specification, a slice of the product you can build, test, and ship in one go. Each edge is a dependency: this FBS can’t start until that one is done.

Sequencing matters more than people think. A well-shaped build sequence ships vertical slices that prove the product works end to end as soon as possible. A badly-shaped one ships horizontal layers that look like progress on a status report but produce no shippable behaviour for weeks. The build sequence is where that gets decided.

Functional build specification: where the arms meetCopy link

A functional build specification is the brief the worker actually executes against, and the explicit convergence point of the two arms. It pulls together both sides into one buildable slice. From the intent arm: which stories and ACs are in scope, which PRD sections the worker needs to read. From the architecture arm: which TAD components and ADRs the slice depends on, which modules and schemas the work will touch. Plus the surrounding context the worker needs to do the slice well: dependencies on other FBSs that must finish first, the relevant business patterns, standards, style guidelines, and instructions.

The FBS carries a list of testable outcomes, which is the restatement of the in-scope ACs in the worker’s terms. The testable outcomes are the AC-level commitments the slice will be marked against; they’re what makes the AC text actionable inside one build cycle.

The FBS is also where the build context lives: the curated set of references that a worker (human or agent) needs to do the slice without grepping for orientation. That context isn’t a generic dump of the codebase. It’s the specific PRD sections, TAD components, ADRs, code modules, and external docs that the slice depends on. Getting this right is most of why AI agents do good work on RCF projects when they’d otherwise produce nonsense.

Test suite and test case: where intent becomes behaviourCopy link

Each acceptance criterion gets one test suite. One to one, no exceptions. The suite implements the criterion in code. The suite is made up of test cases, the individual scenarios that, together, prove the criterion is met: the happy path, the named edge cases, the failure modes.

The one-to-one rule between AC and suite is what makes traceability possible. Run a single command and you can ask “is AC-042-03 passing” or “which tests would I need to look at if requirement REQ-014 changed.” The answers are mechanical because the structure is mechanical.

Reading the chain end to endCopy link

Start with a business decision. The product needs to support exporting user data. On the intent arm, that decision becomes REQ-019 in the PRD, functional, should-have, domain: privacy. REQ-019 generates US-088: as a user I want to download my data so that I can take it elsewhere. US-088 carries three acceptance criteria, AC-088-01 through AC-088-03, covering the happy path, the size cap, and the format.

On the architecture arm, TAD-001 establishes a background job service for long-running work, with ADR-014 recording the decision to route exports through it (alternatives considered: synchronous endpoint, separate worker pool). Components on the arm: the job service, the storage service, the identity service.

The two arms meet at FBS-051. The FBS’s storyScope is { US-088: [AC-088-01, AC-088-02, AC-088-03] }. Its buildContext points to TAD-001 Section 4 (Jobs), the storage service component, and ADR-014. The build sequence places FBS-051 after FBS-016, which stood up the job service. When a worker picks FBS-051 up, they have one document that names what must be true (the ACs) and what system it must be true in (the TAD components and ADR). They write three test suites, then they write the code, then everything goes green, then FBS-051 closes. REQ-019 is now satisfied, and the satisfaction is provable from the chain.

Reading the chain bottom up works just as well. Pick a function in the export handler. Find the suite that covers it. Find the AC that suite implements. Find the story that holds the AC. Find the requirement the story serves. Find the business decision the requirement encodes. From the same function, you can also walk into the architecture arm: which TAD components is the function part of, which ADRs constrained how it was built. Each step is one hop, and each hop is mechanical.

Why this many layers and not fewerCopy link

The obvious objection is that this is a lot of layers. It is. The shorter version, requirement → test → code, would be cleaner. But each layer is there because the layer above and below can’t do its job otherwise.

On the intent arm: requirements need stories because a requirement is too abstract to test. Stories need ACs because a story is too vague to test directly. ACs need test suites because behaviour needs implementing in code, not in prose.

On the architecture arm: the TAD needs components because the system is made of named parts that get referenced individually. Components need ADRs because the consequential choices about each part need to outlive the conversation that produced them.

In the middle: the build sequence and FBS exist because somebody has to decide what gets built when, with what dependencies, drawing what from each arm, or the work fragments.

Each layer is a place where one specific kind of decision gets made and pinned down. Compress the layers and decisions either get made in the wrong place, or stop getting made at all, or get made silently by the worker on the spot. None of those are decisions you want.

The chain is also context engineering at the team scale. Each layer is the context the next layer needs. The agent gets the right slice of intent at the right point in the build, instead of a generic dump of the codebase or a crammed prompt that hopes for the best. That’s the methodology earning its keep on the agent’s behalf as well as the team’s.

Vocabulary, ID schemes, and what to look up nextCopy link

Every document type has an ID. PRD-001. REQ-014. US-042. AC-042-03. TAD-001. TAC-007. ADR-014. FBS-027. TS-088-01. The IDs are opaque strings, never renumbered, never reused. They’re how traceability happens at the system level: code references an AC ID, a test suite ID matches an AC ID, a work item ID points at an FBS ID. The string is the lookup key.

A word about toolingCopy link

The chain runs on plain text. The methodology itself is markdown for the prose, JSON for the structured fields, and git for the history. Git is the system of record: every artefact, every ID, every state change in the chain lives in commits, and the history of the project is the history of its requirements. Every ID-pointer relationship the chain depends on is greppable from a terminal.

In practice, that base layer needs a little help even for a basic implementation. A small CRUD CLI to query and validate the chain, and a handful of coding-agent commands to drive the build cycle, are the minimum: several artefact types with opaque IDs and one-to-one mappings across a two-hundred-FBS product isn’t a comfortable manual job, and the build cycle goes a lot smoother when the agent knows the stage names. Stravica will publish that CRUD layer soon. Beyond it, the integration and enablement layer is wide open, anything up to a full generative agent that drafts artefacts against the standards and runs the diff against the gap. That’s where Stravica builds, because the leverage compounds at scale. The methodology is what’s stable; the tooling is how you make it tractable.

Full vocabulary is in the glossary. ID schemes per document type are catalogued on the document types page. For the next concept in the reading order, see Acceptance criteria as the contract.