ringpre-dev-trd-creation

name	ring:pre-dev-trd-creation
description	Gate 3: Technical architecture document - defines HOW/WHERE with technology-agnostic patterns before concrete implementation choices.
license	MIT
compatibility	opencode
metadata	{"trigger":"- PRD passed Gate 1 (required)\n- Feature Map passed Gate 2 (if Large Track)\n- About to design technical architecture\n- Tempted to specify \"PostgreSQL\" instead of \"Relational Database\"\n","skip_when":"- PRD not validated → complete Gate 1 first\n- Architecture already documented → proceed to API Design\n- Pure business requirement change → update PRD\n"}
sequence	{"after":["ring:pre-dev-prd-creation","ring:pre-dev-feature-map"],"before":["ring:pre-dev-api-design","ring:pre-dev-task-breakdown"]}

TRD Creation - Architecture Before Implementation

Foundational Principle

Architecture decisions (HOW/WHERE) must be technology-agnostic patterns before concrete implementation choices.

Specifying technologies in TRD creates:

• Vendor lock-in before evaluating alternatives
• Architecture coupled to specific products
• Technology decisions made without full dependency analysis

The TRD answers: HOW we'll architect the solution and WHERE components will live. The TRD never answers: WHAT specific products, frameworks, versions, or packages we'll use.

---

⛔ HARD GATE: Design Validation Prerequisite (Step -1)

This check MUST happen BEFORE any TRD work begins.

Step -1.1: Detect if Feature Has UI

Read PRD from docs/pre-dev/{feature}/prd.md and check for UI indicators:

• User stories with: "see", "view", "click", "navigate", "page", "screen", "button", "form"
• Features involving: login, dashboard, settings, profile, reports, notifications, UI, interface
• Any direct user-facing interaction

Step -1.2: If Feature Has UI → Verify Design Validation

⛔ HARD GATE: If feature has UI, design-validation.md MUST exist and show VALIDATED verdict.

Check: docs/pre-dev/{feature}/design-validation.md

If file NOT FOUND:
  → STOP. Cannot proceed to TRD.
  → Message: "Design Validation (Gate 1.5/2.5) not completed.
             Run ring:pre-dev-design-validation before TRD."

If file FOUND but verdict is NOT "DESIGN VALIDATED":
  → STOP. Cannot proceed to TRD.
  → Message: "Design Validation failed with gaps.
             Fix design gaps and re-run validation before TRD."

If file FOUND and verdict is "DESIGN VALIDATED":
  → PASS. Proceed to Step 0.

Step -1.3: If Feature Has NO UI → Skip to Step 0

Backend-only features do not require design validation. Proceed directly to tech stack definition.

Anti-Rationalization for Design Validation Check

Rationalization	Why It's WRONG	Required Action
"Design validation is optional"	It's MANDATORY for UI features. Incomplete design = implementation rework.	STOP. Run design validation first.
"We'll validate design later"	Later = after architecture. Changes cascade.	STOP. Validate design NOW.
"The wireframes look complete"	"Look complete" ≠ validated. Run systematic check.	STOP. Run design validation.
"We're in a hurry, skip validation"	Hurry now = 10x rework later.	STOP. No shortcuts.
"TRD doesn't depend on design"	TRD for fullstack features depends on UI architecture decisions.	STOP. Validate design first.
"Design validation just passed informally"	Informal ≠ documented. Need design-validation.md with VALIDATED.	STOP. Run formal validation.

Pressure Resistance for Design Validation Check

User Says	Your Response
"Skip design validation, we're behind schedule"	"Design validation prevents 10x implementation rework. CANNOT proceed to TRD without it."
"The designer approved it verbally"	"Verbal approval ≠ systematic validation. Need design-validation.md with VALIDATED verdict."
"We can validate design in parallel with TRD"	"TRD depends on complete design. Cannot architect what isn't fully specified. Run validation first."
"Just this once, trust me the design is complete"	"Trust but verify. Ring requires documented validation. Run ring:pre-dev-design-validation."

---

⛔ HARD BLOCK: Tech Stack Definition (Step 0)

