architecture-design

Files (9)

• SKILL.md
• alternatives.md · references/
• boundary-contracts.md · references/
• council-review.md · references/
• cross-critic.md · references/
• deliberation.md · references/
• design-risks.md · references/
• fusion-candidate.md · references/
• independent-plan.md · references/

SKILL.md (first lines)

# Architecture Design

Design or assess one selected subsystem and decide whether changing it is worth the churn.
Produce a falsifiable recommendation, not a diagram justified by file size.
Trace one real caller → handler → effect path before proposing a replacement; for greenfield work, trace the closest existing primitive or integration caller.
Recommend the smallest sufficient change; when evidence is missing, propose a decision-changing check rather than a larger architecture.

## Read First

Discover and follow the target repository's guidance for architecture, ownership, data and effects, testing, and design documents. Read the nearest instructions for every subsystem in scope; do not assume conventional paths exist.

## Routing

- No selected subsystem: use `opportunity-scan`
- Recurring historical pain may matter: use `pain-axis`
- Tracing the existing path leaves a genuine architectural choice: consult [alternatives](references/alternatives.md).
- That choice requires independent elaboration and critique: use [deliberation](references/deliberation.md), not a default multi-agent process.
- Selected design needs a requested repository plan: use `implementation-plan`; carry the existing boundary contract forward.
- A proposed mechanism's necessity or variability is unclear: consult [complexity justification](../references/complexity-justification.md).
- Current patch: use the repository's current-change review process

Read only the reference or skill needed for the concrete unresolved question.
Do not load a chain of design procedures by default.

## Inputs

For a staged new-tool workflow, consume approved requirements and repository integration constraints as the scope evidence. Do not invent product scope or observable behavior; record only design decisions needed to satisfy that evidence. The resulting design contributes to the implementation specification and does not replace it. For a greenfield tool, do not require a current implementation or extraction history.

### Outcome and authority

