A diagram can be complete enough to present and still omit the boundary that will fail in production. Technical design review is where those omissions become questions before they become code.
Why this Skill is needed
The Technical Design Quality Review Skill reviews ADRs, component designs, data flows, and non-functional constraints before implementation. It produces TD-## findings and validation preparation without reviewing unsupplied code or approving an architecture.
What the Skill does
Use this Skill to inspect boundaries, dependencies, failure modes, data consistency, security, performance, observability, compatibility, maintainability, and verification readiness in a supplied design.
A good finding names the design topic, source evidence, impact, priority, gap action, owner, decision question, close condition, and validation method.
Use it when an architecture note, ADR, component design, or technical proposal needs an implementation-readiness pass while important details remain uncertain.
What it does not do
It does not replace:
- Code review, build validation, integration testing, load testing, or production verification.
- Architecture approval or a Human choice between incompatible designs.
- Security review, threat modeling, or risk acceptance.
- Evidence from the real environment, real traffic, or real failure recovery.
It answers whether the supplied design has a reviewable path to implementation and validation.
What it checks
| Focus | Question | Handoff output |
|---|---|---|
| Boundary | Where do tenant, identity, API, storage, and ownership boundaries change? | Boundary rule and source |
| Dependency | What does the design assume about services, queues, storage, or external contracts? | Dependency owner and failure mode |
| Failure and recovery | What happens on timeout, retry, partial write, restart, or compensation? | State transition and recovery evidence |
| Data consistency | Which state is authoritative, and how are duplicates or stale reads handled? | Invariant and validation fixture |
| Security | How are identity, authorization, isolation, secrets, and audit handled? | Control, scope, and safe check |
| Performance | What load, latency, size, and resource assumptions matter? | Measurable objective and environment |
| Observability | Which signal explains success, failure, and recovery? | Metric, log, trace, and owner |
| Compatibility | What existing clients, schemas, versions, and migrations must remain safe? | Compatibility boundary and regression path |
| Maintainability | What will make the design hard to change or diagnose? | Operational cost and owner |
| Verification readiness | What is the smallest check that can challenge the design claim? | Fixture, command, expected evidence |
The matrix keeps an attractive diagram from hiding an unverified operational assumption.
Audit inputs before you start
| State | Meaning | Handling |
|---|---|---|
| known | Directly supported by the supplied ADR, contract, diagram, or plan | Cite revision and source location |
| missing | Needed to evaluate a design topic but not supplied | Create a bounded gap and next evidence action |
| conflicting | Design, contract, policy, or prior decision disagree | Preserve the conflict and request an architecture decision |
| stale | Revision, traffic model, dependency, or environment is outdated | Mark freshness before comparing claims |
| out_of_scope | Unsupplied code, production probe, or excluded component | Keep the review boundary explicit |
| assumptions | A temporary implementation or traffic assumption | State how it can be falsified |
Static design evidence is useful, but it stays static. Do not turn a diagram, dry run, or file presence into runtime proof.
From problem to structured Finding
Connect the source, scope, evidence state, analysis, owner, action, close condition, and validation before writing the conclusion. The case below keeps this Skill’s identifier and domain context.
Keep the decision layers separate
| Layer | How to write it | Example |
|---|---|---|
| Fact | What the supplied design directly states | Files use a tenant-prefixed storage path |
| Evidence-backed Inference | What the missing control could allow | Storage naming alone may not enforce tenant authorization |
| Recommendation | The smallest design or validation action | Trace owner check, response, cache, audit, and expiry behavior |
| Human Decision | What architecture or risk owner must choose | Select the enforcement point and accept compatibility trade-offs |
Keep implementation and runtime claims open until their evidence exists.
A complete case
This case follows Input, Analysis, Finding, Decision, and Validation. When material is incomplete, keep missing, conflicting, or assumptions visible instead of turning them into a pass.
Input
| Material | What to provide | What to do when it is missing |
|---|---|---|
| Design material | ADR, diagrams, interfaces, data flow, constraints, and success criteria | List unsupplied design areas |
| Version and scope | Revision, components, environments, traffic, data, and compatibility boundary | Do not infer from names |
| Risk topics | Dependencies, failures, security, performance, observability, and maintenance | Assess topics separately |
| Verification readiness | Test ideas, metrics, fixtures, owners, and safe environment | Keep unverified claims open |
Use a request like this:
Use the technical-design-quality-review Skill.
Task: Review a design for a multi-tenant invoice export service before implementation.
Inputs: [ADR, data flow, API contract, tenant boundary, storage plan, threat notes, observability plan]
Scope: [export jobs, object storage, customer access]
Constraints: [no code or production probe supplied]
Produce TD-## findings across boundaries, dependencies, failures, data, security, performance, observability, compatibility, maintainability, and verification readiness. Keep design claims separate from runtime evidence.
Analysis
Use the input, matrix, and evidence state to form the judgment before writing the Finding; keep missing material as a gap.
Finding
Example finding: TD-03 exposes a missing tenant boundary
The design stores export files under a tenant-prefixed path but does not specify how download authorization checks the tenant ID. This is an illustrative design review pattern, not an implementation result.
TD-03 — Export download authorization is not connected to tenant ownership
| Field | Example |
|---|---|
| Source and scope | The supplied export design, download API, object-storage path, and audit flow; add exact revisions and sections when available |
| Finding | A tenant-prefixed path is described, but the authorization decision and object-owner check are not defined |
| Evidence state | missing; no API-to-storage trace or negative-case contract supplied |
| Impact and priority | Cross-tenant access and incomplete audit evidence are possible if tenant isolation is required; priority stays unassessed until the affected scope and project rubric are supplied |
| Owner and decision | Assign an accountable API or security owner to decide where ownership is enforced; the design does not name that owner |
| Action | Define where the API verifies the tenant-to-object relationship and how object-storage signing enforces the same rule; specify the failure response and audit evidence |
| Close condition | The design traces one owner check through API, storage, response, audit, and recovery paths |
| Validation | After the owner confirms tenant isolation is required, use synthetic tenants and exports in an isolated environment; expect cross-tenant requests to be denied and retain the response and audit evidence |
The Skill does not infer isolation from a path name. It turns the missing boundary into a decision and a check.
Decision
The accountable owner confirms the decision question and risk trade-off; the Skill does not make that choice.
Validation
Before closing the finding, run the stated validation and retain the raw artifact. Without an execution record, the status remains unverified.
How a Finding enters the next stage
Handoff output
Each TD-## should carry the information needed to continue the work:
| Handoff field | What to retain |
|---|---|
| Source and scope | Design revision, component, interface, dependency, and exclusions for this pass |
| Evidence and impact | Facts stated in the design, missing material, and the affected boundary or decision |
| Owner and open decision | Which design owner must confirm the interface, ownership, failure semantics, or trade-off |
| Validation | Smallest scenario, preconditions, expected behavior, required evidence, and stop condition |
| Close condition | Records needed for the design change, independent validation, and owner acceptance |
Next-stage route
| Handoff | What to carry |
|---|---|
| Requirement to design review | Scope, constraints, security objectives, non-functional goals, and open decisions |
| Design review to implementation | TD findings, resolved decisions, invariants, failure states, and validation fixtures |
| Implementation to test or operations | Version, changed boundary, runtime evidence, logs, metrics, and residual risk |
The review prepares an actionable next step; it does not approve the architecture by itself.
How to prepare better input
Provide the current design revision, scope, interfaces, dependency assumptions, data classification, non-functional objectives, observability plan, intended validation environment, and known constraints.
A useful handoff keeps source revisions, scope, evidence index, assumptions, Human decision boundary, owner, close condition, and the smallest validation action together.
Best practices
- Prioritize high-impact design gaps and request the smallest evidence or safe check that can resolve them.
- Keep design facts, evidence-backed inferences, recommendations, and Human decisions separate; do not turn an assumption into a conclusion.
Working with other Skills
- Security Requirement Review: https://inaodeng.com/en/qaskills/security-requirement-review/
- Observability Design Review: https://inaodeng.com/en/qaskills/observability-design-review/
- Database Design Quality Review: https://inaodeng.com/en/qaskills/database-design-quality-review/
- API Security Testing: https://inaodeng.com/en/qaskills/api-security-testing/
Common traps
- Checking that a diagram exists without checking boundaries, failure handling, or recovery.
- Treating “supports high concurrency” or “has monitoring” as a measurable verification criterion.
- Turning a recommendation into an approved architecture or release conclusion.
- Treating unsupplied code or a dry run as implementation evidence.
Install and invoke
npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en --skill technical-design-quality-review
Use the technical-design-quality-review Skill.
Include objective, scope, versions, evidence paths, constraints, and decision boundary.
Audit inputs first. Return TD-## findings with source, evidence state, impact, owner, close condition, and validation method.
FAQ
Can this Skill review code?
Only code supplied as design evidence can be referenced. It must not claim to have reviewed unsupplied implementation.
Does a clean design review mean the build will pass?
No. Build, compatibility, security, performance, recovery, and runtime behavior need their own evidence.
References
Source Skill and execution contract
-
Technical Design Quality Review prompt (execution contract): https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/technical-design-quality-review/prompts/technical-design-quality-review.md
-
Technical Design Quality Review Skill source directory (definition, prompt, agent adaptation, and evaluation assets): https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/technical-design-quality-review
Static plans, file presence, and dry runs retain their evidence state. They do not become runtime proof, capacity evidence, security approval, or release readiness.
Further reading
- Technical Design Quality Review details: https://inaodeng.com/en/qaskills/technical-design-quality-review/
- Awesome QA Skills project: https://github.com/naodeng/awesome-qa-skills
More Resources
- Personal website: https://inaodeng.com/en/
- AI-generated test detection project: https://github.com/AI-Native-QA-Lab/ai-test-auditor
- DeepSeek QA Workbench: https://github.com/naodeng/dsh-qa
- More AI testing skills: https://inaodeng.com/en/qaskills/
- More testing wiki: https://inaodeng.com/en/wiki/
- More AI Wiki: https://inaodeng.com/en/AIWiki/