This is a HARD GATE. Do NOT proceed without defining the tech stack.

Step 0.1: Auto-Detect or Ask User

Auto-detection: go.mod exists → Go | package.json with react/next → Frontend TS | package.json with express/fastify/nestjs → Backend TS

If ambiguous, AskUserQuestion: "What is the primary technology stack?" Options: Go (Backend), TypeScript (Backend), TypeScript (Frontend), Full-Stack TypeScript

Step 0.2: Load Ring Standards via WebFetch

Standard	URL	Purpose
golang/index.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang/index.md	Go patterns index (modular)
typescript.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/typescript.md	TS patterns, async
frontend.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/frontend.md	React, Next.js, a11y
devops.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/devops.md	Docker, CI/CD
sre.md	https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/sre.md	Health checks, logging

Tech Stack	Load
Go Backend	golang/index.md (then required modules) + 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

Step 0.3: Read PROJECT_RULES.md

Check: docs/PROJECT_RULES.md → docs/STANDARDS.md (legacy) → STOP if not found

Step 0.4: Analyze PRD and Suggest Technologies

Read PRD, extract requirements, suggest technologies that address each, present to user for confirmation. Document in TRD metadata for Gate 6 to create PROJECT_RULES.md.

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

Step 0.5: Document in TRD Metadata

TRD header must include: feature, gate: 3, deployment.model, tech_stack.primary, tech_stack.standards_loaded[], project_technologies[] (category, prd_requirement, choice, rationale per technology decision)

This metadata flows to Gates 4-6.

Pressure Resistance for Step 0

Pressure	Response
"Tech stack doesn't matter for architecture"	"Architecture patterns vary by language. Go patterns ≠ TypeScript patterns. Define stack first."
"We'll decide tech stack later"	"Later = Dependency Map. But architecture NOW needs to know capabilities. Define stack."
"Just use generic patterns"	"Generic patterns miss stack-specific best practices. 5 min to define saves rework."
"Skip to save time"	"Skipping causes Gates 4-6 to ask again. Define once here, inherit everywhere."

---

Mandatory Workflow

Phase	Activities
1. Analysis (After Step 0)	PRD (Gate 1) required; Feature Map (Gate 2) optional; identify NFRs (performance, security, scalability); map domains to components
2. Architecture Definition	Choose style (Microservices, Modular Monolith, Serverless); design components with boundaries; define interfaces; model data architecture; plan integration patterns; design security
3. Gate 3 Validation	All domains mapped; component boundaries clear; interfaces technology-agnostic; data ownership explicit; quality attributes achievable; no specific products named

Explicit Rules

✅ DO Include

System architecture style (patterns, not products), component design with responsibilities, data architecture (ownership, flows - conceptual), API design (contracts, not protocols), security architecture (layers, threat model), integration patterns (sync/async, not tools), performance targets, deployment topology (logical)

❌ NEVER Include

Technology products (PostgreSQL, Redis, Kafka), framework versions (Fiber v2, React 18), language specifics (Go 1.24, Node.js 20), cloud services (AWS RDS, Azure Functions), packages (bcrypt, zod, prisma), container orchestration (Kubernetes, ECS), CI/CD details, IaC specifics

Technology Abstraction Rules

Element	Say This (✅)	Not This (❌)
Database	"Relational Database"	"PostgreSQL 16"
Cache	"In-Memory Cache"	"Redis" or "Valkey"
Message Queue	"Message Broker"	"RabbitMQ"
Object Storage	"Blob Storage"	"MinIO" or "S3"
Web Framework	"HTTP Router"	"Fiber" or "Express"
Auth	"JWT-based Authentication"	"specific library"

Rationalization Table

