/writing-trds

name: ring:writing-trds
description: "Writing a Technical Requirements Document that designs the technical architecture of the system or feature: components and boundaries, data flow, integration points, failure modes, and the mandatory program structure (DDD/hexagonal source tree) — in technology-agnostic patterns (code structure excepted), plus auth/pagination and BFF contracts for fullstack. Gate 3 of ring:planning-large-features (after ring:mapping-feature-relationships, before ring:designing-api-contracts) and Gate 2 of ring:planning-small-features (after ring:writing-prds, before ring:writing-plans). Use when the PRD passed validation. Skip when the PRD is unvalidated or the architecture is already documented."

TRD Creation — Architecture Before Implementation

When to use

• PRD passed Gate 1
• Feature Map passed Gate 2 (Large Track only)
• About to design technical architecture

Skip when

• PRD not validated → complete Gate 1 first
• Architecture already documented → proceed to API Design (Large) or plan (Small)
• Pure business requirement change → update PRD

Sequence

**Runs before:** ring:designing-api-contracts (Large Track) / ring:writing-plans (Small Track) **Runs after:** ring:mapping-feature-relationships (Large Track) / ring:writing-prds (Small Track)

The TRD designs the technical architecture of the system or feature: components and their boundaries, data flow between them, integration points, and failure modes — using technology-agnostic patterns before concrete technology choices.

Handling Missing Information

When specific details are not provided (tech stack, architecture, team size, deployment model, etc.):

• Infer from project name, context, existing codebase patterns, and git history
• Document assumptions explicitly in a `## Assumptions` section at the top of the TRD
• **NEVER block execution to ask clarifying questions — assume and proceed**
• Flag assumptions that carry high risk for the reader to validate (mark as `⚠️ Assumption:`)
• The only valid exception: tech stack ambiguity in Step 0 when auto-detection fails and no codebase files exist to infer from

Step -1: Design Validation Check (UI Features Only, Conditional)

Read PRD and detect UI indicators (user stories with "see", "view", "click", "page", "screen", "button", "form"; features involving login, dashboard, settings, reports, notifications).

**If feature has UI:**

• Check `docs/pre-dev/{feature}/design-validation.md` (produced by a standalone ring:validating-ux-completeness run, if one happened)
• If present → honor its verdict: "DESIGN VALIDATED" proceeds; any other verdict means fix the listed design gaps before (or alongside) the TRD
• If absent → **proceed** and add to `## Assumptions`: `⚠️ UX risk: no design validation ran for this UI feature — consider a standalone ring:validating-ux-completeness pass`

**If backend-only:** Skip to Step 0.

Step 0: Tech Stack Definition (HARD GATE)

Step 0.1: Auto-Detect or Ask

• `go.mod` exists → Go
• `package.json` with react/next → Frontend TS
• `package.json` with express/fastify/nestjs → Backend TS
• Ambiguous → AskUserQuestion: "What is the primary technology stack?"

Step 0.2: Load Ring Standards via WebFetch

| Tech Stack | Standards to Load | |------------|-------------------| | Go Backend | golang/index.md + devops.md + sre.md | | TypeScript Backend | typescript.md + devops.md + sre.md | | TypeScript Frontend | frontend.md + devops.md | | Full-Stack TypeScript | typescript.md + frontend.md + devops.md + sre.md |

WebFetch base URL: `https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/`

Step 0.3: Read PROJECT_RULES.md

Check: `docs/PROJECT_RULES.md` → `docs/STANDARDS.md` (legacy) → if neither exists, note the absence and proceed with Ring standards.

Step 0.4: Analyze PRD and Suggest Technologies

Read PRD, extract requirements, suggest technologies per category, confirm with user.

**AskUserQuestion:** "What deployment model?" Options: Cloud, On-Premise, Hybrid

Step 0.5: Document in TRD Metadata

TRD header must include: `feature`, `gate: 3` (Large) / `gate: 2` (Small), `deployment.model`, `tech_stack.primary`, `tech_stack.standards_loaded[]`, `project_technologies[]` (category, prd_requirement, choice, rationale per decision). On Large Track this flows to Gates 4–6.

Mandatory Workflow

| Phase | Activities | |-------|------------| | **1. Analysis** | PRD (required); Feature Map (Large Track); identify NFRs (performance, security, scalability); map domains to components | | **2. Architecture Definition** | Choose style (Microservices, Modular Monolith, Serverless); design components with explicit boundaries; define interfaces; model data flow end-to-end; plan integration points and patterns; design security; produce **Program Design** — bounded contexts (vertical slices) + source tree (see section below) | | **3. Failure Modes** | For each component and integration point: what fails, how it is detected, how the system degrades or recovers (timeout/retry/circuit-break/fallback); consistency under partial failure | | **4. Gate Validation** | All domains mapped; component boundaries clear; interfaces technology-agnostic; data ownership explicit; failure modes covered; quality attributes achievable; no specific products named |

Program Design (Code Structure — MANDATORY)

Every TRD MUST include a `## Program Design` section with **two mandatory parts**: (1) the **bounded contexts / vertical slices** the feature creates or touches, and (2) the **source tree** for each. This anchors implementation to Lerian's mandatory modeling — **Modular Monolith + DDD + Hexagonal (ports & adapters) + CQRS-light** — as shipped in the canonical `go-boilerplate-ddd`. It is the one place a TRD is concrete about *code structure*; it stays silent on *product* choices (see exception note under Technology Abstraction Rules).

Part 1 — Bounded Contexts (Vertical Slices) [MANDATORY]

In