# Abstraction Architect

> Knowledge base for structural entropy: the cost of change when one concept lives in many places. TRIGGER WHEN: the user asks "should I extract this", "who owns this rule", "is this DRY enough", "is this the wrong abstraction"; centralizing, inlining or removing a layer; auditing for duplicated domain knowledge, competing sources of truth, redundant models or derivable state stored anyway; loaded under /abstraction-architect:audit or the /senior-review:team-review abstraction dimension. DO NOT TRIGGER WHEN: the concern is formatting (use clean-code:clean-code), Python refactoring (use python-development:python-refactor), dead-code removal (use /senior-review:code-review --fix), security (use senior-review:security-auditor), contract drift (use senior-review:api-contract-auditor), or cycles, cohesion and single-file patterns (use senior-review:code-auditor and senior-review:chicken-egg-detector).

- Skill: `acaprino/abstraction-architect` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add acaprino/abstraction-architect`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/abstraction-architect/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: acaprino (https://skillmd.com/u/acaprino)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/acaprino/abstraction-architect

---


# Abstraction Architect Knowledge Base

The question this knowledge base answers:

> Where is the same concept represented, owned, computed or implemented more than once, and what does it cost when that concept changes?

Structural entropy accumulates in ways that look locally reasonable. A support team implements an eligibility check because the domain one was hard to reach. A config value is added next to the code that reads it. A DTO is copied because the original had a field the new caller did not want. Each decision is defensible; the sum is a codebase where a single conceptual change touches nine files and misses two.

## The two evidence tracks

Everything here rests on one distinction, developed in `references/theory.md` section 9 and operationalized in `references/evidence-tracks.md`.

**The track determines the nature of the evidence. The dimension determines the gate.**

- **Form** is the same mechanism written more than once. The risk is premature extraction, the instrument is the count, and the Rule of Three is the gate for D5.
- **Knowledge** is the same fact holding more than one authoritative representation. The risk is drift between owners, the count is the wrong instrument, and two representations are sufficient behind a much stricter semantic proof.

The discriminating question for the knowledge track: **can these representations legitimately disagree?** If yes, there is no finding, whatever the surface similarity. If no, two is enough.

## When to use this skill

Load it when:

- Deciding whether to extract, centralize or inline
- Asking who canonically owns a fact, a policy, a threshold or a piece of state
- Auditing for duplicated knowledge, competing authorities, redundant models, or stored state that is derivable
- Evaluating whether an existing abstraction is paying for itself
- Running `/abstraction-architect:audit`, which spawns the auditor agent that loads this skill

Do not load it for the concerns listed in `references/scope-boundaries.md`, which names the owner of each.

## Reference index

Load on demand, not all up front.

| File | Read it when |
|---|---|
| `references/dimensions.md` | Classifying a candidate. D1 to D7 with proof rules, lenses L1 to L4, the single-primary-classification precedence. **Start here.** |
| `references/evidence-tracks.md` | Deciding whether a candidate has enough evidence. Tracks A and B, gates `A1` to `A5` and `K1` to `K6`. |
| `references/concept-census.md` | Running a global audit. Seed map, concept extraction, the four search families, the Concept Evidence Index. |
| `references/concept-index-protocol.md` | Reading or writing `.abstraction-architect/concept-index.json`. Schema, freshness states, the script contract. |
| `references/decision-frame.md` | Promoting a candidate, calibrating severity, framing the remediation. |
| `references/unification-patterns.md` | Matching a form candidate. P1 to P12 infrastructural, P13 to P18 domain-facing. Not an admission gate. |
| `references/anti-patterns.md` | Judging D7. Twelve wrong-abstraction shapes, cited as `anti-pattern A1` to `A12`. Not an admission gate. |
| `references/scope-boundaries.md` | Deciding whether a concern belongs here at all. The five exclusions and their owners. |
| `references/theory.md` | Arguing a position, or when the user asks why this matters. Nine principles plus the single rule of thumb. |
| `references/further-reading.md` | Citing a source. Verified URLs. |

## The single rule of thumb

When this concern changes, where do you have to touch?

- If N grows linearly with features, the concern is a unification candidate.
- If every new requirement adds a flag, branch or parameter to a shared layer, that layer is a wrong abstraction.
- If N is greater than one and the sites must agree but nothing makes them agree, you have found a competing authority, and that is the more serious finding.

## Two rules that are easy to lose

> Structural simplification is the desired outcome of the audit, not a finding category.

> Patterns are discovery aids and classification examples, never an exhaustive catalog or a prerequisite for a finding.