name: pre-dev-trd-creation description: | Gate 3: Technical architecture document - defines HOW/WHERE with technology-agnostic patterns before concrete implementation choices.

trigger: |

PRD passed Gate 1 (required)
Feature Map passed Gate 2 (if Large Track)
About to design technical architecture
Tempted to specify "PostgreSQL" instead of "Relational Database"

skip_when: |

PRD not validated → complete Gate 1 first
Architecture already documented → proceed to API Design
Pure business requirement change → update PRD

sequence: after: [pre-dev-prd-creation, pre-dev-feature-map] before: [pre-dev-api-design, 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 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.md	`https://raw.githubusercontent.com/LerianStudio/ring/main/dev-team/docs/standards/golang.md`	Go patterns, DDD
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.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

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

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

Output & After Approval

Output to: docs/pre-dev/{feature-name}/trd.md

✅ Lock TRD - architecture patterns are now reference
🎯 Use as input for API Design (pre-dev-api-design)
🚫 Never add technologies retroactively
📋 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.

pre-dev-trd-creation