Establish the target subsystem, current problem, constraints, non-goals, compatibility posture, and requested artifact: analysis, design document, issues, or some combination.
Stop and use opportunity-scan if no subsystem is selected.
Before selecting state, tracking, acknowledgment, or coordination mechanisms, state the minimum observable outcome.
For each added mechanism, name the user requirement or pre-existing constraint that the direct solution cannot meet without it.
Apply the shared [decision-authority rule](~/.agents/shared.md#before-selecting-a-substantial-approach) when classifying proposed guarantees.
Compare the smallest existing-primitive solution first; show the decisive requirement and trade-off in the recommendation, not a separate checklist.

Check whether the design fulfills the practical purpose of the user's request, not just its literal wording or the terms of an earlier proposal.
What should the user or caller be able to know, decide, or do because of it?
Compare a simpler approach against that purpose before preserving obligations inferred by the proposal.
Ground your interpretation of intent in the request; distinguish it from explicit requirements, and do not silently override those requirements.
For worked comparisons of added guarantees and operation scope, see the [contrasting examples](references/simplicity-examples.md).

When comparing architectures, use the same observed path and requirements for each candidate; do not fabricate alternatives to fill slots.

### Configuration and storage

Before designing interfaces or configuration, list every dimension required to vary and the policy that remains fixed. For each configurable dimension, name its explicit requirement and authoritative source; prefer stable references to existing authorities over restating their contents. Record deliberately fixed behavior in the output.
Before selecting a persistence mechanism, identify the current storage boundary.
Record which principal owns the data, where and in what form it persists, its lifetime, who can read it, and who can rotate or recover it.
Moving data between principals or media changes behavior and requires authority.
So does changing its persistence, protection, or lifetime; neither is a routine implementation choice.
If the request does not settle a consequential storage-boundary change, ask before designing the dependent mechanism.
Continue independent analysis while that decision is unresolved.

Examples:

- Moving a credential from a password manager into a host file changes its storage boundary, even when consumers receive the same bytes.
- Replacing a database library does not change the boundary when owner, format, access policy, and lifetime remain fixed.
- Turning an in-memory cache into a disk cache changes the boundary because persistence and recovery behavior change.

## Principles

Avoid unnecessary coupling.
Interfaces should expose the caller’s intent without requiring knowledge of the callee’s implementation.
Keep policy separate from effects as declarative data, not runtime checks. Declarative policy may remain fixed and local: it implies no external assets, registry, extension interface, or runtime configurability unless an explicit requirement demands variation.
Before introducing coordination between systems, ask whether one owner can make the decision and pass a completed result across the boundary.
Do not mix concerns between two different systems just because it simplifies the current implementation.

Before designing an application-side workaround for a tool limitation, inspect the tool's data model and extension points.
Establish whether changing the tool is permitted; a missing CLI option does not prove a missing model capability or an immutable dependency.
When existing interfaces are insufficient, compare a narrow native extension with a separate adapter.
Include maintenance, packaging, and upstream review or release delays in that comparison.

Prefer simplicity over exhaustiveness.
Tools should be reliable, but complexity itself can cause reliability issues.
Favor designs that "passively" do the right thing rather than needing ongoing interventions.
Before adding coordination, retries, monitoring, or lifecycle state, test whether changing ownership or batching operations removes the need for that mechanism.
Before extending a tool to handle edge cases, ask if you can narrow the requirements instead.

Minimize features: add no feature or configurable dimension without an explicit requirement. Keep unspecified and adjacent policy fixed; do what was asked, no more.

Require explicit input when omission could select the wrong identity, target, scope, or high-consequence action.
Otherwise choose sensible defaults that best satisfy the requirements; unspecified details are delegated decisions.

## Procedure

### 1. Trace the existing path

Complete this inspection before choosing or proposing an API, protocol, or subsystem split.

Before proposing a new process, container, network, daemon, cache, store, or lifecycle owner, inventory existing runtime resources.
Include resources on the same trust, connectivity, and ownership path.
Give each plausible resource one disposition: `reuse`, `extend`, `reuse when both features are selected`, or `reject`.
For a rejection, name the concrete requirement the resource cannot meet.
A conditionally created resource remains a reuse candidate.
Absence in some modes does not justify a parallel resource in modes where both exist.
For example, compare extending a gateway only when two capabilities overlap before assigning the second capability its own sidecar.
Do not design the new resource until every closer existing owner has a supported rejection.

For an existing subsystem, start with the affected specification, implementation, same-path tests, and callers.
Consult API inventories, generated contracts, issues, and prepared work only when they can change the proposed boundary or prevent duplicate work.
For a staged greenfield new tool, inspect adjacent systems, existing primitives, runtime and deployment boundaries, and integration callers instead; do not require a current implementation or extraction history.
For adapters and proxies, inspect the native interface and any existing analogous adapter before deciding what to forward, restrict, or replace.
When a repeated operation constructs a client, runtime, or adapter, trace its constructors and factories through to external effects.
Identify repeated resource selection and admission checks, including configuration reads, process launches, and network requests.
Check whether an existing owner has already selected or admitted that resource before proposing another discovery path.

For a proposed resource binding, name its owner, lifetime, and replacement event, such as a new request, attachment, or configuration reload.
Include executable code as well as configuration; a fixed path does not bind the contents later loaded from it.
Check actual producer and consumer deployment lifetimes rather than assuming a shared checkout makes their updates atomic.
Separate resource selection from admission checks and observations of mutable state.
Reuse a selection only for its established lifetime; do not remove fresh checks merely because they share the discovery path.
Check which values must remain dynamic within that lifetime, including caller identity, credentials, and resource contents.

Search by exact proposed title and boundary before recording work; do not duplicate a finding merely because publication is pending.
Use history as evidence when useful, but do not equate churn with pain. Check whether the proposed arrangement existed before and why it changed; a prior separation may encode a correctness constraint.

### 2. Challenge the hardest part and decide whether design is needed

From jyn514/dotfiles, Unlicense.

More from jyn514/dotfiles