tercel/spec-forge/tech-design-generation

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:

1. Identify infrastructure patterns by scanning for Kubernetes manifests, Terraform files, CloudFormation templates, or serverless configuration.
2. 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:

• SRS-first mode (preferred): docs/<feature-name>/srs.md found → the SRS is the authoritative statement of what must be built, and this design answers how. Populate §3.5 User Scenarios from its functional requirement flows, §3.6 Acceptance Criteria from its FR acceptance criteria, §3.4 Scope from its §3.2 Scope Boundaries (carry the out-of-scope table through verbatim — an exclusion that silently disappears between the requirements and the design is how out-of-scope work gets built), and derive §3.7 Success Metrics from its NFR targets. If a PRD also exists, read it for the product intent behind the requirements, not to re-derive the requirements themselves.
• PRD-only mode: PRD found, no SRS → the design will trace to PRD-* capability IDs, which are coarser than FR-* requirements. Flag this to the user: a design built on capabilities rather than specified requirements is making implicit decisions about system behavior that nobody has agreed to. Recommend running /spec-forge:srs <feature-name> first.
• 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, and every inference is recorded as an explicit stated assumption.

Upstream 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 SRS documents to extract functional requirements (FR-XXX-NNN), non-functional requirements (NFR-XXX-NNN), input field rules, state machines, permission matrix, error catalogue, data models, and interface definitions. These are the constraints the design must satisfy, not suggestions.
2. Read all found PRD documents to extract product goals, capability priorities, and success metrics — the intent behind the requirements.
3. Summarize upstream context including every requirement ID this design must address.

Requirement coverage is bidirectional and checked. Every component in §8.1 names the FR-*/NFR-* requirements it satisfies, and every requirement in the SRS is satisfied by at least one component. Report any requirement you cannot place rather than silently dropping it — an unplaced requirement is either a gap in the design or a requirement that should be renegotiated, and both need to be visible. The SRS's error catalogue and state machines map directly onto the design's error handling and state management; if the design cannot express one of them, that is a finding, not a detail to smooth over.

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: