robsonkades/agent-skills/microservices-architecture

Microservices Architecture

Purpose

Make several individually plausible decisions work together for one business outcome. Own their dependencies, conflicting assumptions and integration evidence. A list of patterns or services is insufficient: show which decision constrains which other decision, who can resolve a conflict, and what the next useful increment will prove.

Use this after the affected initiative or use case is known. Initial enterprise orientation belongs to enterprise-application-architecture; distributed symptom triage belongs to distributed-systems. A single timeout adjustment belongs to timeouts-and-deadlines. Do not send these tasks through the entire architecture track. Whether a particular module should become a process belongs to distribution-boundaries; carry its decision forward rather than redoing its analysis here.

Establish the working constraints

Start from the requested result: review findings, an architecture decision, or implemented changes. Reuse accepted decisions and existing evidence. Keep a suitable monolith or existing service arrangement when it meets the outcome; neither a service count nor a bounded-context count is a success criterion. Reopen an accepted boundary only when a changed requirement or contradictory evidence warrants it.

Trace one representative business operation before mapping the whole system:

• Outcome and invariants: caller, protected business effect, latency/availability or

freshness requirement, prohibited intermediate states, and the party authorized to change those requirements. Separate binding constraints from preferences such as "every capability needs a service." Use architecture-characteristics when the outcome is still only "scalable" or "reliable."

• Actual path: entry points, domain rules, transaction/data owners, calls/events,

consumers, scheduled jobs, credentials and trust boundaries. Compare source/contracts with deployments and observations; a diagram or annotation is an assertion to check.

• Delivery and operation: current compatibility promises, release history, incidents,

support ownership, deployment units, failure domains and existing recovery procedures. Use changes and incident evidence to test autonomy or isolation claims; separate pipelines alone establish neither.

• Java/Spring target when present: Maven/Gradle toolchains, compiler release, resolved

dependency management, Spring Boot/Framework/Cloud versions, runtime images and CI. Inspect transaction managers, client configuration and effective profiles for the affected path. This skill has no fixed Java baseline or executable example and grants no upgrade, preview-feature or new-platform requirement.

Distinguish observed facts, inferred relationships and untested hypotheses. Record the artifact/version and relevant workload or capture window behind consequential evidence. If evidence is absent, name the smallest missing trace, contract or owner answer; continue independent work and keep dependent conclusions conditional. Do not invent owners, traffic volumes or performance gains to complete a map.

Build and reconcile the decision map

Keep the map in the project's existing architecture record or task artifact. Link existing ADRs rather than copying them. For each consequential open or affected decision, record:

1. Question and constraint: affected operation/invariant, evidence and any assumption

that could change the answer.

1. Choice and alternative: retain/change/probe, rationale, consequential cost and what

would cause reconsideration. When option comparison needs depth, use architecture-trade-off-analysis.

1. Accountability: decision authority, implementation/operation owner and specialist

question. An advisory skill is not the accountable team.

1. Dependencies and status: decisions this answer needs or constrains, conflicting

requirement/assumption, and whether the choice is proposed or accepted. Track its validation separately: accepted does not mean demonstrated.

1. Acceptance evidence: observable result, check/fixture, responsible owner and any

remaining limit. Use architecture-decision-making for ADR lifecycle, proportionate to the consequence.

Order work by actual dependencies and uncertainty. Settle a blocking invariant or authority question before committing its dependent API/read model. Independent investigations can proceed together; a circular dependency is a reason for a bounded joint experiment or requirement clarification, not an arbitrary ordering. Send each specialist the existing evidence and exact unresolved question, and require a returned contract, assumptions, failure semantics and verification. Do not restart discovery at each handoff.

When an answer changes, revisit only its dependent decisions. Compare their assumptions at the shared boundary: identity/tenant, authoritative state, allowed staleness, transaction participation, deadline, failure outcome and supported versions. For example, an available cached balance does not establish permission to spend it, and moving work behind a gateway does not establish authorization at the operation. Route the unresolved mechanism instead of filling the gap with a framework annotation.

Reconcile time and load across the whole call path too: separately accepted timeout/retry policies can exhaust the caller's budget or multiply downstream attempts. Inspect effective gateway, client and SDK policies before accepting a composed guarantee. The integration reference identifies the evidence to pass to the timeout/retry specialists.

If two binding constraints cannot both hold under the proposed design, expose the conflict and the options to its decision authority. Do not silently weaken an invariant or label an unapproved compromise accepted. Read Integrating decisions when proposals conflict, a process boundary changes semantics, or an implementation slice needs checks across several owners.

Ask the specialist for a bounded result

Load only owners needed by the current questions. This table states the handoff contract; the detailed mechanism remains in its owning skill.

Use these specialists for the remaining affected contracts and their verification:

• rpc-and-api-contracts and schema-evolution-and-compatibility for wire behavior and

version coexistence; distributed-transactions-and-sagas and idempotency for cross-owner effects, delivery gaps, uncertain outcomes and safe repetition.

• distributed-systems-testing for failure evidence and slo-and-alerting for operational

acceptance. Reuse established evidence when it covers the proposed change.

For deeper analysis or framework-specific work, consult:

• architecture-coupling-and-quanta when the independence claim needs a deeper coupling

assessment; architecture-refactoring-paths when a migration across boundaries needs sequencing beyond the first slice.

• spring-boot for applicable Spring implementation routing, carrying the discovered

project baseline. Consult spring-transactions-and-events when transaction or publication behavior is material, and spring-boot-testing for integration verification.

If an owner is unavailable, retain the question and next discriminating check in the map; do not claim its work happened or install tools/skills as a prerequisite without need.

Deliver the first verifiable slice

Choose the smallest business operation that tests the highest-risk interaction among the decisions. State the effect and consumer, included paths, excluded work and why the result will change confidence in the architecture. A small internal modular change can be the right slice. A disconnected service scaffold cannot demonstrate an integration claim.

For a review, deliver the evidenced conflicts or supported retained decisions and their consequences. For a design, deliver the reconciled map and an executable next validation step. For an implementation request, continue through the authorized slice: domain/API change, affected callers or consumers, configuration, data/permission changes, operational documentation and recovery where relevant. Reuse project conventions and supported dependencies; preserve encapsulation and business types, and justify new shared libraries or abstractions by actual consumers. Do not stop after naming specialists.

Verify the combined path with checks capable of refuting its claims: business effect and invariant, realistic dependency failure, relevant unauthorized access, and mixed versions when coexistence is promised. Match deployment/capacity claims to the target topology and workload; mock-only checks cannot demonstrate those properties. For a local-only change, do not manufacture distributed failure tests. Choose checks from the actual map.

Return the retained/changed decisions, unresolved conflicts with owners, slice artifacts or implementation, commands/cases and observed results, plus the next decision affected by that evidence. Separate structural checks, executed behavior and unexecuted plans; state tool/environment limits. An integrated test in an isolated environment is evidence for its exercised conditions, not proof of production autonomy, security or availability.

Sources and limits

• Lewis and Fowler, Microservices:

consult when interpreting independent deployment, business capabilities and failure costs. These are architectural observations, not a conformance checklist.

• Fowler, Monolith First: consult when

evaluating an assumed extraction trajectory. Its tentative experiential argument supports considering retention, not a universal rule against starting with services.