architect

Technical design interview →

## Technical Design

in the living doc → adversarial review. Pipeline: explore → define → [design] → architect → plan.

Phase: Engineering. User is technical. Architecture, data models, APIs, build phasing.

Starting

Before asking anything:

Read the living doc (
```
./plans/*.md
```
). If multiple
```
.md
```
files found in
```
./plans/
```
, list them via
```
AskUserQuestion
```
and ask which feature to work on. Check for
```
## Scope
```
,
```
## Requirements
```
(including
```
### Glossary
```
),
```
## UX Design
```
. Use glossary terms for data models, APIs, modules. UX flows map to behavior specs; screens map to frontend architecture.
- ```
## Rollback Notes
```
  has content → this takes priority. Skip steps 2-3, resume only affected domains, clear after resolving.
- ```
## Technical Design
```
  already populated → skip interview, go to Adversarial Review.
- No
```
### Glossary
```
  AND Requirements introduce 3+ domain nouns not in codebase → generate glossary silently under
```
## Requirements
```
  , then use canonical terms throughout.
Explore codebase — tech stack, patterns, data models, auth, API conventions, testing, deployment.
Search for architecture docs, ADRs, domain glossaries. If docs and code disagree, note discrepancy to surface during interview.

If prior sections exist: "I've read the requirements, UX spec, and explored the codebase. Requirements call for [items]. UX defines [N flows] across [N screens]. Stack uses [tech]. First: [question]."

No Requirements? Works — but note that defined requirements make for a better design. No UX? Interview covers frontend concerns as needed.

Interview Protocol

Use

AskUserQuestion

for every question — header (≤12 chars), 2–4 options, one marked "(Recommended)". When user can't decide: state recommendation, record as assumption, move on.

Code-first: explore codebase before asking questions it could answer. Present as confirmation: "I found the project handles auth via [pattern] in

[file]

. I'll follow the same approach unless you say otherwise."

Completeness tracking

Resolve decisions across these domains depth-first — exhaust sub-questions before moving on. Only ask what the codebase can't answer.

Architecture & patterns — boundaries, APIs, new components, fit with existing
Data & state — models, schemas, migrations, state locations (DB/cache/session/client)
Core behavior — implementation approach per user story. What happens in the system when the user acts?
Edge cases & failure modes — race conditions, partial failures, validation, error handling
Integration & dependencies — external systems, third-party APIs, integration contracts
Operational & rollout — backward compat, feature flags, migrations, monitoring, cost
Security & access — permissions, trust boundaries, sensitive data, abuse prevention
Testing strategy — unit/integration/e2e per component, test data, mocking
Code design & boundaries — interfaces, abstractions, dependency direction, coupling tradeoffs
Phased build plan — vertical slices, dependency ordering, acceptance criteria per phase

Dependencies, conflicts, rollback

Resolve upstream decisions before downstream. When code/docs/intent conflict, surface and classify: stale docs, incomplete implementation, intentional divergence, or unclear ownership.

When a design decision invalidates upstream sections, append

## Rollback Notes

(trigger, affected domains, decisions to preserve). Data model breaks UX →

/design

. Architectural constraint breaks product assumption →

/define

/explore

. Roll back only as far as necessary.

Producing the spec

When every domain is fully resolved, write

## Technical Design

using the template in

assets/technical-design-template.md

. If Requirements exist, verify every FR and user story maps to a behavior spec or build phase — surface gaps. Then proceed to Adversarial Review.

Adversarial Review

Work silently — user sees only the verdict.

Understand: Read
```
## Technical Design
```
. Note anything underspecified, inconsistent, or surprising.
Verify against reality: Check claims against code/docs. If
```
## Requirements
```
exists: all stories addressed? Unjustified scope creep? If
```
## Scope
```
exists: tackles out-of-scope items? Misses v1 items?
Pressure-test: Apply adversarial lenses from
```
references/review-lenses.md
```
. Skip empty lenses, order findings by severity.

Verdict

Scale response to severity — solid spec gets short review.

Format:

### Verdict: Ready / Revise / Rethink

followed by Strengths (2-4 bullets), Issues (severity-ordered: category, description, why it matters, what to do), Risks, Recommended next step (one sentence).

Ready: "Design is ready. Run

/plan

to decompose into implementation issues."

Revise: "Let's work through these issues." Group by subsection. Each turn: restate issues, propose resolution, accept/modify/skip. Skipped items become open items. After all resolved, update

## Technical Design

in single write, re-run review. No re-exploration, no scope expansion, no re-interview. Batch aggressively if user accepts unchanged.

Rethink: Recommend re-interview from affected domains. If findings invalidate product assumptions (not just tech), append

## Rollback Notes

and direct to

/define

/explore

Update

## Decisions Log

with design decisions. Update

## Pipeline Status

with architect row.