tech-design

name

tech-design

description

Generate a technical design document as a markdown file, given a PRD (or PRD-shaped description). Use this skill whenever the user asks for a tech design, technical design doc, architecture doc, implementation design, engineering design, RFC, or wants to "design the implementation of" / "figure out how we'd build" / "spec out the architecture for" a feature. Trigger on phrases like "write a tech design for the PRD at …", "design the implementation of X", "how would we architect this", "turn this PRD into a design". This is the step *after* a PRD — it converts product intent into engineering specifics (components with real file paths, data model, API contracts, existing patterns to reuse). It is *not* the right fit for product/requirements docs (use `prd-generator`) or for breaking work into tasks (use `task-dag`).

Tech Design Generator

Produce a concrete technical design document as a markdown file. A good tech design answers a single question: how will we actually build this? — with enough specificity that an engineer reading it cold can point at the real components, the real file paths, the real function signatures, the real data model, and the existing code they should extend. The design doc is the bridge between product intent (PRD) and decomposed work (task DAG); everything downstream of it depends on this document being concrete.

When this skill triggers

Use this skill for any request that boils down to "design how we'd build this." Common phrasings:

• "Write a tech design for the PRD at plans/foo/prd.md"
• "Design the implementation of "
• "How would we architect this?"
• "Spec out the architecture for the new "
• "I need an engineering design doc for…"
• "Turn this PRD into a design"

If the user is asking for a product doc (problem, users, goals), defer to prd-generator. If they're asking to decompose an existing design into tasks, defer to task-dag.

Workflow

1. Read the inputs

Locate and read the source PRD. If the user gave a path (plans/<slug>/prd.md or otherwise), read that file. If they pasted PRD content inline, work from that. If they gestured at "the PRD we just wrote," look in plans/ for the most recent PRD or ask which one.

Also pull in any explicit constraints from the request itself — language, framework, deployment target, "must integrate with X." Those override defaults.

2. Recall from Hindsight memory (best-effort)

If Hindsight memory tools are available in this session, query them before doing heavy exploration. Prior runs of this skill may have recorded codebase conventions worth knowing.

• Call mcp__plugin_hindsight-memory_hindsight__agent_knowledge_recall with a plain-language query describing the design problem ("auth migration patterns for this repo", "conventions for adding a new HTTP endpoint").
• If a relevant page comes back, read it via mcp__plugin_hindsight-memory_hindsight__agent_knowledge_get_page and treat it as ground truth about prior decisions in this repo.

Recall is best-effort. If Hindsight isn't available, or returns nothing useful, proceed normally — never block on memory.

3. Explore the codebase (when one exists)

If the working directory is a real repository (not greenfield), explore it before writing. The whole point of the design doc is to anchor choices to real code, so an engineer downstream can extend an existing pattern rather than invent one. At minimum, look for:

• Data layer — ORM, migrations directory, model files
• API / routing layer — handlers, controllers, route definitions
• Auth / sessions — middleware, token handling, permission checks
• Test conventions — where unit and integration tests live, how they're run
• Conventions docs — CLAUDE.md, README.md, CONTRIBUTING.md

Use the Explore agent or Grep for targeted searches. The bar to clear: be able to write phrases like "extends the pattern in src/handlers/invitations.ts:34" with real paths — not "add a new handler somewhere."

For greenfield projects, skip this step but be explicit in the design doc about the scaffolding you're proposing and why.

4. Ask focused questions only when needed

If the PRD leaves a high-impact technical decision genuinely open — "is this a new service or part of the monolith?", "do we need a new database, or extend the existing one?", "is real-time required or is polling acceptable?" — ask three or four focused questions before drafting. Keep it short. Tell the user upfront: "I want to nail down a few tech-level decisions before I draft the design."

Skip the interview when the PRD plus the codebase make the answers obvious. A design generated from rich context is more useful than one that took ten back-and-forth questions.

5. Confirm the output path

