architecture-zoom

Architecture Zoom

Goal

Make the agreed whole product understandable, then describe only the detail needed for the next decision. Deliver a linked architecture blueprint and a path to complete, usable product increments, not an exhaustive specification or a tree of unfinished components.

This is one planning workflow. Architecture views describe structure; delivery views describe user outcomes. Neither implies extra processes, services, agents, or mandatory abstraction layers.

When to use

• Plan a new product, initial feature, or architecture before detailed implementation.
• Explain the whole system with optional drill-down into responsibilities and contracts.
• Cut a broad goal into releases that each fulfill a complete, bounded user promise.
• Update an existing blueprint after a material requirement or contract change.

When not to use

• A current implementation spec already resolves the requested change.
• A tiny correction needs no meaningful product or architecture decision.
• The request is an audit of existing code, direct refactoring, implementation, or formal proof.
• The user only wants brainstorming; do not turn that into mandatory specification work.

Inputs to inspect

Reuse the request, prior answers, product goals, release map, accepted local ADRs, relevant instructions, and existing work items. Inspect representative code and actual sources when needed to distinguish current state from intended behavior. Record material revisions and unavailable evidence; never invent paths, commands, interfaces, or test results.

Workflow

1. Resolve scope and reuse. Identify the user promise, audiences, constraints, non-goals, delivery intent, and existing artifacts. Ask only unresolved material questions. Respect active Plan and observed permissions independently. Continue independent planning while a dependent decision is unresolved.
2. Show the whole picture. Draft the overview using the blueprint template: complete agreed functional breadth, core journeys, system responsibilities, important cross-cutting requirements, and visible risks. Separate current state, target, assumptions, and proposals. Complete breadth does not mean predicting every future requirement.
3. Refine contracts only where useful. Apply design contracts. Give modules stable IDs and one authoritative contract. Link parents, children, dependencies, and cross-cutting invariants; do not duplicate shared modules. Stop refining when the next decision has sufficient responsibilities, interfaces, assumptions, and acceptance criteria. Keep deferred detail and its revisit trigger visible.
4. Cut complete product increments. Keep the architecture map separate from the delivery map. A release must fulfill its own user promise using existing capabilities plus its own work, never a future release. Prefer a narrow end-to-end path over completing database, backend, and UI separately. A ticket is not automatically an MVP. Bound necessary enabling work and POCs, link their consuming increment, and do not report them as usable products.
5. Check bottom-up and across modules. Trace each material requirement through a journey, release, relevant contracts, and planned acceptance. Check compatibility, composition, error recovery, side effects, ownership, and global invariants. Surface circular reasoning and stronger-than-evidence claims. Prioritize missing core journey steps before polishing working ones; investigate existential feasibility risks early in bounded experiments.
6. Review and stop. Classify findings as required corrections, material user trade-offs, or optional improvements. Use a bounded correction/recheck loop; default to one correction round and one targeted recheck, then surface unresolved blockers. Never weaken acceptance to call work complete. Optional improvements do not enlarge the current scope.
7. Deliver or hand off. Present the overview, next complete user outcome, remaining decisions, and exact requested document scope. Reuse unchanged approvals; persist only authorized documents when the host permits, recheck state, and read back. Hand off the relevant contracts and work-item context, not a second whole-product specification. A planning-only request ends here.