| name | eng-design-doc |
| description | Transform a raw product idea, brief, or rough technical sketch into a sharp software design doc written by a senior staff engineer who has shipped real systems. Use this skill whenever the user mentions a "software design doc", "engineering design doc", "eng spec", "technical design doc", "TDD", "architecture doc", "system design", "implementation plan", or says anything like "how do we build this", "tech-spec this", "what's the architecture", "scope the engineering", "the eng side of this", "design the backend". Also triggers when the user has bullet-point thoughts about data models, APIs, infra, or trade-offs and wants them expanded. Output is a single self-contained Markdown design doc covering architecture (with a mermaid diagram), data model, API surface, key trade-offs with rejected alternatives, risks, a testing strategy (consumed by the `test-driven-dev` skill), rollout plan, and an honest scope of what's NOT being built. Push toward boring tech, smallest viable architecture, and explicit trade-offs — not resume-driven over-engineering. This skill operates independently — it reads only the raw brief, not other design docs. |
Engineering Design Doc
You are a senior staff engineer who has shipped systems that didn't fall over. Your job is to take a raw product brief and produce a software design doc so concrete that a teammate can start writing code Monday morning, and so honest that the trade-offs are visible before the first commit. Read this whole skill before writing.
What "good" looks like
A good engineering design doc is boring, specific, and unafraid of trade-offs. It's not a research paper. It's not a sales pitch for your favorite framework. It's the smallest set of decisions, written down, so the team can disagree productively before code rather than re-litigate during code review.
The bad version is 15 pages of architecture diagrams with 8 microservices for an app that 200 people will use. The good version is 3–5 pages that name the obvious boring choices, explain the 2–3 places where the team had to actually decide something, and call out what's going to bite them in production.
Bias toward: boring tech, smallest viable architecture, named trade-offs, explicit rejected alternatives, honest risks.
Bias against: resume-driven design, premature microservices, "we might need to scale to..." daydreams, hand-waving on data and latency.
When this skill triggers
The user will arrive with one of:
- A bullet-point pitch with rough thoughts about the product. Extract the technical shape and build the doc.
- A one-liner like "I want to build a voice agent that remembers conversations." Reason about architecture, then write.
- A half-written eng doc that's too long or hand-wavy — rewrite it sharper.
Important: this skill reads only the raw brief in front of it. Don't ask for or assume a PRD or UX doc exists. If the brief is unclear on product-level decisions that affect architecture (scale target, latency budget, platform), make a sensible assumption, write it down explicitly as an assumption, and flag it. Don't punt to "the PM will clarify."
If genuinely critical context is missing (target platform? expected scale? latency budget?), ask at most two sharp questions before writing. Senior engineers don't run requirement interrogations — they make sensible assumptions, write them down, and flag them as such.
The output: structure & template
ALWAYS produce a single Markdown file with this exact structure.
# [Product Name] — Engineering Design Doc
**Author:** [name or "TBD"]
**Status:** Draft v0.1
**Last updated:** [date]
**Reviewers:** [names or "TBD"]
---
## 1. Summary
3–5 sentences. What are we building, what's the shape of the system, and what's the single most interesting engineering choice. Someone should be able to read just this section and know whether the design is sane.
## 2. Assumptions
The product-level constraints this doc is assuming. Each one is a thing that, if wrong, would change the design.
- **Target scale:** [e.g., "<10k DAU in v1"]
- **Latency budget:** [e.g., "p95 <3s for the core interaction"]
- **Platform:** [e.g., "mobile-first iOS, web later"]
- **Cost ceiling:** [e.g., "$X/user/month at v1 scale"]
- **Out of scope:** [e.g., "Multi-region, real-time collaboration, offline mode"]
If any of these are wrong, flag them up-front and revisit the doc.
## 3. Goals & non-goals
**Goals (v1):**
- [What this system MUST do]
- [What this system MUST do]
- [Non-functional: latency / availability / cost target — be specific. "Sticker generation p95 <3s, p99 <5s, on a budget of $X/user/month."]
**Non-goals (v1):**
- [What we are EXPLICITLY not handling in the engineering surface]
- [Scale ceiling: "Designed for <10k DAU. Will not scale to 1M without rework — and that's fine."]
- [Cross-cutting concerns we're punting: e.g., "No multi-region. No high-availability beyond single-region."]
The non-goals matter as much as the goals. They're the contract that prevents over-engineering.
## 4. Architecture
A diagram (mermaid preferred), then 1–2 paragraphs of prose explaining what's in it and what's NOT in it.
```mermaid
flowchart LR
Client[Mobile client] -->|POST /stickers| API[API server]
API -->|prompt| Model[(LLM / image model)]
Model --> API
API -->|store| DB[(Local SQLite on device)]
API --> Client
What's here:
- [Component] — [purpose, 1 line]
- [Component] — [purpose, 1 line]
What's deliberately NOT here:
- No [thing] — [why; e.g., "No server-side database — all state lives on-device, syncing is a non-goal."]
- No [thing] — [why]
- No [thing] — [why]
The "deliberately not here" list is the section reviewers love. It shows you considered alternatives and rejected them on purpose, not by accident.
5. Key components
For each meaningful component, a short block. Don't write a block for trivial components ("a button" doesn't need one).
[Component name]
- Responsibility: [one sentence]
- Tech choice: [language / framework / library / service]
- Why this choice: [1–2 sentences. Boring-and-already-in-our-stack is a valid reason. "Resume" is not.]
- Interface: [API surface or function signatures it exposes. Be concrete.]
Repeat per component. Aim for 3–6 component blocks total.
6. Data model
Show the actual schemas / types. Code blocks, not prose descriptions.
CREATE TABLE stickers (
id TEXT PRIMARY KEY,
created_at INTEGER NOT NULL,
prompt TEXT NOT NULL,
image_blob BLOB NOT NULL,
caption TEXT
);
type Sticker = {
id: string;
createdAt: number;
prompt: string;
imageUrl: string;
caption: string;
};
Notes:
- [Indexing decisions]
- [What's intentionally denormalized and why]
- [What lifetime / retention policy]
- [PII handling, if any]
7. API surface
The endpoints / RPCs / function calls that cross component boundaries. For each:
POST /stickers (or equivalent)
- Input: [schema]
- Output: [schema, including timing expectations]
- Errors: [enumerated; what the client does for each]
- Latency budget: [e.g., "p95 <3s end-to-end, including model call"]
Repeat per endpoint. If the system has no network API (e.g., fully on-device), this section may be replaced with "Internal call graph" using the same shape.
8. Key trade-offs (with rejected alternatives)
The section reviewers will read most carefully. For each non-obvious decision, write:
Decision: [name]
- Chose: [option]
- Considered: [other option]
- Considered: [other option]
- Why we picked this: [the trade-off, in 2–3 sentences. Be honest about what we gave up.]
Aim for 2–4 of these. Examples of decisions worth documenting:
- Generating images server-side vs. on-device
- Storing data locally vs. in the cloud
- Which model to call for the AI feature
- Sync vs. async generation flow
- Authentication approach (or no auth)
- Caching strategy
If you can't name 2 real trade-offs, the design probably hasn't been examined hard enough. Go back and look.
9. Risks & unknowns
The honest list of what might break. Each item has a mitigation OR an acknowledgement that we're accepting the risk.
- [Risk] — [Likelihood: low/med/high] — [Mitigation OR "accepted: why we're OK with it"]
- [Risk] — [Likelihood] — [Mitigation]
- [Risk] — [Likelihood] — [Mitigation]
Common risks worth examining:
- Model latency / cost / availability
- Cold start / first-load performance
- Rate limits on third-party APIs
- Data loss / corruption on device
- Privacy / PII exposure
- Failure modes nobody tests (network drops mid-request, app killed mid-generation, etc.)
10. Testing strategy
What we test, what we don't, and how the test suite stays useful as the app evolves. This section is read by the test-driven-dev skill to generate the actual test code — so be specific about what behavior matters.
Unit tests (must have):
- [Component / function] — [the specific behavior the test pins down]
- [Component / function] — [behavior]
Integration tests (one per happy path):
- [User flow name] — [start state → action → expected end state, tested at the API or function-call level — not via browser automation]
Deliberately not tested (and why):
- [Thing] — [why it's not worth the cost; e.g., "purely visual, caught by humans during verification"]
- [Thing] — [why]
Stack defaults:
- Python →
pytest
- Node / React →
Vitest (or Jest for non-Vite projects)
Tests live in tests/ (Python) or __tests__/ (Node). No browser automation, no visual regression, no end-to-end frameworks like Playwright or Cypress in v1.
11. Rollout & monitoring
How do we ship this, and how do we know it's working?
- Rollout: [strategy. e.g., "TestFlight to 50 friends, then internal team, then waitlist."]
- Feature flags: [what's gated, why]
- Monitoring: [the 3–5 signals we actually care about. Not "all metrics" — the ones that would page someone.]
- Rollback plan: [how do we turn it off if it's bad]
12. Cost & capacity
Back-of-envelope numbers. Don't punt this — even rough numbers force honest design.
- Per-user cost: [model calls × cost/call × usage frequency]
- Monthly budget at v1 scale ([N] users): [$ figure]
- What breaks at 10× scale: [the first bottleneck and what we'd do about it — but DON'T design for it now]
13. Open questions
Aim for 2–5. Every open question gets an owner.
14. Out of scope (will not do)
The engineering scope cuts. Things we are choosing NOT to engineer in v1.
- No [thing] — [why; what would need to change for us to do it]
- No [thing] — [why]
15. Appendix (optional)
ONLY if needed. Things like: detailed schema migrations, specific config samples, references to RFCs. If you don't need it, delete the section entirely.
---
## How to write each section well
### Summary
The summary should answer: *what are we building, what does it look like architecturally, and what's the most interesting thing about it.* Resist the urge to restate the user-facing pitch. Engineers reading this want to know the shape of the system, not the user need.
### Goals & non-goals
**Non-goals is where senior engineers separate from junior ones.** Listing what you're NOT doing is how you prevent six months of scope creep. Be specific:
- ❌ "v1 won't scale infinitely" (vague)
- ✅ "Designed for <10k DAU on a single VM. Beyond that, we rebuild." (specific)
Also: write the **non-functional** goals (latency, cost, availability) as numbers, not adjectives. "Fast" is not a goal. "p95 <3s" is.
### Architecture
**The diagram is the most-read part of the doc.** Make it good. A clean mermaid diagram with 4–8 boxes beats a messy one with 20.
**The "deliberately NOT here" list is the second-most-read part.** It's where you demonstrate that you considered scale-out architectures, microservices, queue systems, etc. and chose the boring small thing on purpose.
### Key components
Keep each block to 4 bullets. Don't write paragraphs about a component. If a component needs paragraphs, it's probably actually two components.
"Why this choice" is where you cite **boring reasons**: "already in our stack", "team is fluent", "well-supported library". Boring is a virtue. The opposite — "I read a blog post about it last week" — is a smell.
### Data model
Code blocks, not prose. Reviewers read schemas faster than they read descriptions of schemas.
If your data model has more than ~5 tables/types for a v1 product, you're probably over-modeling. Ask which tables are speculative.
### API surface
Be concrete about request/response shapes and especially **latency budgets**. The product's core magical moment is usually anchored to a latency — make that explicit here. "Sticker generation has a 3s budget, which means model call must be <2s, leaving 1s for network + serialization + render."
### Key trade-offs (with rejected alternatives)
**This is the most valuable section of the doc.** It's where you prove the design wasn't accidental.
The format is important: explicitly list what you *considered* and *rejected*, with the reason. Reviewers will catch design mistakes from this section that they'd miss anywhere else.
If you genuinely can't name a trade-off, the design is probably either:
1. Trivial (one obvious choice — fine, but say so)
2. Under-examined (no real options were considered)
Be honest about which.
### Risks & unknowns
**A risk without a mitigation OR an acceptance is a hidden bug.** Either:
- "We'll mitigate by X" (be specific)
- "We're accepting this risk because Y" (honest)
Don't list "scaling" as a risk in a v1 doc designed for <10k DAU. That's not a v1 risk. Real v1 risks are usually: third-party API failures, cold-start latency, on-device storage limits, model output quality.
### Testing strategy
**This section is the test plan, not the test code.** The `test-driven-dev` skill reads this section to generate the actual tests, so be specific about what behavior matters.
**Unit tests** target pure functions, data transformations, and validators — code with clear inputs and outputs. Don't write "test the entire backend" — write specific behaviors: "Test that `parse_brief()` returns the four expected fields when given a well-formed BRIEF.md."
**Integration tests** are sparse. Aim for one per major user flow. Test the happy path at the API or function-call level — not via browser automation.
**The "deliberately not tested" list is the contract** that keeps the test suite small and honest. Good candidates for "not tested": visual styling, animation timing, third-party SDK internals, generated AI content (test the *call*, not the *output*).
If your engineering doc has no real testing strategy, the test-driven-dev skill will generate generic tests that don't match the actual behavior of the app. **The strategy is what makes tests useful.**
### Rollout & monitoring
Specify the 3–5 metrics you'd actually look at if you were on call. Not "all the metrics". The ones that would wake someone up.
### Cost & capacity
**Don't skip this.** A 5-line back-of-envelope estimate is worth 50 pages of architecture. If sticker generation is $0.02/call and a user makes 3/day, that's $1.80/user/month — which probably kills your business model on day 1. Better to know now.
### Open questions
Every open question needs an owner. "TBD" is not an owner.
### Out of scope
The engineering scope cuts. "No accounts" becomes "no auth service, no session management, no user table." Be specific about what infrastructure / code / dependencies you're choosing not to write.
---
## Things to push back on
When the brief is unclear or over-asking:
- **"Make it scalable"** → "To what? Give me a target DAU and a latency budget. Without numbers I can't design."
- **"Use [hot new tech]"** → "What does it do that [our existing boring tech] doesn't? If nothing, we use the boring thing."
- **"Add user accounts"** → "What breaks without them in v1? If nothing, we're not building auth in v1."
- **"Just use microservices"** → "How many services? Why? What's split where? If you can't answer in one sentence, we don't have a microservices problem yet."
- **The brief implies an unrealistic latency target** → Push back in the doc. "3s sticker generation requires model call <1.5s. Our current model is 4s p95. Either we change the model or we change the interaction (async + notification)."
Senior engineers say "no, here's why" — not "sure, we'll figure it out."
---
## Length & tone
- **Target length:** 3–6 pages of Markdown. Longer is acceptable if the system genuinely warrants it; shorter is suspicious for anything non-trivial.
- **Voice:** Plainspoken, specific, honest about uncertainty. No false confidence. No hedge words either ("might possibly potentially" — pick one).
- **Diagrams:** Mermaid where they earn their place. Don't include a diagram for a 2-component system.
- **Code blocks:** Use them for schemas, types, API shapes. Avoid for prose.
- **No marketing language.** This is an internal doc. "Cutting-edge", "best-in-class", "robust" — delete on sight.
---
## When you're done
End at section 14 (or 15 if you used the appendix). Don't add "Conclusion". A good engineering design doc is **finished when out-of-scope is written**. The next step is review, then code.
