Architecture Session Review

Architecture Session Review

Use this skill to make architecture thinking useful during coding work. The goal is not to summarize architecture theory. The goal is to turn architectural concerns into better implementation choices, concrete verification, and clear decision notes.

Core Workflow

1. Inspect the live code, repo guidance, current behavior, and any user supplied issue or design context before judging the architecture. 2. Classify the scope of the change as local code, module, component, service, data boundary, deployment unit, or enterprise integration. 3. Identify the top quality attributes that matter for this task. Prefer three or fewer unless the user asks for a broad review. 4. Map the relevant boundaries: components, dependencies, public contracts, data ownership, runtime communication, and deployment constraints. 5. Choose the smallest useful architecture pass: 1. Light pass for one file, one function, or a narrow refactor. 2. Standard pass for cross module changes, shared abstractions, public APIs, data access, or important tests. 3. Deep pass for service boundaries, storage ownership, architecture style choices, migration plans, operational behavior, or decisions that should be recorded. 6. Implement the change in the style of the repo, keeping edits scoped. 7. Convert each important concern into a verification step. Prefer executable checks over opinions. 8. Finish with changed files, checks run, decision summary, and remaining risk.

Architectural Significance Filter

Treat a choice as architecturally significant when it affects at least one of these:

1. System structure or component boundaries. 2. Quality attributes such as maintainability, scalability, performance, availability, security, resilience, deployability, observability, testability, usability, or portability. 3. Dependencies between modules, services, teams, or vendors. 4. Public interfaces, contracts, protocols, schemas, migrations, or versioning. 5. Data ownership, read and write paths, transactions, consistency, or integration flow. 6. Construction technique, framework, platform, tool, build system, or process choice that will be hard to reverse.

If none apply, keep the work at normal code review depth.

Lenses to run, not re-implement

This skill is the session-level frame; it does not re-derive the per-lens analyses. Delegate them:

• Trade-offs and coupling → run architecture-lens: name the connascence type (strength × locality × degree) for any coupling the change adds, and use its decision lens to compare options (every option states what it gains and gives up — no option is free).
• Layer placement and cohesion → run architecture-lens: does each module keep one clear responsibility, and does the dependency direction stay clean?
• Runtime / data flow → confirm the owning component or service stays clear and that sync vs async matches the needed reliability, latency, and consistency.
• Fitness function → for each boundary worth protecting, name the automated check that guards it in future changes.

Carry the findings from these lenses into the risk pass and the decision note below.

Decision Record Trigger

Create or draft an ADR when the decision changes long lived direction, affects more than one team, changes risk posture, introduces a platform or vendor, changes data ownership, changes public contracts, or resolves a repeated debate.

Use the ADR template in references/adr_risk.md.

Risk Pass

For standard and deep passes, name risks with impact and likelihood:

1. Low: small impact or unlikely. 2. Medium: meaningful impact or plausible. 3. High: severe impact and plausible, or unknown technology.

For each high risk item, provide a mitigation, verification step, and owner if the user has given team context. If the task is code only, make the owner the current change set. For the full per-risk record fields, use references/adr_risk.md.

Verification Menu

Choose checks matching your top quality attributes — pick checks for the two or three attributes the change most affects, not every attribute. The full per-attribute catalog of concrete checks is in references/verification_menu.md; read it when you need the specific checks for an attribute.

Output Contract

For implementation work, keep the final response concise:

1. What changed. 2. Why the change is architecturally safe or what trade off it accepts. 3. Verification run. 4. Remaining risk.

For review work, lead with findings by severity and include file and line references.

References

Read only what is needed:

1. references/architecture_lens.md for quality attributes, modularity, component thinking, and fitness functions. 2. references/style_fit.md for architecture style selection. 3. references/adr_risk.md for ADRs, risk analysis, and diagrams. 4. references/team_checklists.md for team boundaries, review checklists, and release checks. 5. references/verification_menu.md for the per-attribute catalog of concrete verification checks.

ADR, Risk, And Diagrams

Use this reference when the task involves a long lived decision, repeated debate, high risk implementation, or architecture communication.

ADR Guidance

Create a concise ADR when a decision affects structure, quality attributes, dependencies, interfaces, data ownership, construction technique, cost, security, or more than one team.

Template:

1. Title: short and specific. 2. Status: proposed, accepted, superseded, or request for comments with deadline. 3. Context: forces, constraints, and alternatives. 4. Decision: clear statement of what will be done. 5. Consequences: benefits, costs, and trade offs. 6. Compliance: how the decision will be checked. 7. Notes: author, approval, links, and superseded records.

