Tech Design

Tech Design

Turn a locked WHAT into a buildable HOW. Gather the constraints first, then decide the technical approach with the facts on the table, and append the design record to the spec: technical decisions as D-NN blocks (so the architecture why survives across sessions), the Structure Outline — schemas, signatures, file list — as a design snapshot that freezes at lock, and the constraints and accepted risks recon proved (facts must not live only in conversation). Verify the design against reality before handing off.

When to use

YES: a feature's product/UX is locked in a spec and now needs implementation decisions (approach, data shapes, file layout) before it can be sequenced into waves.

NO: product scope or UX is still unclear (use product-interview); the change is trivial with one obvious implementation (go straight to write-plan); you only need wave ordering, not design (use write-plan).

Protocol

Input

• Spec folder: meta/specs/NNN-slug/ (or a path to either file in it, or a feature name to match against existing folder slugs). If more than one folder plausibly matches, list the candidates via AskUserQuestion — never glob-and-pick. The resolved NNN-slug is the one Step 6 commits.

Step 1 — Gate: the WHAT must be locked

Refuse to proceed if the spec (meta/specs/NNN-slug/spec.md) is not ready:

grep -nE '^[[:space:]]*-[[:space:]]*\*\*Status:\*\*[[:space:]]*open' spec.md   # any hit ⇒ blocked
grep -n '\[NEEDS CLARIFICATION:' spec.md                                       # any hit ⇒ blocked