Excuse	Reality
"Everyone knows we use PostgreSQL"	Assumptions prevent proper evaluation. Stay abstract.
"Just mentioning the tech stack for context"	Context belongs in Dependency Map. Keep TRD abstract.
"The team needs to know what we're using"	They'll know in Dependency Map. TRD is patterns only.
"It's obvious we need Redis here"	Obvious ≠ documented. Abstract to "cache", decide later.
"I'll save time by specifying frameworks now"	You'll waste time when better options emerge. Wait.
"But our project template requires X"	Templates are implementation. TRD is architecture. Separate.
"The dependency is critical to the design"	Then describe the capability needed, not the product.
"Stakeholders expect to see technology choices"	Stakeholders see them in Dependency Map. Not here.
"Architecture decisions depend on technology X"	Then your architecture is too coupled. Redesign abstractly.
"We already decided on the tech stack"	Decisions without analysis are assumptions. Validate later.

Red Flags - STOP

If you catch yourself writing any of these in a TRD, STOP:

• Specific product names with version numbers
• Package manager commands (npm install, go get, pip install)
• Cloud provider service names (RDS, Lambda, Cloud Run, etc.)
• Framework-specific terms (Fiber middleware, React hooks, Express routers)
• Container/orchestration specifics (Docker, K8s, ECS)
• Programming language version constraints
• Infrastructure service names (CloudFront, Cloudflare, Fastly)
• CI/CD tool names (GitHub Actions, CircleCI, Jenkins)

When you catch yourself: Replace the product name with the capability it provides. "PostgreSQL 16" → "Relational Database with ACID guarantees"

Gate 3 Validation Checklist

Category	Requirements
Architecture Completeness	All PRD features mapped; DDD boundaries; single clear responsibilities; stable interfaces
Data Design	Ownership explicit; models support PRD; consistency strategy defined; flows documented
Quality Attributes	Performance targets set; security addressed; scalability path clear; reliability defined
Integration Readiness	External deps identified (by capability); patterns selected (not tools); errors considered; versioning strategy exists
Technology Agnostic	Zero product names; capabilities abstract; patterns named not implementations; can swap tech without redesign

Gate Result: ✅ PASS → API Design | ⚠️ CONDITIONAL (remove product names) | ❌ FAIL (too coupled)

Common Violations

Violation	Wrong	Correct
Tech in Architecture	Language: Go 1.24+, Framework: Fiber v2.52+, Database: PostgreSQL 16	Style: Modular Monolith, Pattern: Hexagonal, Data Tier: Relational DB, Key-value store, Object storage
Framework in Components	Fiber middleware for JWT, bcrypt for passwords, passport.js for OAuth2	Auth Component: Purpose, Inbound (HTTP endpoints), Outbound (persistence, notifications), Security (token-based, industry-standard hashing)
Cloud Services in Deployment	Compute: AWS ECS Fargate, Database: AWS RDS, Cache: ElastiCache	Compute: Container-based stateless, Data Tier: Managed DB with backup, Performance: Distributed caching, Traffic: Load balanced with health checks

Pagination Strategy (Required for List Endpoints)

If feature includes list/browse, decide during TRD:

Strategy	Best For	Trade-off	Performance
Cursor-Based	>10k records, infinite scroll, real-time	Can't jump pages	O(1)
Page-Based (Offset)	<10k records, admin interfaces	Degrades with large offsets	O(n)
Page-Based + Total Count	"Page X of Y" UI	Additional COUNT query	2 queries
No Pagination	Very small bounded datasets (<100)	All data at once	-

Document in TRD: API Patterns → Pagination → Strategy + Rationale

Authentication/Authorization Architecture (If Required)

If feature requires authentication or authorization (as determined in Question 2 of pre-dev command):

Auth Type	TRD Description (Abstract)	Implementation Reference
User authentication only	"Token-based authentication with stateless validation"	For Go: golang/security.md → Access Manager Integration
User + permissions	"Token-based authentication with role-based access control (RBAC)"	For Go: golang/security.md → Access Manager Integration
Service-to-service	"Machine-to-machine authentication with client credentials"	For Go: golang/security.md → Access Manager Integration (GetApplicationToken)
Full (user + S2S)	"Dual-layer authentication: user tokens for end-users, client credentials for services"	For Go: golang/security.md → Access Manager Integration

Document in TRD: Security Architecture → Authentication/Authorization → Strategy + Implementation Reference

Key Implementation Pattern (for TRD reference):

