evolve-architecture

name	evolve-architecture
description	Use when evaluating or evolving an existing system's architecture, business or domain boundaries, cross-module flows, dependencies, reliability, scalability, security, or operability.

Evolve Architecture

Improve an existing architecture from evidence and actual business needs. Theory is a decision aid, not a target architecture.

Boundaries

• Keep review requests read-only. Design or implement only when asked.
• Establish the system boundary, business goals, change pressure, critical qualities, constraints, and evidence before judging the design.
• Inspect only causal paths that can change the conclusion; do not inventory the repository by default.
• Separate confirmed facts, hypotheses, and evidence gaps. Do not treat folder shape, pattern compliance, or theoretical elegance as a problem without a concrete consequence.
• Preserve existing contracts, data semantics, and unexplained user changes.

Understand The System

Reconstruct representative request, data, control, deployment, and failure paths. Identify:

• business capabilities, subdomains, vocabulary, rules, data ownership, and public contracts;
• dependency direction and collaboration across domain or module boundaries;
• critical flows from entry through orchestration, decisions, state changes, transaction boundaries, events or side effects, errors, compensation, and outcome;
• coupling, consistency, concurrency, idempotency, failure isolation, recovery, observability, security, capacity, operability, readability, and testability.

Rank findings by impact, likelihood, and confidence. Tie each finding to an affected scenario, evidence, consequence, root cause, and smallest credible remediation direction. If the current design is adequate, say so.

Design The Evolution

When design is requested, derive the target from confirmed problems. Define:

• target boundaries, responsibilities, ownership, public contracts, and allowed dependencies;
• the critical business flows and their consistency and failure semantics;
• the current-to-target mapping and what stays, moves, splits, merges, or leaves;
• alternatives, trade-offs, compatibility impact, and the simplest adequate option;
• an ordered, independently verifiable, reversible evolution path.

Apply DDD, modularity, information hiding, high cohesion and low coupling, Clean or Hexagonal Architecture, event-driven design, CQRS, or distributed systems patterns only when they solve an evidenced problem. Do not introduce microservices, layers, abstractions, or extension points without demonstrated need.

Gate And Deliver

Before changing domain boundaries, public contracts, data or persistence, cross-module dependencies, deployment topology, or moving code broadly, explain the material trade-offs. Obtain user approval only when a material decision remains unresolved or the request does not authorize implementation. An explicit request to implement a named or recommended design counts as approval. When evidence is missing, identify the smallest way to acquire it.

After authorization, evolve through working vertical slices. Use refactor, develop-feature, or fix-bug for each slice instead of duplicating its workflow. Keep the architecture decision and acceptance criteria visible; update only supporting tests, documentation, configuration, and observability.

For reviews, report findings, evidence gaps, assumptions, and priorities. For evolution designs, add the business and domain map, critical flows, target, alternatives, staged plan, verification, rollback, decisions, and residual risk. Claim completion only with current test, build, and feasible runtime evidence for affected behavior and contracts.