acaprino/abstraction-architect

Abstraction Architect Knowledge Base

This skill gives Claude the conceptual frame for the pure-architecture question: when does duplicated logic want to be unified into a layer, and when does an existing layer want to be inlined or decomposed?

Two opposite failure modes coexist in real codebases. Both have well-documented theory:

• Missed unification. A cross-cutting concern is duplicated across many call sites. Each site is local-looking but they form a single concern that wants to change together. Drift between sites becomes the source of bugs, security holes, or fiscal errors.
• Wrong abstraction. An existing shared layer is fighting its callers. Every new feature adds a flag, branch, or parameter to it. The layer should be inlined back to duplication so the real pattern can emerge later.

The skill exists because both failures look superficially like "the right thing": missed unification is hidden under "we already have similar code elsewhere", and wrong abstraction is defended by "but we DRY'd this last quarter".

When to use this skill

Load this skill when:

• Deciding whether to extract three similar functions into a shared layer
• Evaluating whether an existing abstraction is paying for itself
• Auditing a codebase for missed unification or wrong abstraction (/abstraction-architect:audit spawns the auditor agent which loads this skill)
• Onboarding teammates to the canonical literature on the abstraction-vs-duplication question

Do not load this skill for:

• Style and readability fixes (use clean-code:clean-code)
• Python-specific complexity reduction (use python-development:python-refactor)
• Dead-code removal (use senior-review:cleanup-dead-code)
• Security and authorization review (use senior-review:security-auditor)
• Generic code review (use senior-review:code-auditor)

Reference index

Load references on demand, not all up front. Each file is focused on one dimension of the problem.

• references/theory.md — the principles: Rule of Three, DRY/WET/AHA, Wrong Abstraction, Locality of Behaviour, Bounded Contexts, Tidy First options framing, CUPID vs SOLID. Read this first when the user asks "why does this matter".
• references/unification-patterns.md — 12 canonical essential duplication cases. Read when scanning a codebase for missed unification or when the user asks "should this be a service".
• references/anti-patterns.md — 12 canonical wrong abstraction cases. Read when reviewing an existing shared layer or when the user asks "is this a god service".
• references/decision-frame.md — the operational classifier with pre-flight questions and severity calibration. Read when promoting a candidate to a finding or deciding whether the gate has been cleared.
• references/further-reading.md — verified URL list (Metz, Beck, Dodds, Abramov, Gross, North, Acton, Italian-language DDD canon). Read when the user asks for resources or when citing a position in a report.

The single rule of thumb

When the 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.

This question subsumes most of the principles in theory.md and is the load-bearing classifier the auditor agent applies.