(Exact forms are load-bearing — defined under Gate anchors in skills/product-interview/SKILL.md beside the canonical template. POSIX ERE only; don't "fix" the patterns.)

If either matches, stop and report in this exact shape — never design on top of an unlocked WHAT:

**Blocked — the WHAT isn't locked:**
- Open decisions: [D-NN — title, one per line | none]
- Unresolved markers: [each clarification marker, verbatim | none]
Next: resolve these in product-interview, then re-run tech-design.

Step 2 — Discover (two parallel tracks, before any design)

Bounded by the spec, so parallel — both complete before an approach is proposed.

2A — Context (parent reads):

• The spec: Requirements, UX, ACs, product decisions (note the highest existing D-NN — Step 5 continues the numbering from it), Constraints, Open Questions (items tagged (for tech-design) are inputs discovery left for this skill).
• Project conventions: CLAUDE.md and whatever convention docs it references (ARCHITECTURE.md, api-patterns.md, .claude/rules). These are the source of truth for "where things go" — follow them; don't re-decide them here.
• Existing code in the affected areas: patterns, interfaces, signatures to match — and the test landscape (test file locations, test style — unit/integration/e2e — helpers and fixtures the implementation should follow); nothing downstream re-discovers it.

2B — Constraint recon (parallel Opus subagents, one per surface):

Enumerate every external surface the spec's ACs ride on — the enumeration sizes the fan-out: one subagent per surface, merging closely related surfaces (no external surfaces at all → record "2B empty — no external surfaces" and design on 2A alone). Each dispatch carries the surface name plus the AC/Constraint texts riding on it, so the subagent knows which numbers are load-bearing. Recon targets per surface type:

| Surface | Recon | |---|---| | External APIs / providers | Hard limits: rate/throughput caps, quotas, batch sizes, latency floors; required fields; capabilities; gotchas | | Platform (Shopify, extension, etc.) | What the platform permits/forbids for the promised UX; review/approval constraints | | Existing subsystems | The real interfaces and capacities of internal systems the design will lean on | | Data / migrations | Current schema shapes and volumes a delta must be compatible with |

Each subagent returns these fields — read blocks and volatility first; they drive the gate, the rest informs the design:

| Field | Value | |---|---| | blocks | AC-N \| D-NN \| none — a constraint that makes a cited AC unsatisfiable or contradicts a decision; none is valid and recordable | | volatility | stable \| changing — set changing (with what/when) whenever the user has named a pending change to the surface | | exists | yes / no | | capabilities | what the surface can do | | hard constraints | the limits, with numbers | | gotchas | traps the design must avoid |

The gate — resolve before designing. A blocks or changing finding stops you; pick a choice via AskUserQuestion. A surface flagged both takes the blocks choice first — a current blocker outranks a future one.

| Finding | Choices (via AskUserQuestion) | |---|---| | blocks: AC-N \| D-NN | Route back to product-interview (rec.) · Revise the AC now · Record as accepted risk · Abort | | volatility: changing | Design against the anticipated state (rec.) · Design against the current state · Block until it settles | | blocks: none, stable | none — continue |

Mechanics for the choices that touch the spec:

• Route back to product-interview (the WHAT itself is affected) — first write [NEEDS CLARIFICATION: ] beside the affected AC/requirement; the marker re-blocks the lock gates, so an interrupted route-back resumes from the file, not memory — then stop.
• Revise the AC now (user-sanctioned WHAT edit) — revise in place with a (revised per D-NN) marker plus a superseding D-NN citing the 2B evidence; it rides Step 6's commit, continue.
• Record as accepted risk — lands in ## Accepted risks (knowingly carried) at the Step-5 Draft write; continue.
• Design against the anticipated state — existing code is the starting state, never the target (the WHAT may diverge); record the assumption as a D-NN (drafted now, written at Step 5) citing what changes and when; a not-yet-built dependency it leans on lands in ## Accepted risks as a sequencing dependency.
• Design against the current state — note why the pending change is out of scope, continue.
• Block until it settles — write [NEEDS CLARIFICATION: pending change — confirm the target state before lock] beside the affected AC/requirement; the lock greps refuse to lock until it's resolved.

Before leaving Step 2: state the load-bearing assumptions you are making (named pending changes are caught above; this catches the rest) in this exact shape, so the user can correct them before any design exists:

**Assumptions I'm carrying into the design:**
- [assumption] — [what breaks if it's wrong]

(Write None — 2A/2B covered everything load-bearing when the list is empty.)

Step 3 — Design: approach, then structure

Select approach — with 2B's constraints on the table:

• Single obvious path — note it briefly and continue. Most features land here.
• Multiple viable paths with real tradeoffs — the parent owns the judgment of whether multi-path applies; the agent owns the analysis. Spawn the propose-alternatives agent (agents/propose-alternatives.md) with three inputs: Problem (the spec's goal plus the specific decision point that forks), Current approach (the existing implementation if any, else "no current approach — greenfield"), Context (2A's relevant files and conventions + 2B's constraints). Present its AlternativesOutput via AskUserQuestion with a recommendation — flag when confidence is low or the tradeoff depends on priorities you don't know. Do not continue until the user selects. If the user proposes an approach not in the list, validate it against 2A's conventions and 2B's constraints — adopt it if it holds; otherwise explain why and re-ask.

Record the chosen approach (and rejected alternatives + why, distinguishing rejected-forever from deferred) as a technical D-NN block destined for the spec, citing the 2B finding that drove it where load-bearing. A genuinely load-bearing fork is a decision (spec), not detail — capture it here, don't let it leak silently into the plan.

Structure outline — the concrete shape the locked decisions imply. Scale depth to scope. This is a design snapshot bound for the spec's ## Structure Outline section — written Status: Draft for review, frozen once locked:

## Structure Outline

### Before → after
[ASCII call-graph: affected module/flow today → what it becomes.
 module → function → return-shape, with caller lists.]

### File map
[Annotated create/modify tree (✨ create · ✏️ modify) of the affected dirs, with a one-line *why* on each load-bearing or convention-establishing/deviating placement; where an existing convention dictates the location, cite the convention doc instead of re-arguing it. Add the import DAG when cross-module direction is a rule. Scale to scope — a one-file change is one line.]

### Per-file walk
- `path/to/file.py`
  - `signature(args) -> ReturnType` — [one-line purpose]
  - [data shape / schema delta: field, type, nullability, constraint]

### Files touched
- create: [paths]
- modify: [paths]

Must include, where the goal touches them: data shapes, signatures, component trees — skip skeleton sections irrelevant to the change (a backend-only change needs no component tree). The create/modify file list and the File map are unconditional; placement rationale is one line per load-bearing entry — a deeper walk only on request. For a new or changed return shape or exported signature, trace its direct consumers across any serialization boundary — a frontend fetch, IPC/queue message, GraphQL field, route path, serialized-storage record — that no symbol-grep recovers; each one that must change is a modify entry so write-plan slices it. Direct consumers only — a deeper chain is an accepted runtime scope-expansion. Must NOT include: implementation logic, wave sequencing, test strategy.

The ### Files touched heading is write-plan's buildable signal — its outline-present gate greps ^### Files touched (Gate anchors, skills/product-interview/SKILL.md). Withheld from the Step-5 Draft and appended at lock, so a mid-design Draft reads as in-progress, never finished or stale. Never rename or omit it.

Pressure-test the shape — before handing the design to verify, read the outline as architecture and invoke the deep-modules skill via the Skill tool for the lens — the deletion test and deepening-move table it carries. Then settle a verdict on each axis below for the Step-5 review: a clean outline clears all four in one line; a smell names its axis, and the loaded table gives the reshape. Fold any reshape into the outline first; record a D-NN only if it changes the chosen approach itself.

• Depth — does each module earn its interface? Settle it with the deletion test.
• Interface — is the common case one obvious call, with the hard cases hidden rather than pushed onto callers?
• Seam only where it varies — is every swap point backed by a real second adapter, not a hypothetical one?
• Coupling — would changing one decision force edits across several files? Reshape so the knowledge lives in one place.

Step 4 — Verify the design

2B answered "what is possible"; this step answers "does this specific design hold." Verify runs before the Draft is written — on the drafted outline, not yet on disk. Launch Opus subagents split by file cluster (related files and interfaces share a subagent):

• Signatures/interfaces the outline references exist as written.
• The schema delta is compatible with current models.
• Named components exist with the assumed props/composition.
• Every outline claim that names a real file or symbol resolves to it — file-location and attribution claims ("X lives in a.js"), not just signatures and props.
• Nothing in the outline contradicts a 2B finding; any surface the chosen approach implies that 2B didn't cover (e.g., a specific endpoint of a recon'd provider) gets checked now.

Each subagent returns a verdict per outline claim it checked: confirmed / broken (with evidence) / not checkable — "breaks the outline" is the subagent's finding to make, not parent improvisation. Step 4 is mandatory on every outline bound for the spec — re-run replacements included. Never skip it.

If a finding breaks the outline, present via AskUserQuestion: "Amend outline" (recommended — a verified break means the design is wrong; back to Step 3) / "Record as a known risk and proceed" (written into the spec's ## Accepted risks (knowingly carried) at the Step-5 Draft write — never left in conversation) / "Route back to product-interview" (the WHAT is affected — first write [NEEDS CLARIFICATION: ] beside the affected AC, as in 2B's gate) / "Abort". A finding that merely needs an AC downgrade rather than a re-interview takes 2B's "Revise the AC now" path.

Step 5 — Write the Draft, then review the file

Write the verified design into meta/specs/NNN-slug/spec.md as Status: Draft so the user reviews the file. One Draft write, the design-fact duties:

1. Technical D-NN blocks under ## Decisions, continuing discovery's D-NN numbering; stamp [tech] after the colon (discovery stamps [product] — advisory, no gate greps it). Write lowercase Status: locked — the Capitalized header staying Draft is what keeps the design reviewable yet unlocked (the case split; see Gate anchors). Canonical block:

### D-07: [tech] [technical decision title]
- **Status:** locked
- **Chosen:** [approach/structure]
- **Rejected:** [alt — why it lost]; [alt — *deferred*, not rejected forever — why]
- **Rationale:** [the constraint that drove it; cite the 2B/verify finding if load-bearing]
- **Supersedes:** —
- **Superseded-by:** —

1. The Structure Outline into ## Structure Outline, replacing the section wholesale (discovery's placeholder comment included) — but withhold the ### Files touched heading (appended at lock, Step 6).

1. Constraints and accepted risks: append load-bearing 2B numbers (cited in a blocks verdict or bounding an AC) to ## Constraints; append every Step-4 risk the user accepted to ## Accepted risks (knowingly carried). Both append-by-both — discovery seeds them; this skill adds what recon and verify proved.

1. Confirm the AC gating tags: discovery's [code-gated]/[human-gated:] tags were provisional — confirm or flip each against the chosen design. A tag flip is a tag-only edit, exempt from the supersession protocol; the only other sanctioned AC edit is a user-approved revision from the 2B/Step-4 gates.

1. Dispose of (for tech-design) Open Questions: strike each with → resolved per D-NN, or escalate to a real decision or clarification marker — the tag must be absent at lock.

Then point the user at the file — spec.md, or git diff — and give the review its context in this exact shape:

**Design ready for review:**
- What verify changed: [claim → what broke → how the outline was amended | none — all claims confirmed]
- Accepted risks carried: [risk — why accepted | none]
- Shape checks: [clear | [check]: [smell] → [reshape]]
``` Use `AskUserQuestion` to collect the choice: "Lock & commit" / "Adjust" / "Find gaps first". Recommended: lock & commit once the file matches the goal and clears the four shape checks. This is the design-lock gate — any reply that isn't explicit approval is **Adjust**; never proceed on an implied yes.

- **Adjust** — edit the Draft in place, re-run Step 4's verify on the change (an unverified outline is a guess), then re-point the user at the file.
- **Find gaps first** — opt-in, for a complex design or when you doubt the outline is complete — invoke the `find-gaps` skill over the written Draft, paired with the affected code paths so checkers read real files. Fence lenses to design-level absences only — data integrity, inter

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [preetamnath](https://github.com/preetamnath)
- **Source:** [preetamnath/agent-skills](https://github.com/preetamnath/agent-skills)
- **License:** MIT
- **Homepage:** https://www.preetamnath.com/blog/agent-skills

Install and usage instructions live in the source repository linked above.