architecturehardparts

Architecture Hard Parts

Use this when a coding session contains an architecture decision, not just an implementation task.

Distinct from architect-lens (code-level connascence and trade-offs): this skill works at the service level — service-decomposition, data-ownership, and saga territory.

Mental Model

Architecture choices are contextual tradeoffs. No pattern is best outside the current constraints. Anchor each recommendation in connascence (strength × locality × degree — see architect-lens), data ownership, deployability, runtime behavior, and validation.

Workflow

1. Name the decision in one sentence.

   Include the current system shape, the change being considered, and the architectural force involved. Example forces include service boundaries, data ownership, transaction consistency, workflow coordination, shared code, contract shape, scaling pressure, and failure isolation.

2. Reproduce the current shape from code and runtime evidence.

   Read the relevant modules, schemas, migrations, tests, dependency manifests, deployment descriptors, service contracts, queues, jobs, logs, and dashboards. Prefer current repo evidence over remembered architecture.

1. Map connascence before proposing a change.

   Check static connascence (visible in source) through imports, package dependencies, shared libraries, schema access, deployment coupling, configuration, and infrastructure dependencies. Check dynamic connascence (only at runtime) through request flow, messaging, consistency requirements, workflow state, coordination ownership, retries, timeout behavior, and compensation paths. Judge each by strength × locality × degree: strong, distant, high-degree connascence is the decomposition target.

2. Decide whether the work is pulling apart or putting back together.

   Pull apart when the evidence favors maintainability, testability, deployability, scalability, fault isolation, security isolation, change isolation, or database type fit. Put back together when the evidence favors single unit transactions, tightly related data, heavy workflow chatter, frequent shared domain code changes, low latency, or simpler ownership.

3. Read the focused reference only when needed.

   Read references/catalog.md for the decision catalog when the task involves decomposition, service granularity, data decomposition, reuse, data ownership, eventual consistency, workflows, sagas, contracts, or data mesh.

   Read references/adrtemplate.md when the user wants a durable written decision, when the choice affects multiple teams, or when the code change creates an architectural precedent.

4. Compare options with the local context.

   Use a short matrix in prose. Keep options mutually exclusive and collectively complete for the decision at hand. Avoid generic pros and cons that ignore the repo, domain workflow, data model, operational constraints, or team boundaries.

5. Prefer bottom line clarity.

   Give the user or stakeholder the practical choice in terms of outcome. Examples: choose faster response over immediate consistency, choose independent deployability over shared transaction simplicity, choose a shared library over a shared service because the function is domain local and latency sensitive.

6. Implement the smallest coherent shape — a behavior-preserving move when the decision is structural.

   Keep edits scoped to the decision. Preserve existing module boundaries unless the decision is to change them. Add tests or fitness functions that guard the architecture property, not only the domain behavior.

7. Close with verification.

   Report the code changed, the tradeoff accepted, the fitness function or test added, and any risk that still needs a follow up decision.

Fitness Function Prompts

Use these prompts to turn an architecture choice into validation:

1. What must stay isolated after this change?
2. What dependency, import, schema access, service call, queue, or shared library would violate that isolation?
3. Can a test, static check, migration check, contract test, monitor, or alert fail when the architecture drifts?
4. Is the check architecture focused rather than domain focused?

Output Contract

For architecture decisions, produce a concise decision note with these sections:

1. Decision
2. Context Evidence
3. Options Considered
4. Tradeoffs
5. Implementation Move
6. Validation
7. Consequences

When writing an ADR, use the repository convention if one exists. If none exists, use docs/adr/YYYYMMDD_slug.md. The helper script scripts/newadr.py can draft a markdown file. Example: python <skill_dir>/scripts/newadr.py --title "Split billing schema" --out-dir docs/adr --dry-run. The script path is relative to this skill, not the repo. Run with --help for all flags.

Gotchas

1. Do not split services because smaller sounds cleaner. First prove the disintegrator beats the integrator.
2. Do not merge services just because a workflow is noisy. First check whether orchestration, asynchronous messaging, or contract changes address the actual coupling.
3. Do not treat database ownership as an implementation detail. Ownership controls change safety, consistency, and bounded context integrity.
4. Do not rely on generic architecture advice. The relevant domain cases decide the tradeoff.