tech-design-generation

name	tech-design-generation
description	Generates professional Technical Design Documents following industry-standard engineering practices. This skill activates when the user asks to write a technical design, create an architecture design, draft a design doc, write a technical proposal, do system design, create a technical design document, write an RFC, create a design document, or produce an architecture document. It synthesizes best practices from the Google Design Doc format, the RFC template structure, and Uber/Meta engineering design standards to produce comprehensive, implementable technical designs tailored to the user's project and codebase.
instructions	Generate Technical Design Documents by combining the structured decision-making of Google Design Docs, the formal rigor of RFC templates, and the engineering excellence of Uber/Meta design standards. Follow the seven-step workflow defined in this skill, reference the template at references/template.md, and validate output against the checklist at references/checklist.md.

Tech Design Generation Skill

What Is a Technical Design Document?

A Technical Design Document (TDD) is the engineering blueprint that translates product requirements into a concrete, implementable architecture. It sits between the Software Requirements Specification (SRS) and the actual code, serving as the contract between the engineering team and the rest of the organization about how a system will be built. A well-crafted TDD reduces implementation risk, surfaces architectural trade-offs early, and provides a lasting record of why specific technical decisions were made.

The Google Design Doc tradition emphasizes that design documents are not just about documenting a decision after the fact -- they are a tool for thinking through a problem rigorously before committing to code. The RFC (Request for Comments) tradition adds the dimension of structured peer review, ensuring that designs benefit from collective expertise. Uber and Meta engineering standards contribute a focus on scalability, operational readiness, and production-grade thinking from day one.

This skill combines all three traditions. Every generated Technical Design Document evaluates genuine alternative solutions against explicit criteria wherever a real design decision exists, and documents the rationale behind the chosen approach. The document covers architecture, API design, data modeling, security, performance, observability, and deployment -- everything an engineering team needs to move from design to implementation with confidence.

Seven-Step Workflow

Every Technical Design Document generated by this skill follows a disciplined seven-step process. Each step must be completed before moving to the next.

Sub-agent boundary: Steps 1-3 are performed by the orchestrator (commands/tech-design.md) in the main context. Steps 4-7 are performed by a generation sub-agent (Task(subagent_type="general-purpose")) that reads references/generation-instructions.md, references/template.md, and references/checklist.md directly. The sub-agent operates in an isolated context and receives a structured prompt with all Step 1-3 outputs.

Step 1 -- Deep Scan Codebase

Before writing anything, perform a thorough scan of the current project to build deep technical understanding.

@../shared/project-context.md

Execute the full Project Context Protocol. Prefer its PC.0 fast path — resolve <sf_scripts> (see @../shared/scripts.md) and run python3 "<sf_scripts>/sf-scan.py" --root "<project_root>", which returns the languages, frameworks, DB/auth signals, test command, and the existing-doc inventory (including any upstream prd.md/srs.md with their declared IDs) in one pass — use its documents, document_index, frameworks, signals, and test fields directly. Fall back to the manual PC.1–PC.6 scan only if python3 is unavailable:

1. PC.1 Project Discovery — project structure, README, existing docs
2. PC.2 Tech Stack Detection — language, framework, database, test framework, CI/CD
3. PC.3 Project Profile — Web API, CLI, Frontend, AI Agent, etc.
4. PC.4 Architecture Awareness — module boundaries, architectural pattern (MVC, layered, clean, microservices), dependency direction, key abstractions (interfaces, traits)
5. PC.5 Existing Test Infrastructure — test framework, coverage assessment

Additionally: 6. Identify infrastructure patterns by scanning for Kubernetes manifests, Terraform files, CloudFormation templates, or serverless configuration. 7. Scan for ADRs (Architecture Decision Records) in docs/adr/ or docs/decisions/ — existing decisions constrain the design.

This scanning ensures the generated design document is grounded in the real architecture. The detected project profile and architecture pattern inform which design sections need the most depth (e.g., a microservices project needs API contract design; a monolith needs module boundary design).

Step 1.5 -- Doc-First Discipline (Mandatory)

Before locating upstream documents or writing any design content, the doc-first discipline applies. Read the existing documentation, identify what already covers the architecture, components, decisions, or interfaces, and decide for each section whether to REUSE (reference existing), EXTEND (edit existing in place), or NEW (genuinely missing). The default for any topic that already has coverage in an existing tech-design or ADR is to extend in place — never to create parallel tech-design-v2.md files, never to append ## Update blocks, never to leave superseded ADRs strikethrough'd inside the active doc.

