Architecture Optimizer

Audit a system's architecture, report what is coupled, risky or expensive and why, agree a plan, then change it. Order: evidence, approval, edits. Architecture changes are expensive and hard to reverse; a diagram or a pattern name is not evidence. Nothing is restructured before approval.

Workflow

1. Scope (quick)

• Map the system: repositories/services, deployables, data stores, synchronous and asynchronous edges, team ownership, environments, and the quality attributes that matter (latency, availability, throughput, cost, compliance, delivery speed).
• Read the existing architecture docs/ADRs/C4 if present; otherwise reconstruct the map from manifests, compose/K8s files, routes, schemas and calls.
• Run python <skill-dir>/scripts/audit.py <repo-root> -- static scan for dependency cycles, boundary leaks, shared databases, multiple ORMs, remote calls without timeouts, HTTP-in-loop, oversized files, missing ADRs/contracts/observability and deployment probes, with file:line evidence. Use --json to post-process.
• Classify the pain: slow delivery/coupling, runtime latency/reliability, data consistency, scaling/cost, security/compliance, or migration risk. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here.

2. Audit

The script finds cheap leads; you find the rest by reading the dependency graph, the transaction boundaries and the call chains. Load only what applies:

Measure, never guess. Build the dependency graph and measure real behavior: p50/p95/p99, error rate, throughput, queue age, DB pool wait, deploy frequency/lead time, change failure rate, and the cost of the current topology. A pattern is not a result; a diagram is not a measurement.

Mark each finding Confirmed (graph/trace/load/code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as ARCHITECTURE_OPTIMIZATION_REPORT.md in the repo root, and show the user. Five-line summary, findings table by impact/effort/risk, then per-finding detail (evidence, why it hurts, fix, risk, migration/rollback). Include a current/target boundary map and the decisions that need an ADR.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- break cycles, fix boundary leaks, add timeouts/retries/idempotency, remove shared mutable state, add indexes/caching, bound pools/queues, add health/metrics/traces, document an ADR. Low risk and reversible.
2. Structural -- introduce/repair module boundaries, move code behind a public API, split a package, apply outbox/inbox, make handlers idempotent, add contract tests, isolate a data store, change deployment topology. Name each behavior and ownership change.
3. Heavy -- extract a service, split a database/schema, adopt event-driven flows, replace the monolith, platform/cloud migration. Separately approved, with a staged rollout and rollback. Each step: scope, files/services touched, expected effect, how to verify, how to roll back, and the decision record.

5. Fix

Only approved items, in small groups. After each: build, typecheck/lint, unit/integration/contract tests, and the relevant load/trace check. Keep changes reversible; do not combine a data migration with a boundary refactor. If a change alters a transaction boundary, public API/event contract, data ownership or deploy topology, stop and ask.

6. Verify and wrap up

Re-run the same graph/metrics/load: cycles, cross-boundary imports, p50/p95/p99, error rate, queue age, DB pool wait, deploy lead time/change failure rate, cost. State plainly what could not be measured. End with deferred items, the ADRs written, and one suggested next step.

Principles

• Boundaries follow data and transactions, not org charts. A service that shares a database is a distributed monolith.
• Modular monolith before microservices. Extract only when a measured constraint (team autonomy, scaling, isolation, compliance) justifies the network and consistency cost.
• Every remote call needs a contract and a failure mode. Timeout, retry policy, idempotency, circuit breaker/bulkhead, and an owner.
• Data ownership is the hard part. One writer per aggregate; schemas/contracts evolve; shared tables are coupling.
• Async is not free. Events need ordering/idempotency/outbox/inbox, replay and dead-letter handling.
• Measure quality attributes. Latency, availability, cost and delivery speed decide; pattern fashion does not.
• Prefer reversible steps. Strangler fig, parallel run, feature flags, expand/contract migrations.
• Record decisions. ADRs and fitness functions stop the same debate from recurring.
• Docs and systems drift. Reconstruct the map from code/config, then reconcile the docs.