Default to plans/<slug>/design.md, where <slug> is the same kebab-case slug used by the PRD (derive it from the PRD's filename or feature name). If the PRD is at plans/team-invitations/prd.md, the design goes to plans/team-invitations/design.md — that way task-dag and task-specs can hang off the same directory. Honor any explicit path the user provides.

6. Write the design doc

Use the default structure below unless the context strongly suggests a different shape. Adapt thoughtfully — don't pad sections with nothing meaningful to say, and don't drop sections just because they'd take effort to fill.

Default tech design structure

# <Feature / Component Name> — Technical Design

**Author:** <if known, else omit>
**Status:** Draft
**Last updated:** <YYYY-MM-DD>
**Related PRD:** <relative path to prd.md>

## Summary
2–4 sentences. What we're building, the chosen approach in a single phrase, and the most important constraint or tradeoff. A reader should be able to stop here and know roughly what changes.

## Architecture overview
Short prose description of the chosen approach plus a diagram (Mermaid or ASCII) showing the major pieces and how data flows. Keep the diagram readable — five to ten nodes is usually enough.

## Components / modules
Enumerate every new and modified module. For each:
- **Path** — real file path (e.g., `src/services/invitations.ts`), marked `(new)` or `(modify)`
- **Responsibility** — one sentence
- **Key public surface** — exported functions, types, classes, with signatures (not just names)

## Data model & migrations
If the design touches persistence: concrete schema. Tables/collections, columns with types, indexes, constraints. Migration filename(s) and any backfill plan. If there are genuinely no data changes, say "No data model changes" and move on.

## APIs / contracts
Every new or changed external surface — HTTP endpoint, RPC method, queue message, event payload, CLI command. For each, show the concrete contract: method + path, request shape, response shape, error cases. Use code blocks with type definitions where they help.

## Existing patterns to reuse
Bulleted list. Each item: file path + one-sentence "why this fits." Anything the design borrows from elsewhere in the codebase — utilities, base classes, middleware, test helpers — belongs here so downstream tasks know what to import instead of reinventing.

## Tech choices and tradeoffs
The decisions worth defending. For each: what was chosen, what was the leading alternative, one sentence on why. Three to six entries is usually right. Skip choices where there's only one sane option.

## Open technical questions
Things you don't know yet. Phrase each as a real question with a proposed path to resolution. Owning open questions is more credible than papering over them.

## Out of scope
Tech-level scope-outs — what this design explicitly does *not* address. Distinct from the PRD's non-goals; this is engineering-level (e.g., "no schema changes to the `users` table", "no migration of legacy session tokens — handled separately").

## Risks and mitigations
What could go wrong from an engineering standpoint, and what we'd do about it. Cover correctness, performance, security, operability where relevant.

## Rollout plan
Only when launch is non-trivial. Flag gating, phased rollout, dual-write windows, rollback story. Drop if not relevant.

## Appendix
Anything supporting the design that doesn't belong in the main flow: prior art, links to related code, raw research, glossary.

Adapting the structure

Sections to add when the context warrants:

• Performance budget — for latency- or throughput-critical features (target p50/p99, expected QPS)
• Security model — when threat surface is non-trivial (auth flows, untrusted input, PII)
• Observability — what we'll log/meter/trace and dashboards/alerts to add
• Migration plan — separate from rollout when migrating existing data or systems

Sections to omit when they'd be empty:

• Data model & migrations — drop if there are genuinely none
• APIs / contracts — drop if no external surface changes
• Rollout plan — drop for low-risk additive features
• Appendix — drop if there's nothing to put there

7. Persist learnings to Hindsight (best-effort)

If Hindsight memory tools are available and the exploration uncovered a reusable convention worth remembering across runs — e.g., "this repo uses Drizzle ORM, migrations live in db/migrations/, every model has a sibling <model>.test.ts" — write or update a page. Use mcp__plugin_hindsight-memory_hindsight__agent_knowledge_create_page (or _update_page if a similar page exists; check with _list_pages first).

Keep pages tight: one convention per page, with file path examples. Do not dump design-specific details into Hindsight (those belong in design.md). Only persist patterns that will help future runs in this repo.

8. Surface the file

Tell the user where it lives in one sentence — "Wrote the design doc to plans/team-invitations/design.md." — plus a brief summary of the chosen approach (one or two sentences) and any notable judgment calls flagged so the user can correct them before they ripple downstream into task-dag and task-specs.

Quality bar

A tech design is a thinking artifact that downstream skills and downstream coding agents will execute against. Concreteness is non-negotiable. Aim for a document that:

• Names real file paths, not "the auth module"
• Shows real function signatures and type definitions, not "an endpoint that handles invitations"
• Points to existing patterns to reuse, with paths
• Distinguishes new code from modified code
• Surfaces real open questions rather than burying them

Things to avoid:

• Architecture prose without a diagram or a component list
• Vague component names ("the service layer") without file paths
• Pseudo-code that hides the hard decisions ("// handle auth here")
• Made-up library or function names — if you're not sure something exists, grep first or flag it as an assumption
• Re-stating the PRD instead of adding engineering specifics — the design doc earns its keep by being concrete where the PRD is intentionally not
• Implementation completeness — the design names interfaces and files, it doesn't write the implementation (that's downstream in task-specs and the coding agents)

When you draft, picture the downstream task-dag skill reading this. If a section doesn't give that skill enough to decompose work, dig harder.