The full discipline, the four rules, the pre-generation checklist, and the anti-patterns to avoid:

@../shared/doc-first.md

You MUST run the pre-generation checklist (the five questions) from doc-first.md before proceeding to Step 2. If existing docs already cover any of the topics this tech design will discuss, you must:

1. List the existing files and sections that overlap (with file:line references) — this includes ADRs in docs/adr/ or docs/decisions/
2. Decide REUSE / EXTEND / NEW for each section (architecture, API design, data model, security, deployment)
3. Bias toward EXTEND — opening the existing tech-design and modifying it — over NEW
4. Respect ADR immutability. ADRs are decision records: an old decision is not deleted when superseded. Instead, the old ADR is marked Status: Superseded by ADR-NNN and a new ADR is added that references it. This is the only exception to the no-strikethrough rule, because ADRs are explicitly historical artifacts.
5. Identify which existing component names, interface contracts, and module boundaries must remain stable to preserve compatibility with code and downstream specs
6. Surface any downstream documents (feature specs, test-cases, README) this generation will affect

If the project shows signs of doc drift (multiple tech-design-*.md files, contradictory architecture diagrams in different docs, obvious duplication), warn the user before proceeding and recommend they run /spec-forge:analyze or /spec-forge:propagate first.

If a usable existing tech-design already covers most of what the user is asking for, the right action is edit it in place, not generate a new file.

---

Step 2 -- Find Upstream Documents

Search for matching upstream documents that feed into this design. Determine the operating mode:

• Upstream mode: PRD and/or SRS found → design will trace to formal requirement IDs. If BOTH an idea draft and a PRD exist, the PRD takes precedence as the source of truth (it is a formalized version of the idea). Read the idea draft only for supplementary context that the PRD may not cover.
• Idea-first mode: Idea draft found at ideas/<feature-name>/draft.md, no PRD/SRS → §3.5 User Scenarios, §3.6 Acceptance Criteria, and §3.7 Success Metrics are derived from the idea draft's problem statement, MVP scope, and demand validation results. If the idea draft scenarios are vague or generic, ask clarifying questions to make them concrete enough for §3.5.
• Standalone mode: No upstream documents → these sections are populated from user clarification answers

Upstream mode search: The sf-scan.py inventory from Step 1 already reports any upstream docs/*/prd.md and docs/*/srs.md (under document_index) with the requirement IDs each declares — use it instead of re-scanning for these files by hand. Then:

1. Read all found PRD documents to extract product goals, user stories, and success metrics.
2. Read all found SRS documents to extract functional requirements (FR-XXX-NNN), non-functional requirements (NFR-XXX-NNN), data models, and interface definitions.
3. Summarize upstream context including the requirement IDs that this design must address.

If no PRD/SRS found, check for idea draft at ideas/<feature-name>/draft.md.

Step 3 -- Clarify Only What You Cannot Infer

First infer every answer you can from the upstream PRD/SRS, the idea draft, the scanned project context, and any existing tech-design or ADRs — and state those inferences as explicit assumptions the user can correct. Then ask the user only the questions whose answers materially change the design and cannot be inferred. Do not march through a fixed questionnaire or re-ask anything the upstream docs or scan already answer; a strong scan often makes most questions unnecessary. Typical areas that genuinely need input when they cannot be inferred:

• Architecture preference and any mandated patterns to follow.
• Technical constraints or forbidden technology choices.
• Performance targets for latency, throughput, and scalability.
• Data strategy including new databases, tables, or migration needs.
• Integration points with external services, APIs, or message queues.
• Security requirements including authentication method and data sensitivity.
• Deployment strategy including cloud provider, orchestration, and environment topology.
• Timeline constraints that might affect technical decisions.
• Agent consumers: Are there programmatic consumers for this system (API clients, automation tools, other services integrating programmatically)? If yes, describe their integration patterns (REST API, async events, webhooks, SDK) and key workflows. Agent-facing systems need explicit API contracts, machine-verifiable response schemas, and structured error codes designed for programmatic consumption — not just human-friendly error messages.