• Every protected endpoint requires middleware authorization
• Pattern: auth.Authorize(applicationName, resource, action) on each route
• Engineers will implement per-route protection following the referenced standard

Note for Go Services: Lerian's Access Manager (plugin-auth + identity + lib-auth) is the standard authentication system. Reference golang/security.md → Access Manager Integration section in the TRD so engineers know where to find implementation patterns including route middleware protection.

License Manager Architecture (If Required)

If feature is a licensed product/plugin (as determined in Question 3 of pre-dev command):

License Type	TRD Description (Abstract)	Implementation Reference
Single-org (global)	"Global license validation at service startup with fail-fast behavior"	For Go: golang/security.md → License Manager Integration
Multi-org	"Per-request license validation with organization context"	For Go: golang/security.md → License Manager Integration

Document in TRD: Security Architecture → Licensing → Strategy + Implementation Reference

Key Architecture Pattern (for TRD reference):

• License validation as global middleware (applied early in chain)
• Fail-fast on startup: service refuses to start without valid license
• Graceful shutdown integration for license manager resources
• Built-in skip paths for health/readiness endpoints

Note for Go Services: Lerian's License Manager (lib-license-go) is the standard licensing system. Reference golang/security.md → License Manager Integration section in the TRD so engineers know where to find implementation patterns including global middleware and graceful shutdown.

Frontend-Backend Integration Pattern (If Fullstack)

⛔ HARD GATE: If the feature is fullstack (topology.scope: fullstack), this section is MANDATORY in the TRD.

Step 1: Read api_pattern from research.md

The api_pattern was determined during Topology Discovery (Q7) and persisted in research.md frontmatter.

# From research.md frontmatter
topology:
  scope: fullstack
  api_pattern: bff | none  # bff if dynamic data, none if static

Step 2: Document Pattern in TRD

TRD must include an ## Integration Patterns section:

## Integration Patterns

### Frontend-Backend Communication

**Pattern:** [direct | bff | other]

**Rationale:** [Why this pattern was chosen]

**Architecture Implications:**
- [List architectural decisions driven by this pattern]

Pattern-Specific Documentation

If api_pattern: none (Static Frontend):

### Frontend Architecture

**Pattern:** Static Frontend (no dynamic data)

**Rationale:** Pure static content, no server-side data fetching needed.

**Architecture Implications:**
- Static site generation (SSG) or client-side rendering of static content
- No API routes needed
- No backend integration
- Content embedded at build time or loaded from static files

**Data Flow:**
Build Process → Static HTML/JS → Browser

If api_pattern: bff (MANDATORY for dynamic data):

### Frontend-Backend Communication

**Pattern:** BFF (Backend-for-Frontend) layer

**Rationale:** [Multiple backend services | Complex data aggregation | Sensitive keys to hide | Request optimization needed]

**Architecture Implications:**
- Frontend calls BFF API routes (Next.js API Routes recommended)
- BFF aggregates data from multiple backend services
- Sensitive API keys stored server-side in BFF
- Response transformation happens in BFF layer
- Frontend receives optimized, frontend-specific data shapes

**Data Flow:**
Frontend Component → BFF API Route → Backend Service(s) → Database(s)

**BFF Responsibilities:**
- Data aggregation from multiple services
- Response transformation for frontend consumption
- Authentication token management (httpOnly cookies with Secure and SameSite attributes)
- Rate limiting and caching
- Error normalization

BFF Contract Specification (MANDATORY for BFF Pattern)

⛔ HARD GATE: If api_pattern: bff, this section MUST be included in TRD.

When This Applies

Topology Scope	api_pattern	BFF Contract Required
fullstack	bff	Yes
frontend-only	bff	Yes
fullstack	direct	No
frontend-only	direct	No

BFF Contract Structure

TRD MUST include a ## BFF Contracts section:

## BFF Contracts

### Purpose
Define typed contracts between BFF layer and Frontend components.

### Contract Per Feature

#### Feature: {feature_name}

**BFF Route:** `/api/{feature}/[operation]`

