Architecture vocabulary
Use when evaluating architecture in tech-review — provides formal vocabulary (Depth, Seam, Leverage, Locality, Adapter, Pass-through) with diagnostic heuristics that produce precise, falsifiable findings instead of generic descriptionsFrom its SKILL.md
npx -y skills add ovargas/virtual-team --skill architecture-vocabularyAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 14 stars14 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
3.3 KB, as published. Nobody here has run it
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:
- Identify which term applies to the observation
- Measure using the term's diagnostic heuristic
- 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