Where the idea draft or upstream docs leave a core design section (e.g., §3.5 User Scenarios) vague or generic, ask the one focused question that makes it concrete — generalizing the idea-first rule above. But a section you can populate confidently from the scan and upstream docs needs no question at all; proceed to generation once the material gaps are closed rather than gathering answers you already have.

Step 4 -- Generate Design

Using the template at references/template.md, generate the complete Technical Design Document. Key requirements for this step:

• Present genuine alternative solutions with a structured comparison matrix wherever a real design decision exists; where only one approach is viable, state that explicitly ("no meaningful alternative — rationale: …") rather than inventing a straw-man second option.
• Recommend one solution and provide explicit rationale for the decision.
• Use Mermaid syntax for all diagrams following the C4 model levels.
• Design APIs with complete endpoint specifications, request/response schemas, and error codes.
• Define database schemas with ER diagrams, index strategies, and migration plans.
• Address security as a first-class concern with authentication, authorization, encryption, and audit logging.
• Set specific, measurable performance targets with caching and optimization strategies.
• Plan observability with logging, monitoring, and alerting.
• Define deployment strategy with environments, CI/CD pipeline, and rollback procedures.

No forcing irrelevant sections — adapt to the actual project profile. Populate only the sections this project's profile actually calls for, and omit the ones it does not rather than filling them with placeholder content. A stateless CLI or a pure library has no database design, no circuit-breaker/retry policy for external dependencies, and no blue-green deployment or rollback plan — mark those sections not applicable with a one-line reason instead of manufacturing filler. (This governs what you fill in; do not delete sections from the template — it stays complete.)

Step 5 -- Traceability

If upstream documents (PRD and SRS) were found:

• Map each SRS functional requirement to the technical components that implement it.
• Map each SRS non-functional requirement to the architecture decisions that satisfy it.
• Verify that all FR and NFR items from the SRS are addressed somewhere in the design.
• Document any requirements that are intentionally deferred with justification.

Let the script layer do the coverage math: after the design is drafted, run

python3 "<sf_scripts>/sf-trace.py" matrix --upstream "<srs.md>" --downstream "<tech-design.md>"

and use its uncovered_upstream (SRS FR/NFR IDs with no design reference — coverage gaps to close) and orphan_downstream_refs (design references to requirement IDs that do not exist — dangling links to fix). The script computes the coverage; you decide whether each uncovered requirement is intentionally deferred or a real omission. Fall back to building the matrix by hand if the script is unavailable.

This traceability ensures no requirements fall through the cracks between specification and design.

Step 6 -- Quality Check

Run the structural gate with the script, then apply judgement with the checklist:

python3 "<sf_scripts>/sf-verify-doc.py" "<tech-design.md>" --strict

This deterministically confirms the title, recommended sections, ID format/uniqueness, and the absence of leftover template placeholders. Fix everything it flags. Then load references/checklist.md and evaluate the items the script cannot judge — architecture trade-off soundness, decision rationale, whether each performance target has a real threshold, whether the design actually addresses every requirement. Validate both the completed tech-design document AND all generated feature specs in docs/features/. Summarize the checklist results so the user can see what passed and whether any items were intentionally skipped with justification. The document is only written to disk once the structural gate passes and the judgement items hold. (If python3 is unavailable, run every checklist item by hand.)

Step 7 -- Feature Spec Generation

After the main Technical Design Document passes the quality check, automatically generate individual feature specs for each component identified in Section 8 (Detailed Design). The tech-design produces both the architecture document and the implementation-ready feature specs in a single pass.

7.1 Identify Components

Extract all components from the Component Overview table in §8.1. Each row in the table becomes one feature spec file.

7.2 Generate Feature Specs

For each component, create a feature spec at docs/features/{component-name}.md using the template below. The feature spec contains the implementation-level detail that was traditionally written in §8 of the tech-design — method signatures, logic steps, field mappings, state machines, and error handling specifics.

Feature Spec Template:

No numbering: Feature spec titles and filenames use the component slug only (e.g., auth-service.md, NOT 01-auth-service.md or F-01 Auth Service). Do NOT prefix titles with numbers, IDs, or order indicators. Execution order is defined exclusively in docs/features/overview.md.

# {Component Name}

> Feature spec for code-forge implementation planning.
> Source: extracted from docs/{project}/tech-design.md §8
> Created: {date}