**Frontend Consumer:** `{ComponentName}`

**Request Contract:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| param1 | string | Yes | Description |
| param2 | number | No | Description |

**Response Contract:**
| Field | Type | Nullable | Description |
|-------|------|----------|-------------|
| data | object | No | Main response data |
| data.id | string | No | Entity identifier |
| data.name | string | No | Display name |

**Error Contract:**
| Error Code | Condition | Frontend Handling |
|------------|-----------|-------------------|
| VALIDATION_ERROR | Invalid input | Show field errors |
| NOT_FOUND | Resource missing | Show empty state |
| UNAUTHORIZED | Session expired | Redirect to login |

BFF-to-Backend Mapping

Document how BFF routes map to backend APIs:

### Backend API Mapping

| BFF Route | Backend APIs Called | Aggregation Logic |
|-----------|---------------------|-------------------|
| /api/dashboard | GET /users/:id, GET /orders?userId= | Merge user + recent orders |
| /api/profile | GET /users/:id, GET /preferences/:userId | Merge user + preferences |

Frontend-only BFF Creation

If topology.scope: frontend-only AND api_pattern: bff:

The feature requires creating a NEW BFF layer to consume existing backend APIs.

TRD MUST document:

1. BFF Location: Where BFF code will live (e.g., app/api/ for Next.js)
2. Existing APIs to Consume: List of backend endpoints (from PRD Data Sources)
3. BFF Routes to Create: New routes that aggregate/transform data
4. Type Definitions Location: Where shared types will be defined

### BFF Creation Plan (Frontend-only)

**BFF Framework:** Next.js API Routes / tRPC / Custom

**Existing Backend APIs (from PRD):**
- User API: GET /api/v1/users/:id
- Orders API: GET /api/v1/orders?userId=

**New BFF Routes:**

| Route | Purpose | Backend Calls | Response Shape |
|-------|---------|---------------|----------------|
| /api/dashboard | Dashboard data | users + orders | DashboardData type |
| /api/export/pdf | Generate PDF | orders | Blob |

**Type Definitions:**
- `types/api/dashboard.ts` - DashboardData, DashboardRequest
- `types/api/orders.ts` - Order, OrderList

Rationalization Table for BFF Contracts

Excuse	Reality
"BFF contracts are implementation detail"	Contracts define component boundaries. Must be designed, not discovered.
"Frontend will figure out the types"	Untyped APIs cause runtime errors. Define types upfront.
"We'll add types as we implement"	Missing types cause frontend bugs. Specify contracts in TRD.
"BFF is just a pass-through"	Even pass-through needs error handling and type transformation. Document it.
"Backend already has types"	Backend types ≠ frontend types. BFF transforms shapes. Define both.

BFF Task Ownership (MANDATORY for BFF Pattern)

⛔ HARD GATE: If api_pattern: bff, TRD MUST specify task ownership.

Task Assignment Rules

TRD MUST include a ## Task Ownership section when BFF is involved:

## Task Ownership

### BFF Implementation

| Task Type | Owner | Rationale |
|-----------|-------|-----------|
| BFF route creation | Frontend Engineer | BFF serves frontend, owned by consumer |
| BFF type definitions | Frontend Engineer | Types consumed by frontend components |
| Backend API integration | Frontend Engineer | BFF calls existing APIs |
| Error normalization | Frontend Engineer | Frontend defines error UX |
| Caching strategy | Frontend Engineer | Frontend knows cache requirements |

### Collaboration Points

| Activity | Frontend | Backend | Notes |
|----------|----------|---------|-------|
| BFF contract review | Author | Reviewer | Backend validates API assumptions |
| Type definitions | Author | Contributor | Shared types may exist |
| Error mapping | Author | Consultant | Backend clarifies error semantics |

Why Frontend Owns BFF

Reason	Explanation
Consumer proximity	BFF serves frontend; frontend knows data needs
Type safety chain	Frontend types → BFF types → seamless
Iteration speed	Frontend can modify BFF without backend coordination
Error UX	Frontend defines how errors appear to users

When Backend Should Own BFF

