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 critique 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.

For critique, evaluate the supplied candidate using the relevant caller trace, principles, and boundary or risk checks.
Report supported findings, their consequences, and the smallest useful corrections.
A review request does not authorize edits or require developing a replacement architecture.
Use the design procedure below when developing or comparing approaches is requested.
For a concrete question about whether the proposed contract narrows governing requirements, consult `spec-review`'s [non-narrowing check](../spec-review/references/non-narrowing.md), not another full review.

## 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.

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?
Ground your interpretation of intent in the request; distinguish it from explicit requirements, and do not silently override those requirements.

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.
Compare a simpler approach against the practical purpose before preserving obligations inferred by the proposal.
For worked comparisons of added guarantees, operation scope, and representations, 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

#### Configuration

Before designing interfaces or configuration, list every dimension required to vary and the policy that remains fixed.

- For each configurable dimension, name the explicit requirement and its authoritative source.
- Prefer stable references to existing authorities over restating them.
- Record deliberately fixed behavior in the output.

#### Persistence

Identify the current storage boundary before selecting a persistence mechanism.
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.
Changing persistence, protection, or lifetime does too; none 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

Use these principles for both design and critique; consulting them does not start the full design procedure.

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 the applicable inspection before choosing or proposing an API, protocol, or subsystem split.
Start with one complete caller-to-result interaction using existing commands, identifiers, and defaults.
For an existing subsystem, trace the affected specification, implementation, same-path tests, and callers.
Identify the result the caller needs, then inspect how far that interaction already gets before treating a missing proposed interface as a missing capability.

Compare that route with the governing outcome, including required maintenance or lifecycle changes, before investigating proposal-specific machinery.
Check the ownership, authorization, compatibility, storage, and supported-interface constraints needed to establish whether the direct route suffices.
If it does, use step 2 to state the complete recommendation and stop; do not investigate resources or boundaries for an addition that is no longer needed.
Use the further inspection below only where it can resolve a remaining choice or establish a candidate's sufficiency.

From jyn514/dotfiles, Unlicense.

More from jyn514/dotfiles