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 presents at least two alternative solutions, evaluates them against explicit criteria, 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 (generalist(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 (PC.1 through PC.6):

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 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:

1. Search for PRD files matching docs/*/prd.md related to the feature being designed. Read all found PRD documents to extract product goals, user stories, and success metrics.
2. Search for SRS files matching docs/*/srs.md related to the feature. 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 Questions

Present the user with targeted clarifying questions. These questions fill gaps that cannot be inferred from the codebase or upstream documents. Typical areas include:

• 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.

Do not proceed to generation until the user has answered enough questions to inform the core design sections.

Step 4 -- Generate Design

Using the template at references/template.md, generate the complete Technical Design Document. Follow the writing guidelines and standards defined in the reference files below. Key requirements for this step:

• Writing Guidelines: @./writing-guidelines.md

• Standards: @./standards.md

• Present at least two alternative solutions with a structured comparison matrix.

• 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.

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.

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

Step 6 -- Quality Check

Validate the completed tech-design document AND all generated feature specs in docs/features/ against every item in references/checklist.md. Fix any issues before presenting the final document to the user. Summarize the checklist results so the user can see what passed and whether any items were intentionally skipped with justification.

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.]

| AC-ID | Criterion | Verification Method |
|-------|-----------|---------------------|
| AC-{nnn} | {Specific, testable condition that must be true for this component to be done} | {Unit test / Integration test / Manual — be specific about what to call and what to assert} |

## 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 — individual feature specs must NOT contain order numbers or numeric IDs.

## 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 — do NOT assign numeric IDs, order prefixes, or sequence numbers to feature specs. 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.

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.

Automatic Upstream Document Scanning

Before generating any Technical Design Document, the skill automatically searches for upstream PRD and SRS documents to ensure the design is grounded in established requirements.

1. Search for PRD files using the pattern docs/*/prd.md. Read matching documents to extract product goals, user personas, feature requirements, and success metrics.
2. Search for SRS files using the pattern docs/*/srs.md. Read matching documents to extract functional requirements, non-functional requirements, data models, and interface specifications.
3. Cross-reference upstream IDs so that the design document can map components and decisions back to specific PRD and SRS requirement identifiers, maintaining full traceability across the documentation lifecycle.

This scanning phase feeds directly into Steps 2 and 5 of the workflow and ensures every generated design reflects the actual requirements rather than assumptions.