| Field | Value |
|-------|-------|
| Component | {component-slug} (same as filename without `.md`) |
| Priority | {P0 / P1 / P2, derived from requirement priorities} |
| SRS Refs | {mapped from traceability matrix, e.g., FR-XXX-001..005} |
| Tech Design | §8.1 — {component row reference} |
| Depends On | {component slugs this depends on, or "—" if none} |
| Blocks | {component slugs this blocks, or "—" if none} |

## Purpose

{One paragraph describing what this component does and why it exists. Derived from the Component Overview table.}

## Scope

**Included:**
- {responsibility 1}
- {responsibility 2}

**Excluded:**
- {explicitly out of scope}

## Core Responsibilities

1. **{Responsibility name}** — {brief description}
2. ...

## Interfaces

### Inputs
- **{input name}** ({source}) — {description}

### Outputs
- **{output name}** ({destination}) — {description}

### Dependencies
- **{module/system name}** — {what it provides}

## Data Flow

{Mermaid diagram if 3+ steps}

## Key Behaviors

{Implementation-level detail: method signatures, logic steps, field mapping tables, state machines, algorithms. This is where the depth of the traditional §8 detailed design lives.}

### {Behavior 1}
{Detailed description with logic steps, code signatures, data structure transformations}

### {Behavior 2}
{Detailed description}

## Constraints

- **{constraint type}**: {description}

## Acceptance Criteria

[Map back to AC-IDs from tech-design §3.6 where applicable. Add component-specific criteria not covered at the feature level.]

> **This table is the acceptance standard.** When no SRS or test-cases document exists, `code-forge:review`'s Acceptance Gate reconciles every **P0/P1** row here against a named passing test and hard-blocks merge on any P0 row with no passing test. Therefore every row must be (a) a single mechanically-testable condition with a concrete Expected Result, (b) tagged with a Priority, and (c) the set must cover — for every P0 behavior — not just the happy path but its boundary, error, and negative conditions. A happy-path-only AC set is the #1 cause of "passes review but is only a demo" and is rejected by the Step 6 quality check.

| AC-ID | Priority | Criterion | Expected Result | Verification Method |
|-------|----------|-----------|-----------------|---------------------|
| AC-{nnn} | P0 | {Given … When … — a single testable happy-path condition} | {Exact observable outcome: return value / status code / persisted state} | {Unit / Integration / E2E — name what to call and what to assert} |
| AC-{nnn} | P0 | {boundary or error condition for the SAME behavior — invalid input, limit exceeded, missing precondition} | {Specific rejection / error code / message — never "fails"} | {…} |
| AC-{nnn} | P1 | {negative — what must NOT happen for this component} | {Behavior that should NOT occur is absent} | {…} |

## Error Handling

{Component-specific error handling: which exceptions, error codes, sanitization rules}

## File Structure

{src-root}/ └── {module-path}/ ├── {component-name}.{ext} # Main implementation ├── {component-name}.test.{ext} # Unit tests (co-located) └── {sub-module}/ └── {file}.{ext} # Sub-module files if applicable

{Use the actual project source root (e.g., `src/`, `lib/`, `app/`), the actual file extension, and the actual module path. Do NOT write a placeholder — look at the project structure and derive the real path.}

## Test Module

**Test file**: `{exact/path/to/component-name.test.ext}`

**Test scope**:
- **Unit**: {Specific functions/methods to unit test, e.g., `processPayment()`, `validateCard()`}
- **Integration**: {Integration points to test: API endpoints, DB operations, external services}
- **Fixtures / Mocks**: {What to mock or set up, e.g., "mock Stripe client", "seed user with active subscription"}

7.3 Generate Overview

Create or update docs/features/overview.md:

# Feature Overview

> Auto-generated from tech-design. See docs/{project}/tech-design.md for architecture context.
> Updated: {date}

## Features

| # | Feature | Description | Dependencies | Priority | Status |
|---|---------|-------------|--------------|----------|--------|
| 1 | [{name}](./{name}.md) | {one-line} | {deps or "—"} | {P0/P1/P2} | draft |
| 2 | [{name}](./{name}.md) | {one-line} | {deps or "—"} | {P0/P1/P2} | draft |

> The `#` column defines the canonical execution order based on the dependency graph. Features with no dependencies come first. This is the ONLY place where feature ordering is assigned.

## Execution Order

{Same order as the `#` column above, with dependency rationale.}

1. **{feature-name}** — {reason, e.g., "no dependencies"}
2. **{feature-name}** — {reason, e.g., "depends on auth-service"}

## Architecture Reference

For system-level concerns (solution design, API specifications, security, performance, deployment), see:
- **Tech Design**: `docs/{project}/tech-design.md`

7.4 Dependency Resolution

When filling Depends On / Blocks fields and building the execution order in overview.md:

1. Parse component dependencies from the Component Overview table and from component interaction diagrams
2. Use each component's slug (its filename without .md) as the stable cross-reference identifier. Execution order is defined exclusively in the # column of the Features table in docs/features/overview.md.
3. Cross-reference with SRS requirement IDs from the Traceability Matrix (§18, Appendix D — Requirements Traceability) to fill SRS Refs (leave empty if no upstream SRS exists)
4. Derive priority from the requirement priorities (P0 requirements → P0 feature)

7.5 Content Depth Guidance

Each feature spec should contain enough detail that an engineer (or code-forge:plan) can implement without referencing back to the main tech-design. Specifically:

• Method signatures with parameter types and return types
• Step-by-step logic for non-trivial methods (numbered steps with conditional branches)
• Field mapping tables for data transformation operations
• State transitions specific to this component (if applicable)
• Default values, validation rules, and constants
• Error conditions and what exception/error to raise for each

Do NOT include system-level concerns that belong in the main tech-design (API endpoint specifications, database schema, security design, deployment strategy, performance targets). Feature specs focus on component internals.

7.6 Verify Feature ↔ Component ↔ Overview Membership

After the feature specs and overview.md are written, let the script cross-check the bookkeeping. Fast path (preferred): resolve <sf_scripts> and run

python3 "<sf_scripts>/sf-trace.py" chain --tech-design "<tech-design.md>" --features-dir "docs/features" --overview "docs/features/overview.md"

Use its output to catch the two most common bookkeeping gaps: feature specs under docs/features/ that are not mentioned in the tech-design, and §8.1 Component Overview slugs that have no feature file. Reconcile every mismatch it reports — add the missing feature spec, or correct the §8.1 row. Fallback: if python3 is unavailable or the script is not found, cross-check the §8.1 rows against the docs/features/ files by hand.

Architecture Diagram Standards -- C4 Model

All architecture diagrams follow the C4 model, which provides four levels of abstraction for communicating software architecture.

Level 1 -- Context Diagram. Shows the system as a single box surrounded by the people who use it and the external systems it interacts with. This is the highest-level view and should be understandable by non-technical stakeholders. Use a Mermaid flowchart TB diagram with clear labels for each actor and system.

Level 2 -- Container Diagram. Zooms into the system box and shows the high-level technology building blocks: web applications, APIs, databases, message queues, file storage, and other containers. Each container is labeled with its technology choice. Use a Mermaid flowchart TB diagram with subgraphs to group related containers.

Level 3 -- Component Diagram. Zooms into a single container and shows the major structural components inside it: controllers, services, repositories, domain models, and their relationships. Use a Mermaid flowchart LR or flowchart TB diagram.

Level 4 -- Code Diagram. Typically not included in the design document itself but may be referenced for particularly complex algorithms or data structures. When needed, use Mermaid classDiagram notation.