Put more weight on why than how.

Decision quality test:

1. Does it explain why, not only how? 2. Does it include business value? 3. Does it name rejected alternatives when useful or when the decision is likely to be revisited? 4. Does it say how compliance will be measured? 5. Does it have one system of record?

Risk Analysis

Rate risks with the low, medium, and high scale in the Risk Pass of SKILL.md. Unknown or unproven technology should be treated as high risk until tested.

For each risk, record:

1. Area. 2. Attribute affected. 3. Impact. 4. Likelihood. 5. Current evidence. 6. Mitigation. 7. Verification.

Solo Risk Storming

When no team session is possible:

1. Draw or describe the current architecture context. 2. Pick one dimension such as availability, scalability, security, data integrity, performance, deployability, or maintainability. 3. Mark likely risk points from code evidence. 4. Separate confirmed risk from suspected risk. 5. Mitigate through scoped code changes, tests, or explicit follow up.

Do not pretend solo analysis is consensus. Name it as a first pass.

Diagram Guidance

Prefer a low ritual diagram early. Use C4 style when useful:

1. Context: users and external systems. 2. Container: deployable or runtime units. 3. Component: internal building blocks. 4. Class or code level only when needed.

Diagram rules:

1. Keep view context clear when drilling in. 2. Label every ambiguous element. 3. Distinguish sync and async communication. 4. Show data ownership and direction when relevant. 5. Include a key if symbols are not obvious.

Architecture Lens

Use this reference when coding work touches structure, boundaries, or long lived quality.

Architecture Elements

Assess architecture through four practical elements:

1. Structure: the chosen topology, components, services, deployment units, and runtime flow. 2. Quality attributes: the success criteria beyond feature behavior. 3. Decisions: rules that guide implementation choices. 4. Design principles: softer guidance that helps developers choose within constraints.

Quality Attribute Discovery

Start from the domain and the task. Avoid broad lists unless doing a broad review.

1. Operational attributes: availability, continuity, performance, recoverability, reliability, robustness, scalability, elasticity. 2. Structural attributes: configurability, extensibility, installability, reuse, localization, maintainability, portability, supportability, upgradeability. 3. Cross cutting attributes: accessibility, archivability, authentication, authorization, legal and regulatory fit, privacy, security, supportability, usability.

Good architecture work usually selects a small set and makes trade offs explicit.

Modularity Review

Use the Boundary Review in SKILL.md as the core checklist for cohesion, coupling, connascence, locality, data flow, runtime flow, and fitness functions. Add these probes:

1. Cohesion splitting test: would splitting this module increase coupling and reduce readability? 2. Abstraction balance: is the code too concrete to evolve or too abstract to understand? 3. Degree: how many files, modules, services, or teams are affected if this changes?

Favor weaker coupling across wider boundaries. Strong coupling can be acceptable inside a cohesive component.

Component Thinking

When a task touches component structure, use this loop:

1. Identify candidate components from domain behavior, not only data entities. 2. Assign requirements or stories to components. 3. Check roles and responsibilities. 4. Apply the most important quality attributes. 5. Restructure components when feedback shows wrong granularity. 6. Revisit public contracts and data ownership.

Watch for entity shaped components that only mirror tables. That often means the design is driven by storage rather than behavior.

Fitness Functions

A fitness function is an objective integrity check for architecture.

Useful coding session forms:

1. Dependency cycle test. 2. Layer access rule. 3. Forbidden import rule. 4. Public contract test. 5. API schema compatibility test. 6. Query performance check. 7. Migration dry run. 8. Security configuration check. 9. Service health or smoke test. 10. Observability check for logs, metrics, or traces.

If a concern matters repeatedly, encode it so future work cannot quietly break it.

Style Fit

Use this reference when the task asks for architecture choice, service boundaries, refactoring direction, or migration planning.

First Choice

Decide these before naming a style:

1. Does one set of quality attributes fit the whole system, or do different parts need different attributes? 2. Does the domain naturally split into independent behavior areas? 3. Where should data live, and who owns writes? 4. Should communication be sync, async, or mixed? 5. What do team skill, delivery process, operations, and cost make realistic?

Default to sync communication when it is sufficient. Use async communication when reliability, scale, latency isolation, workflow decoupling, or buffering justify the complexity.

Style Signals

Layered architecture:

1. Best when the system is simple, cost constrained, technically partitioned, and needs familiar organization. 2. Watch for sinkholes, weak deployability, and weak testability if layer boundaries become ceremony. 3. Coding cue: add layer access checks when layers matter.

Pipeline architecture:

1. Best when data flows through ordered transformations. 2. Watch for poor fit when steps need heavy shared state or bidirectional coordination. 3. Coding cue: keep filters independent and pipes clear.

Microkernel architecture:

1. Best when custom behavior or product variation can live in plugins around a stable core. 2. Watch for plugin contract drift and accidental coupling between plugins. 3. Coding cue: protect core contracts and plugin registry behavior.

Service based architecture:

1. Best when domain services can be coarse grained and moderate distribution is enough. 2. Watch for database coupling, service granularity mistakes, and weak elasticity. 3. Coding cue: clarify service ownership and migration boundaries.

Event driven architecture:

1. Best when async behavior, loose coupling, burst handling, or event reaction is central. 2. Watch for data loss, error handling, workflow visibility, ordering, and contract sprawl. 3. Coding cue: test idempotency, retries, dead letter behavior, and event schema compatibility.

Space based architecture:

1. Best when extreme concurrent load and high elasticity dominate. 2. Watch for data collision, cache consistency, testability, and operational complexity. 3. Coding cue: verify cache, write behind, data reader, and data writer behavior carefully.

Orchestration driven service oriented architecture:

1. Best when enterprise workflow reuse and central coordination are stronger concerns than service autonomy. 2. Watch for tight reuse coupling and central engine bottlenecks. 3. Coding cue: make orchestration dependencies visible and test core flows.

Microservices:

1. Best when domain boundaries are strong and independent deployment, testability, team autonomy, and different quality attributes per service matter. 2. Watch for performance, data consistency, transaction complexity, operational overhead, and too much orchestration. 3. Coding cue: protect bounded context, data isolation, contract versioning, and operational signals.

Least Worst Rule

Do not ask which style is best. Ask which style creates the least harmful trade off for this domain, team, data model, and operating environment.

Team Checklists

Use this reference when architecture work affects developer guidance, pull request review, release readiness, or team workflow.

Boundary Guidance

The architect role in a coding session should give enough constraint to protect the architecture and enough freedom for implementation.

Too much control:

1. Specifies implementation detail that belongs to the developer. 2. Blocks useful libraries or tools without a clear quality reason. 3. Creates friction without improving risk.

Too little control:

1. Leaves architectural decisions to accidental local choices. 2. Gives diagrams with no actionable constraints. 3. Avoids hard decisions until the team has to decide under pressure.

Effective guidance:

1. Gives clear boundaries. 2. Explains why the boundary matters. 3. Allows local choice inside the boundary. 4. Turns repeated guidance into a check or decision record.

Code Completion Checklist

Use only for items that are easy to miss and not already automated:

1. Formatting and cleanup are complete. 2. No swallowed exceptions or silent failure paths were added. 3. Public contracts and schemas are updated. 4. Architecture boundaries still hold. 5. New dependency has a technical and business reason. 6. Important logs, metrics, and traces exist. 7. Tests cover the risky behavior.

Unit And Functional Test Checklist

Prompt for missed cases:

1. Minimum and maximum values. 2. Missing fields. 3. Special characters. 4. Permission boundaries. 5. Retry or duplicate requests. 6. Error and timeout paths. 7. Migration or compatibility behavior. 8. Cross component contract behavior.

If a checklist item can be automated, prefer automation and remove it from the manual checklist.

Release Checklist

Use when deployment risk exists:

1. Build and test checks pass. 2. Database migrations have a forward path and rollback notes. 3. Configuration and environment changes are documented. 4. New dependencies are known. 5. Observability exists for the changed path. 6. Data backfill or replay steps are defined. 7. Rollout and rollback risks are named. 8. Owners for follow up are clear.

Verification Menu

Concrete checks per quality attribute. Choose checks matching the two or three quality attributes the change most affects — do not run every row.

1. Modularity: dependency cycle checks, forbidden import checks, architecture tests, public API tests. 2. Maintainability: complexity budgets, cohesive file and module boundaries, duplication checks, clear naming. 3. Performance: benchmarks, query plans, p95 checks, load focused smoke tests. 4. Scalability and elasticity: queue depth checks, concurrency tests, capacity assumptions, back pressure tests. 5. Availability and resilience: retry behavior, timeout checks, fallback tests, chaos or failure mode tests when appropriate. 6. Security and privacy: auth path tests, least privilege checks, dependency scans, sensitive data checks. 7. Data integrity: migration tests, contract tests, idempotency tests, transaction and consistency tests. 8. Deployability: build checks, migration dry runs, rollback notes, release checklist. 9. Observability: logs, metrics, traces, alert coverage, local log review.