architecture-experience

Files (11)

• SKILL.md
• architecture-brief-template.md · assets/
• trace-example.clean.json · assets/
• trace-example.json · assets/
• adr-patterns.md · references/
• boundaries-and-dependency-direction.md · references/
• data-and-control-flow.md · references/
• mental-model-formation.md · references/
• ownership-map.md · references/
• standards.md · references/
• estimate_architecture_path.py · scripts/

SKILL.md (first lines)

# Architecture Experience

## Mission

Accelerate mental-model formation: module boundaries, dependency direction, ownership, data and control flow, extension points, and the decisions that shaped them. Deliver the two canonical answers — where a new feature belongs, and how one representative request flows end to end — fast enough to be useful inside a working session.

Describe the system as it is, not as it was designed. Ground every claim in the repository, tests, schemas, and runtime artifacts. When the code contradicts documented intent, surface the contradiction; never smooth it over.

Work in audit-first mode: form and verify the model before proposing changes. Redesign proposals are backlog entries, not audit results. This skill measures how quickly the system can be understood, not how good the system is.

Read `references/standards.md` for the canonical thresholds, severity vocabulary, and release gates.

For catalog-style discovery — listing, searching, and indexing services and owners — use the `developer-discoverability` skill instead of re-deriving inventories here.

## Architecture Magic Path

A competent engineer explains where a new feature belongs AND traces one representative request end to end within `ARCHITECTURE_COMPREHENSION_MAX_MIN`.

Design for the timer. The timer covers orientation, boundary identification, the feature placement question, the request trace, and verification of the resulting claims. It stops when both answers are stated with evidence and rationale.

Benchmark persona: an engineer with repository access and code navigation tooling, general competence in the stack, and no prior mental model of this system.

The pass/fail bands and severity vocabulary are canonical in `references/standards.md`. Cite the constant by name; never restate its value here.

Evidence labels: **Observed**, **CI-observed**, or **Estimated**. An estimate cannot prove a pass; it can only indicate likely risk or feasibility.

Run `scripts/estimate_architecture_path.py` on a request trace or import graph for an Estimated comprehension time before committing to a budget.

Reading docs, chasing imports, and re-tracing wrong paths all count against the timer. The hop list is the estimate of record; it is not the full cost.

## Architecture experience workflow

### 1. Scope and orient

Determine:

- the system under study and its repository layout
- the representative request to trace, or the feature to place
- the benchmark start and stop conditions
- which claims can be Observed versus only Estimated

Do not begin a trace before the request's entry point and expected terminal effect are named. Record the repository layout and the system's entry points before choosing a representative request.

### 2. Form the mental model

Read `references/mental-model-formation.md`.

Answer the feature placement question: which module, service, and file the feature belongs in, and why. Then trace one representative request end to end, recording every hop.

Stop when the model is internally consistent, every hop is grounded in evidence, and the trace ends at a verified terminal effect.

Verify the placement answer survives the boundary and dependency checks before it is final.

### 3. Audit boundaries and dependency direction

Read `references/boundaries-and-dependency-direction.md`.

Verify that module and service boundaries are real in the repository, not only in prose. Check dependency direction per edge: layers point one way, the graph is acyclic, and no cross-boundary calls or data structures leak between layers.

Flag every violation as a finding with the file and dependency edge as evidence.

Verify every boundary claim against the repository; prose and diagrams are hypotheses.

### 4. Build the ownership map

Read `references/ownership-map.md`.

For each module or service, record the owner, code path, public surface, and escalation or on-call route. Derive ownership from CODEOWNERS, manifests, and git history. Unknown ownership is a finding, not a skip.

Verify the map against current manifests; a map that cannot be cross-checked is stale.

### 5. Trace data and control flow

Read `references/data-and-control-flow.md`.

Trace each relevant flow type — request/response, event/async, batch, config-driven — with the per-type procedure. Record each hop's layer, transformation, side effects, and failure modes.

Verify each hop in code or tests; inferred hops are labeled Estimated.

### 6. Audit ADRs

Read `references/adr-patterns.md`.

Verify each ADR states status, context, decision, consequences, and supersedes. Detect staleness: decisions contradicted by code, tests, or docs; statuses not updated; superseded decisions without a pointer to the successor.

Verify ADR status against the code; a decision the code contradicts is stale.

### 7. Identify extension points

Locate where new features, plugins, hooks, and protocols attach. Distinguish designed extension points from accidental seams. Note the hop cost each extension path adds to the mental model.

Verify an extension point by finding at least one consumer or call site.

### 8. Estimate the Architecture Magic Path

Assemble the trace as a JSON hop list and run `scripts/estimate_architecture_path.py`. Compare the Estimated comprehension time against `ARCHITECTURE_COMPREHENSION_MAX_MIN`; the script's default budget comes from its embedded constant table.

If the estimate is over budget, attribute the excess to individual hops and propose reductions: fewer hops, clearer boundaries, ownership clarity, or ADR remediation.

Example: `python3 scripts/estimate_architecture_path.py trace.json --max-const ARCHITECTURE_COMPREHENSION_MAX_MIN`. Verify the estimator against the bundled fixtures before trusting it on a real trace.

## Contracts

- Every claim carries an evidence label: Observed, CI-observed, or Estimated. An estimate cannot prove a PASS.
- Boundaries, dependencies, and ownership are derived from the repository, tests, and runtime artifacts, never from interviews or prose alone.
- Dependency direction is stated per edge; cycles and upward edges are findings, not noise.
- Ownership resolves to a team or role, or is recorded as Unknown. Unknown is a finding.
- ADR status is the current decision state; stale ADRs are findings.
- The Architecture Magic Path is compared against `ARCHITECTURE_COMPREHENSION_MAX_MIN` by name; values come from the canonical metrics and are never restated here.
- Hops are counted per layer crossing, and a trace is incomplete until it ends at a verified terminal effect.
- Heuristic tool output is never a verdict; semantic review is still required.

## Required output

Produce the architecture brief from `assets/architecture-brief-template.md`. The brief must contain:

1. Scope — system, representative request or feature, evidence labels
2. Mental model — feature placement answer with rationale; trace summary
3. Boundary audit — module/service boundaries verified, with evidence

From devarispbrown/devex-skills, MIT.

More from devarispbrown/devex-skills