Skip to main content
TRW
LEDGER // REQUIREMENTS
EXAMPLE CONTRACT · RISK-SCALED RIGORAARE-F v3.2.1

Requirements that govern the build, not just describe it

When feature or high-risk work needs a durable contract, TRW carries acceptance criteria and FR-by-FR traceability from planning through delivery. The agent verifies work against the spec — not against the conversation.

Get StartedREAD THE REQUIREMENTS SPEC
  • FR01Acceptance criterion

    Rate limit: 100 requests per minute per IP

    middleware/rate_limit.py

  • FR02Acceptance criterion

    429 response includes Retry-After header

    api/responses.py:42

  • FR03Acceptance criterion

    Authenticated users exempt from IP-based limit

    middleware/rate_limit.py:89

  • FR04Acceptance criterion

    Limits configurable per route prefix

    config/limits.yaml

  • FR05Acceptance criterion

    Sliding-window algorithm, Redis-backed

    services/redis_limiter.py

0 of 5 acceptance criteria satisfiedVERIFYING…
LEDGER // PROBLEM

A chat request is context. A requirement is a contract.

Fluent code can still miss the boundary that mattered. TRW converts the request into a versioned artifact that names scope, uncertainty, pass conditions, and the evidence needed to call each requirement verified.

Chat-only brief

OPEN TO INTERPRETATION

“Add rate limiting to the public API.”

  • No declared traffic boundary
  • No failure response contract
  • No proof of completion

Governed contract

REVIEWABLE

WHEN an unauthenticated IP exceeds 100 requests in 60 seconds

THE API SHALL return HTTP 429 with Retry-After

PROVE WITH integration test on the real middleware path

BoundaryBehaviorEvidence
LEDGER // AARE_F

One durable shape makes review repeatable

AARE-F (AI-Augmented Requirements Engineering Framework) defines what a good requirement looks like and how to prove it. Category-aware sections and typed frontmatter give every PRD a predictable spine, while risk level determines how much rigor and independent review the work needs.

Source of intentNeed, decision, issue, incident, or approved request
Scope boundaryGoals, non-goals, dependencies, and explicit assumptions
Singular requirementsUnambiguous behavior with measurable pass conditions
Verification mappingMethod, evidence artifact, pass condition, and automation path
Risk-scaled rigorPriority and consequence set the drafting and review bar
Bidirectional traceabilityNeed → FR → implementation → evidence, and back again
TERMINAL // trw_prd_create

Start with a structured draft, not a fabricated finish

trw_prd_create creates a versioned, category-aware skeleton with frontmatter, required sections, and optional typed verification mappings. It is the beginning of requirements work: grooming fills the gaps, independent review challenges the assumptions, and execution planning binds the contract to real repository paths.

01 // CREATE

Generate the durable skeleton and ID.

02 // GROOM + REVIEW

Resolve ambiguity, risk, scope, and missing proof.

03 // PLAN

Map requirements to files, tests, dependencies, and owners.

TOOL CALL

trw_prd_create(

input_text="Add rate limiting to the public API",

category="INFRA"

)

OUTPUT

PRD-INFRA-042 created

sections_generated: 9

output_path: docs/requirements-aare-f/prds/PRD-INFRA-042.md

index_synced: true

Next: groom → review → execution plan

LATTICE // VALIDATION

Score the draft. Then review the evidence.

trw_prd_validate measures structural readiness with risk-scaled thresholds. The score surfaces missing structure; it does not predict implementation quality. Risk-appropriate independent review and requirement-matched evidence remain the actual closure gate. See the delivery lifecycle.

Medium-risk baseline · configurable by project

35pts

Traceability

Real links to source, code, tests, dependencies, and behavior proof

25pts

Implementation readiness

Control points, switch matrix, key files, and proof tests

20pts

Content density

Substantive decisions over filler; a hygiene signal, not the goal

20pts

Structural completeness

Required sections and frontmatter are present and coherent

DRAFTING AID

A high score means the document is structurally ready for review—not that the feature is correct. When score and behavioral evidence disagree, trust the evidence.

LEDGER // TRACEABILITY

A requirement is verified only when the evidence path closes

The traceability matrix links each FR to its source, implementation surface, declared verification method, evidence artifact, and pass condition. The trw-traceability-checker checker can surface missing links, but paths alone are claims until the declared proof runs on the real behavior.

01 // SOURCE

User need or decision

02 // FR

Singular requirement

03 // CODE

Behavioral control point

04 // EVIDENCE

Test, analysis, inspection, or demo

05 // PASS

Observed result meets the condition

FR01 → rate_limit.py → integration/test_rate_limit.py → 429 + Retry-After observed

CLOSED

Forward: start at the need and prove the shipped behavior.

Backward: start at a code or test change and recover the authority for it.

LEDGER // FAQ

Common questions

Do I have to write PRDs manually?

No. trw_prd_create generates a category-aware AARE-F skeleton from your input. You then groom missing decisions, review assumptions, and bind the plan to real repository paths.

What happens if functional requirements change mid-build?

Update the FRs in the PRD and re-run trw_prd_validate. The quality gate re-checks traceability before IMPLEMENT resumes. No silent drift.

Does this work for small bug fixes?

Yes. Category-aware templates scale the artifact to the work: a focused FIX uses a smaller structure than a CORE feature, while still preserving scope, acceptance criteria, and verification evidence.

How strict are the quality gates?

Thresholds scale by risk and are configurable per project. Treat the score as structural readiness for review; independent review and requirement-matched evidence determine verified closure.
TERMINAL // SHIP_WITH_SPECS

Turn the next request into a contract the build can prove

Create the PRD, review the gaps, and carry requirement-matched evidence through delivery.

GET STARTEDREAD THE REQUIREMENTS SPEC