Scenario	Owner	Rationale
BFF includes business logic	Backend	Logic belongs with domain experts
BFF requires database access	Backend	Data layer is backend concern
BFF serves multiple frontends	Backend	Shared layer needs coordination

TRD Must Document

### BFF Ownership Decision

**Owner:** [Frontend Engineer | Backend Engineer]

**Rationale:** [Why this assignment]

**Coordination Required:**
- [ ] Backend API documentation review
- [ ] Type definition alignment
- [ ] Error code mapping

Rationalization Table for Task Ownership

Excuse	Reality
"BFF is backend code"	BFF location ≠ ownership. Consumer drives ownership.
"Let teams figure it out"	Undefined ownership causes delays. Decide in TRD.
"Ownership is obvious"	Obvious to you ≠ clear to team. Document it.
"We can split BFF tasks"	Split ownership causes integration bugs. One owner.

Rationalization Table for Integration Patterns

Excuse	Reality
"Direct API calls are simpler"	FORBIDDEN. Direct client→API calls expose keys, break type safety. BFF is mandatory.
"BFF is overkill for our feature"	If there's dynamic data, BFF is required. Not a choice, a rule.
"We can call the API directly, it's just one endpoint"	Even one endpoint needs error normalization, type safety. Use BFF.
"API pattern doesn't affect architecture"	Pattern determines data flow, security, and layer responsibilities. Document it.
"Client-side fetch is fine for this"	Client-side fetch to external APIs exposes keys. Use BFF.

⛔ HARD RULE: BFF is MANDATORY for Dynamic Data

Client-side code MUST NEVER call backend APIs, databases, or external services directly.

If Feature Has...	api_pattern	Implementation
Dynamic data (API, DB, external)	bff	Next.js API Routes
Static content only	none	No API layer

"Direct API calls" is FORBIDDEN. There is no api_pattern: direct option.

Design System & Styling (For Frontend Features)

⛔ HARD GATE: If the feature includes any user-facing UI, this section is MANDATORY.

Step 1: Detect UI Library

Auto-detection from package.json:

Package Present	UI Library
@lerianstudio/sindarian-ui	Sindarian UI (Radix-based)
@radix-ui/*	Radix UI Primitives
@shadcn/ui or shadcn in devDeps	shadcn/ui
@chakra-ui/react	Chakra UI
@headlessui/react	Headless UI
@mui/material	Material UI
None detected	Ask user for choice

If no UI library detected, AskUserQuestion: "What UI component library will this project use?" Options: shadcn/ui (Recommended), Chakra UI, Material UI, Headless UI, Custom components

Step 2: Document Styling Configuration

TRD must include a ## Design System Configuration section:

## Design System Configuration

### UI Library
- **Library:** [Detected or chosen library]
- **Version:** [Package version from package.json]

### CSS Framework
- **Framework:** [TailwindCSS v4 / CSS Modules / Styled Components / etc.]
- **Config File:** [tailwind.config.ts / postcss.config.js / etc.]

### Theme Integration
- **CSS Variables Required:** Yes/No
- **Dark Mode:** prefers-color-scheme / class-based / not supported
- **Source Directive:** @source path for component styles

### Required CSS Imports
List CSS files that MUST be imported in globals.css:
- `@import "tailwindcss";`
- `@import "@library/dist/components/ui/button/styles.css";`
- etc.

### Theme Variables
Document required CSS custom properties:
- Color scale (zinc, shadcn)
- Spacing variables
- Component-specific variables (button, input, dialog)

Step 3: Component Availability Matrix

TRD MUST document which components exist in the chosen UI library:

### Component Availability

| Component Needed | Available in Library | Notes |
|------------------|---------------------|-------|
| Button | ✅ Yes | Variants: primary, secondary, outline |
| Dialog/Modal | ✅ Yes | Use DialogTrigger pattern |
| Form | ✅ Yes | Requires Form context wrapper |
| Input | ⚠️ Partial | Requires FormField context |
| IconButton | ✅ Yes | Separate component for icon-only |
| Toast | ✅ Yes | Requires Toaster provider |
| Table | ✅ Yes | Use TableHeader, TableBody, etc. |

### Missing Components (Must Create)
- [ ] Component X - not available, need custom implementation

Step 4: Variant Mapping

TRD MUST document available variants to prevent implementation errors:

### Button Variants (Example)

| Design Intent | Correct Variant | WRONG (Don't Use) |
|---------------|-----------------|-------------------|
| Primary action | `variant="primary"` | `variant="default"` |
| Secondary action | `variant="secondary"` | - |
| Cancel/neutral | `variant="outline"` | `variant="ghost"` |
| Destructive | `variant="primary" className="bg-red-600"` | `variant="destructive"` |
| Icon-only | Use `<IconButton>` | `<Button size="icon">` |

Rationalization Table for Design System

Excuse	Reality
"Styling is implementation detail"	Styling bugs cause white screens and broken UX. Document upfront.
"Developers will figure out CSS"	Missing CSS variables = hours of debugging. Specify requirements.
"All UI libraries work the same"	They don't. Form patterns, variants, and contexts vary significantly.
"We'll add dark mode later"	CSS architecture for dark mode must be set from the start.
"Component variants are obvious"	They're not. ghost vs plain vs outline varies by library.
"Just use the library's defaults"	Defaults may not match design. Document exact variants needed.

Red Flags - STOP

If reviewing a TRD for a UI feature and you see NONE of these, STOP and add them:

• No UI library specified
• No CSS framework documented
• No theme variables listed
• No component availability matrix
• No variant mapping

Gate 3 Validation Addition for UI Features

Category	Requirements
Design System	UI library specified; CSS framework documented; theme variables listed; component availability verified; variant mapping complete

ADR Template

**ADR-00X: [Pattern Name]**
- **Context**: [Problem needing solution]
- **Options**: [List with trade-offs - no products]
- **Decision**: [Selected pattern]
- **Rationale**: [Why this pattern]
- **Consequences**: [Impact of decision]

Confidence Scoring

Factor	Points	Criteria
Pattern Match	0-40	Exact before: 40, Similar: 25, Novel: 10
Complexity Management	0-30	Simple proven: 30, Moderate: 20, High: 10
Risk Level	0-30	Low proven: 30, Moderate mitigated: 20, High accepted: 10

Action: 80+ present autonomously | 50-79 present options | <50 request clarification

---

Document Placement

trd.md is a shared document - it defines architecture for the entire feature.

Structure	trd.md Location
single-repo	docs/pre-dev/{feature}/trd.md
monorepo	docs/pre-dev/{feature}/trd.md (root)
multi-repo	Write to BOTH repos

Multi-repo handling:

# Read topology from research.md frontmatter
if [[ "$structure" == "multi-repo" ]]; then
    # Write to both repositories
    mkdir -p "{backend.path}/docs/pre-dev/{feature}"
    mkdir -p "{frontend.path}/docs/pre-dev/{feature}"

    # Write TRD to primary (backend)
    # Then copy to frontend
    cp "{backend.path}/docs/pre-dev/{feature}/trd.md" "{frontend.path}/docs/pre-dev/{feature}/trd.md"
fi

Sync footer for multi-repo:

---
**Sync Status:** Architecture document maintained in both repositories.

---

Output & After Approval

Output to:

• single-repo/monorepo: docs/pre-dev/{feature-name}/trd.md
• multi-repo: Both {backend.path}/docs/pre-dev/{feature}/trd.md AND {frontend.path}/docs/pre-dev/{feature}/trd.md

1. ✅ Lock TRD - architecture patterns are now reference
2. 🎯 Use as input for API Design (ring:pre-dev-api-design)
3. 🚫 Never add technologies retroactively
4. 📋 Keep architecture/implementation strictly separated

The Bottom Line

If you wrote a TRD with specific technology products, delete those sections and rewrite abstractly.

The TRD is architecture patterns only. Period. No product names. No versions. No frameworks.

Technology choices go in Dependency Map. That's the next phase. Wait for it.

Stay abstract. Stay flexible. Make technology decisions in the next phase with full analysis.