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

FocusQuestionHandoff output
BoundaryWhere do tenant, identity, API, storage, and ownership boundaries change?Boundary rule and source
DependencyWhat does the design assume about services, queues, storage, or external contracts?Dependency owner and failure mode
Failure and recoveryWhat happens on timeout, retry, partial write, restart, or compensation?State transition and recovery evidence
Data consistencyWhich state is authoritative, and how are duplicates or stale reads handled?Invariant and validation fixture
SecurityHow are identity, authorization, isolation, secrets, and audit handled?Control, scope, and safe check
PerformanceWhat load, latency, size, and resource assumptions matter?Measurable objective and environment
ObservabilityWhich signal explains success, failure, and recovery?Metric, log, trace, and owner
CompatibilityWhat existing clients, schemas, versions, and migrations must remain safe?Compatibility boundary and regression path
MaintainabilityWhat will make the design hard to change or diagnose?Operational cost and owner
Verification readinessWhat 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

StateMeaningHandling
knownDirectly supported by the supplied ADR, contract, diagram, or planCite revision and source location
missingNeeded to evaluate a design topic but not suppliedCreate a bounded gap and next evidence action
conflictingDesign, contract, policy, or prior decision disagreePreserve the conflict and request an architecture decision
staleRevision, traffic model, dependency, or environment is outdatedMark freshness before comparing claims
out_of_scopeUnsupplied code, production probe, or excluded componentKeep the review boundary explicit
assumptionsA temporary implementation or traffic assumptionState 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

LayerHow to write itExample
FactWhat the supplied design directly statesFiles use a tenant-prefixed storage path
Evidence-backed InferenceWhat the missing control could allowStorage naming alone may not enforce tenant authorization
RecommendationThe smallest design or validation actionTrace owner check, response, cache, audit, and expiry behavior
Human DecisionWhat architecture or risk owner must chooseSelect 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

MaterialWhat to provideWhat to do when it is missing
Design materialADR, diagrams, interfaces, data flow, constraints, and success criteriaList unsupplied design areas
Version and scopeRevision, components, environments, traffic, data, and compatibility boundaryDo not infer from names
Risk topicsDependencies, failures, security, performance, observability, and maintenanceAssess topics separately
Verification readinessTest ideas, metrics, fixtures, owners, and safe environmentKeep 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
FieldExample
Source and scopeThe supplied export design, download API, object-storage path, and audit flow; add exact revisions and sections when available
FindingA tenant-prefixed path is described, but the authorization decision and object-owner check are not defined
Evidence statemissing; no API-to-storage trace or negative-case contract supplied
Impact and priorityCross-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 decisionAssign an accountable API or security owner to decide where ownership is enforced; the design does not name that owner
ActionDefine 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 conditionThe design traces one owner check through API, storage, response, audit, and recovery paths
ValidationAfter 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 fieldWhat to retain
Source and scopeDesign revision, component, interface, dependency, and exclusions for this pass
Evidence and impactFacts stated in the design, missing material, and the affected boundary or decision
Owner and open decisionWhich design owner must confirm the interface, ownership, failure semantics, or trade-off
ValidationSmallest scenario, preconditions, expected behavior, required evidence, and stop condition
Close conditionRecords needed for the design change, independent validation, and owner acceptance

Next-stage route

HandoffWhat to carry
Requirement to design reviewScope, constraints, security objectives, non-functional goals, and open decisions
Design review to implementationTD findings, resolved decisions, invariants, failure states, and validation fixtures
Implementation to test or operationsVersion, 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

Common traps

  1. Checking that a diagram exists without checking boundaries, failure handling, or recovery.
  2. Treating “supports high concurrency” or “has monitoring” as a measurable verification criterion.
  3. Turning a recommendation into an approved architecture or release conclusion.
  4. 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

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

More Resources

Share