All Mermaid code blocks must use the ```mermaid fence so they render correctly in GitHub, GitLab, and most Markdown viewers. Every diagram must have a descriptive title, and every node must have a human-readable label.

Technology Stack Decision

Every technical design must begin with explicit technology choices. The Technology Stack section requires a table listing every layer of the system (programming language, runtime, framework, ORM, database, cache, message queue, frontend framework, testing framework, build tool, containerization) with the specific version and a rationale explaining why it was chosen. Rationales must be project-specific -- "it's popular" is not sufficient; "Go 1.22 was chosen because the team has 3 years of Go experience and its concurrency model fits our real-time event processing needs" is.

Naming Conventions

Inconsistent naming across code, APIs, and databases is one of the most common sources of confusion in engineering teams. The design document must define naming conventions at three levels:

Code Naming. Specify conventions for files/modules, classes/structs, interfaces/traits, functions/methods, variables, constants, enums, and test files. Follow the chosen language ecosystem's conventions (e.g., camelCase for JavaScript, snake_case for Python/Rust, PascalCase for Go exported names).

API Naming. Specify conventions for URL path segments (kebab-case plural nouns recommended for REST), query parameters, request/response body fields, custom headers, and error codes. The request and response field conventions must match.

Database Naming. Specify conventions for table names (snake_case plural recommended), column names, primary/foreign keys, index names, constraint names, and enum types. Use a consistent pattern like idx_<table>_<columns> for indexes and fk_<table>_<referenced_table> for foreign keys.

Parameter Validation & Input Parsing

Every parameter that crosses a trust boundary must have explicit validation rules. The design document must include a Validation Rules Matrix table where each row defines: parameter name, type, required/optional, minimum value, maximum value, pattern/format (regex or standard like RFC 5322 for email), default value, sanitization strategy, and the specific error message returned on failure.

Beyond the matrix, the document must define type coercion rules (how strings are parsed to integers, booleans, dates, enums), input sanitization strategy (HTML/XSS, SQL injection, path traversal, command injection, JSON depth limits), and the distinction between null, missing, and empty values.

Boundary Values & Edge Cases

The design must document every system limit and what happens when it is exceeded. This includes: request body size, string field lengths, array sizes, concurrent connections, rate limits, file upload sizes, JSON nesting depth, pagination result caps, and bulk operation batch sizes. For each limit, specify the exact number, the behavior when exceeded (specific HTTP error code), and the rationale.

Edge cases must be documented in a table covering at minimum: empty string input, unicode/emoji handling, idempotent duplicate requests, behavior during database migration, concurrent update conflicts, referential integrity on delete, timezone handling, numeric overflow, null vs zero semantics, and long-running request timeouts.

Business Logic Rules

All business rules must be documented precisely enough that an engineer can implement them without ambiguity.

State Machines. If entities have lifecycle states, define the state machine using a Mermaid stateDiagram-v2 diagram. For every transition, document: from state, to state, trigger, guard conditions (what must be true), and side effects (what happens as a result).

Computation Rules. For every calculation or derived value, document: a rule ID, description, formula/logic, inputs, output type, numeric precision and rounding strategy, and a worked example with real numbers.

Conditional Logic. For complex branching behavior, document each condition with what happens when true and when false, plus any relevant notes about configurability or thresholds.

Error Handling Strategy

Define a comprehensive error taxonomy covering every error category the system can produce. For each category, specify: HTTP status code, error code pattern, whether the client should retry, and the user-facing message. Additionally, define retry and circuit breaker configuration for every external dependency: retry count, backoff strategy, circuit breaker threshold, timeout, and fallback behavior.

API Design Conventions

The design document must specify API conventions appropriate to the chosen protocol.

RESTful APIs. Follow resource-oriented design. Endpoints use plural nouns (e.g., /api/v1/users, /api/v1/orders/{orderId}/items). Use standard HTTP methods: GET for retrieval, POST for creation, PUT/PATCH for updates, DELETE for removal. Version the API in the URL path (e.g., /api/v1/). Define standard error response shapes with error codes, messages, and request IDs.

GraphQL APIs. Define the schema with queries, mutations, and subscriptions. Document resolver responsibilities and data loader patterns for N+1 prevention. Specify error handling conventions within the GraphQL response structure.

gRPC APIs. Define service and message protobuf schemas. Document streaming patterns (unary, server-streaming, client-streaming, bidirectional). Specify deadline and retry policies.

Regardless of protocol, every API specification must include: endpoint or operation name, authentication requirements, request schema with field types and validation rules, response schema with example payloads, and a complete error code table.

Database Design Standards

Database design sections must include the following elements.

Schema Design. Define every table or collection with its columns, data types, constraints (primary key, foreign key, unique, not null, defaults), and purpose. Use a table format for clarity.

ER Diagram. Use Mermaid erDiagram syntax to visualize entity relationships. Label every relationship with its cardinality and nature.

Index Strategy. For each table, define the indexes needed: primary indexes, unique indexes, composite indexes for common query patterns, and partial or conditional indexes where appropriate. Document the rationale for each index in terms of the queries it supports.

Migration Strategy. Plan how schema changes will be applied: migration tool selection, forward and backward compatibility, zero-downtime migration techniques (expand-contract pattern), and data backfill procedures.

Solution Comparison Methodology

Every design document must evaluate genuine alternative solutions wherever a real design decision exists. Where only one approach is viable, record that explicitly with a short rationale ("no meaningful alternative — rationale: …") instead of manufacturing a straw-man second option. When real alternatives do exist, the comparison follows a structured methodology.

1. Describe each solution with enough detail that a reader can understand its architecture, key technology choices, and implementation approach.
2. List pros and cons for each solution, organized by technical merit, operational impact, and business alignment.
3. Build a comparison matrix evaluating all solutions against consistent criteria: implementation complexity, performance characteristics, scalability ceiling, operational cost, team expertise alignment, time to delivery, and risk profile. Use a rating system (e.g., High / Medium / Low or numeric scores) for each criterion.
4. Document the decision with explicit rationale explaining why the recommended solution was chosen and why the alternatives were rejected.

Security Design Principles

Security must be treated as a first-class architectural concern, not a bolt-on afterthought.

Authentication. Specify the authentication mechanism (OAuth 2.0, JWT, API keys, mTLS, SAML) and document the token lifecycle including issuance, validation, refresh, and revocation.

Authorization. Define the authorization model (RBAC, ABAC, or hybrid). Document roles, permissions, and access control rules. Specify how authorization is enforced at the API gateway, service, and data layers.

Data Encryption. Specify encryption at rest (algorithm, key management, rotation policy) and encryption in transit (TLS version, certificate management). Document handling of sensitive fields (PII, payment data) including tokenization or field-level encryption where applicable.

Audit Logging. Define what events are logged (authentication attempts, data access, configuration changes), the log format, retention policy, and how audit logs are protected from tampering.

Performance Design

Performance sections must be specific and measurable, not aspirational.

Target Metrics. Define concrete targets: API response time at p50, p95, and p99 percentiles; throughput in requests per second; error rate thresholds; and resource utilization limits.

Caching Strategy. Specify what is cached (query results, computed values, static assets), where caching happens (browser, CDN, application layer, database query cache), cache invalidation strategy (TTL, event-driven, manual), and cache warming procedures.

Optimization Plan. Document specific optimization techniques: query optimization, connection pooling, lazy loading, pagination strategies, batch processing, and async processing for non-critical paths.

Observability

The design must plan for production observability from the start.

Logging. Define log levels, structured log format (JSON recommended), correlation ID propagation, and log aggregation destination. Specify what must be logged at each level.

Monitoring and Metrics. Define the key metrics to track: RED metrics (Rate, Errors, Duration) for services, USE metrics (Utilization, Saturation, Errors) for resources, and business metrics. Specify the monitoring tool and dashboard requirements.

Alerting. Define alerting rules with conditions, severity levels, notification channels, and escalation procedures. Include runbook references for each alert.

Deployment Strategy

The deployment section ensures the design is production-ready.

Environments. Define the environment topology (development, staging, production) with purpose, configuration differences, and access controls for each.

CI/CD Pipeline. Describe the pipeline stages: build, unit test, integration test, security scan, artifact creation, deployment, smoke test, and promotion. Specify any gates or approval steps.

Rollback Strategy. Define how to roll back a failed deployment: blue-green switching, canary percentage reduction, feature flag disabling, or database migration reversal. Specify the rollback decision criteria and the maximum time to rollback.

Reference Files

This skill relies on two reference files stored alongside it.

• references/template.md -- The full Technical Design Document template with placeholder text for every section. The generated document is built by filling in this template. Note that §8 (Detailed Design) is an overview only — the detailed per-component content goes into feature specs.
• references/checklist.md -- A quality checklist organized into four categories (Completeness, Quality, Consistency, Format) plus feature spec validation. The checklist is used during Step 6 to validate the finished document.

Always read both files before generating a document so that any updates to the template or checklist are picked up automatically.

Output Location

The tech-design skill produces two types of output:

1. Main Technical Design Document:

docs/<feature-name>/tech-design.md

where <feature-name> is a lowercase, hyphen-separated slug derived from the feature name (for example, docs/user-authentication/tech-design.md or docs/payment-processing/tech-design.md). If the docs/<feature-name>/ directory does not exist, create it. If a file with the same name already exists, confirm with the user before overwriting.

2. Feature Specs (auto-generated from §8 Detailed Design):

docs/features/{component-name}.md     — one per component
docs/features/overview.md             — feature index with dependencies and execution order

Feature specs contain the implementation-level detail (method signatures, logic steps, field mappings) that code-forge:plan consumes directly. Upstream PRD/SRS discovery that grounds the design in established requirements is handled once, in Step 2 (via the sf-scan.py inventory), and feeds Step 5 traceability.