Gate 3: Technical architecture document - defines HOW/WHERE with technology-agnostic patterns before concrete implementation choices.
Inherits all available tools
Additional assets for this skill
This skill inherits all available tools. When active, it can use any tool Claude has access to.
name: pre-dev-trd-creation description: | Gate 3: Technical architecture document - defines HOW/WHERE with technology-agnostic patterns before concrete implementation choices.
trigger: |
skip_when: |
Architecture decisions (HOW/WHERE) must be technology-agnostic patterns before concrete implementation choices.
Specifying technologies in TRD creates:
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.
This is a HARD GATE. Do NOT proceed without defining the tech stack.
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
| 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 |
Check: docs/PROJECT_RULES.md → docs/STANDARDS.md (legacy) → STOP if not found
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
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 | 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." |
| 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 |
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)
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
| 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" |
| 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. |
If you catch yourself writing any of these in a TRD, STOP:
When you catch yourself: Replace the product name with the capability it provides. "PostgreSQL 16" → "Relational Database with ACID guarantees"
| 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)
| 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 |
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-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]
| 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 to: docs/pre-dev/{feature-name}/trd.md
pre-dev-api-design)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.