architecture-vocabulary

Files (1)

• SKILL.md

SKILL.md (first lines)

# Architecture Vocabulary

Use these terms and heuristics when evaluating architecture. Every architecture finding should reference at least one vocabulary term. Replace generic language with precise claims.

## Terms

| Term | Definition | Diagnostic Heuristic |
|------|-----------|---------------------|
| **Depth** | Deep module: simple interface, rich functionality. Shallow module: interface nearly as complex as its implementation. | Count public methods vs lines of meaningful logic. Ratio near 1:1 = shallow. |
| **Seam** | A point where behavior can be swapped without changing surrounding code. | One adapter = hypothetical seam. Two adapters = real seam. Zero = no seam yet. |
| **Adapter** | A thin translation layer at a seam boundary. Contains no business logic. | If your adapter has business logic, it's a service pretending to be an adapter. |
| **Leverage** | How much behavior a module provides per unit of interface complexity. | **Deletion test:** imagine deleting the module. If complexity reappears across callers, it was earning its keep (high leverage). If callers barely notice, it was unnecessary indirection (low leverage). |
| **Locality** | Related changes stay together. Modifying one behavior touches one file, not five. | A single conceptual change requiring edits in 3+ files = poor locality. The concept is scattered across wrong boundaries. |
| **Pass-through** | A method or layer that receives arguments, adds nothing, and forwards them. | If you can describe it as "calls X with the same arguments," it's a pass-through. Adds stack depth and maintenance cost without value. |

## Applying the Vocabulary

When forming architecture findings, follow this protocol:

1. **Identify** which term applies to the observation
2. **Measure** using the term's diagnostic heuristic
3. **State** the finding as a falsifiable claim with evidence

## Findings: Before and After

**Before:** "This module has poor separation of concerns."
**After:** "This module is **shallow** — 14 public methods, each a thin wrapper over the database client (ratio ~1:1). Consider consolidating into fewer, deeper methods."

**Before:** "The code is tightly coupled."
**After:** "No **seam** exists between the notification service and the email provider (zero adapters). Adding a second provider would require modifying the service internals."

**Before:** "There's unnecessary abstraction here."
**After:** "The `EventDispatcher` has **low leverage** — deletion test shows callers would each add one direct call, replacing the dispatcher's 200-line interface with ~3 lines each. The indirection isn't earning its complexity."

**Before:** "Changes to billing touch too many files."
**After:** "Billing logic has **poor locality** — updating the tax calculation requires edits in `models/order.ts`, `services/billing.ts`, `utils/tax.ts`, and `api/checkout.ts` (4 files). Consider co-locating tax logic."

## Integration

This skill is loaded by:
- `commands/tech-review.md` — used during the Architecture & Structure evaluation dimension

From ovargas/virtual-team, MIT.

More from ovargas/virtual-team