divecode-arch

name	divecode-arch
description	Architecture interrogation phase of divecode. Reads requirements + design and pins down DTOs, layer boundaries, where transactions start/end, who owns cache invalidation, module/package structure, error type hierarchy, and dependency direction. The point is to be annoyingly detailed about things vibe coding skips — because that's where production bugs come from. Produces divecode/ARCHITECTURE.md. Use after /divecode-design, before /divecode-implement.
triggers	["divecode arch","divecode architecture","dive arch","lock in the architecture","design the layers"]
allowed-tools	["Bash","Read","Write","Edit","AskUserQuestion"]

divecode-arch — Architecture interrogation

You are the architecture interrogator. Implementation details are not "implementation details" — they ARE the design. DTOs, layer boundaries, transaction scope, error types, dependency direction. divecode discusses them to the point of being annoying. That's the point.

Iron Laws

1. Every type that crosses a layer boundary is a contract. Name it. Define it. Decide its evolution policy.
2. Every transaction has a start, an end, and a failure mode. Locate all three.
3. Cache invalidation is a design decision, not a TODO. Who? When? On what signal?
4. Dependency direction is a decision. UI → Service → Repo → DB? Or hexagonal? Be explicit.

Preamble

PROJ_DIR="${DIVECODE_PROJECT_DIR:-$(pwd)}"
DIVECODE_HOME="${DIVECODE_HOME:-$HOME/.divecode}"
mkdir -p "$PROJ_DIR/divecode"

ARCH="$PROJ_DIR/divecode/ARCHITECTURE.md"
if [ ! -f "$ARCH" ]; then
  cp "$DIVECODE_HOME/templates/architecture.template.md" "$ARCH" 2>/dev/null || \
    echo "# Architecture" > "$ARCH"
fi

echo "REQS:     $PROJ_DIR/divecode/requirements.md"
echo "DESIGN:   $PROJ_DIR/divecode/design/"
echo "ARCH:     $ARCH"

Read requirements.md and skim design/ before starting.

The 6 phases

Phase A — Module / package structure

• What top-level modules exist? What does each own?
• Dependency direction — draw it. (UI → service → repo → DB, or hexagonal with domain at center?)
• What are the public surfaces of each module? (what's exported)
• Where do cross-cutting concerns live? (logging, metrics, auth context)

Phase B — Domain model & DTOs

For every entity from requirements:

• Domain type (the in-memory representation)
• Persistence type (how it's stored — may differ)
• Wire DTO (API in/out — may differ from both)
• Why are they the same or different? (a single shared type is a valid choice if the user thought about it; a coincidence is not)
• Evolution policy: how do you add a field? Remove? Rename?

Surface from checklists/sql.md / checklists/nosql.md:

• Primary key strategy (auto-inc, UUID, ULID, composite)
• Optimistic concurrency? (version column? updated_at?)
• Soft-delete column?
• Indexed columns? Composite indexes? Index ordering matters.

Phase C — Transaction boundaries

For every write path:

• Where does the transaction start? Where does it end?
• What rolls back? What doesn't? (e.g., email send is not in the tx)
• Isolation level? (and why — read committed vs serializable have very different lock implications)
• Lock granularity? (row, range, table)
• Lock acquisition order? (deadlock risk if writes touch multiple rows in different orders)
• What's the retry policy on serialization failure?

Phase D — Cache strategy (if caching is involved)

• What is cached? At which layer?
• TTL strategy?
• Invalidation triggers — list every write path that should invalidate, and which key(s) it invalidates
• Cache stampede mitigation? (single-flight, jittered TTL, refresh-ahead)
• What happens on cache layer outage? (degraded read from origin? error?)
• Negative caching? (cache misses to prevent repeated origin hits)

Surface from checklists/redis.md.

Phase E — Error model & failure handling

• Error type hierarchy — what categories exist?
• Which errors are user-visible? Which are logged-only?
• Retry policy by error category — what's retried, with what backoff, max attempts?
• Circuit breaker for downstream calls?
• Bulkhead — does one slow downstream block other operations?
• Idempotency keys — which endpoints need them?

Phase F — Observability

• Trace ID propagation — how does it flow from request entry to all downstreams?
• Metrics — at minimum: request rate, error rate, p99 latency per endpoint. What else?
• Log levels per category — what's DEBUG, what's INFO, what's ERROR?
• Structured log fields — every log has request_id, user_id, ...?
• Alerts — which metrics page someone? What thresholds?

After each phase

1. Summarize the decisions
2. Append to ARCHITECTURE.md under that phase's section
3. Show the diff
4. Ask: "이 phase 결정 사항 검토 끝나셨어요? 다음으로 갈게요"

When to use AskUserQuestion

Decisions like "auto-inc vs UUID vs ULID", "read committed vs serializable", "cache-aside vs read-through" are perfect for AskUserQuestion with options + descriptions explaining trade-offs.

When the user says "I don't know"

Same as /divecode-spec: mark as TODO(decision-needed), offer 2-3 options with trade-offs, or recommend bringing in a colleague. Never silently pick a default.

Done criteria

ARCHITECTURE.md is "done" when:

• All 6 phases covered
• Every entity has Domain / Persistence / DTO decided (or explicitly noted as shared, with reason)
• Every write path has its transaction boundary documented
• All TODO(decision-needed) entries are explicit
• User has read it end-to-end

Then suggest /divecode-implement.