ai-training-skills/shared-abstraction-refactor/SKILL.md

name, description, metadata

name	description	metadata
shared-abstraction-refactor	Use when asked to find duplicated local patterns across a bounded code area, scan/report shared-abstraction opportunities, or promote obvious shared abstractions. Scope first, avoid whole-repo scanning by default, and distinguish scan mode from low-risk implementation mode for styles, helpers, types, schemas, tests, fixtures, docs, or other reusable project structures.	short-description Find and promote shared abstractions

Shared Abstraction Refactor

Overview

Use this skill for focused pattern-promotion refactors: finding repeated local code, styles, types, fixtures, or docs in a bounded area and deciding whether to promote them into an existing or new shared layer.

The goal is reuse without context bloat. Do not turn every task into a whole-repo archaeology dig.

Modes

Use scan mode when the user asks to scan, find opportunities, identify candidates, report duplication, or otherwise asks what could be shared. In scan mode, do not edit files. Return candidates with confidence, recommended action, and deferrals. Validation is optional unless a command helps confirm findings.

Use implement mode when the user asks to create abstractions, promote shared code, refactor, or implement obvious opportunities. In implement mode, edit only low-risk abstractions whose meaning is stable across use sites, then update call sites, tests, and docs.

If the request is ambiguous and the mode cannot be safely inferred, ask one concise question before editing.

Scope First

Before reading broadly, identify the refactor scope. If the user did not provide enough information and it cannot be safely inferred, ask at most 2-3 concise questions.

Required inputs:

• target path or subsystem,
• artifact type to inspect,
• mode: scan/report only or implement obvious low-risk promotions.

Useful optional inputs:

• tech stack,
• known shared surfaces,
• validation command,
• search budget: narrow, medium, or broad,
• promotion threshold, such as "appears in 2+ places with the same meaning."

Good scoping questions:

• "Which area should I inspect: frontend components, backend schemas, tests, fixtures, or docs?"
• "Should I only report shared-abstraction candidates, or also implement obvious low-risk promotions?"
• "What duplication type should I prioritize: styles, helpers, types, fixtures, or docs?"

If the user already provides enough scope, proceed without asking.

Workflow

1. Load only directly relevant local guidance, such as AGENTS.md and a subsystem architecture doc.
2. Inventory known shared surfaces in the target domain before inspecting many implementation files.
3. Search with tools first, preferably rg and file listings, to identify candidate repetition without loading every file.
4. Sample representative files from each candidate cluster instead of reading the whole subsystem.
5. Classify candidates as one of:
   • reuse existing shared primitive,
   • promote to shared primitive,
   • leave local because meaning differs,
   • defer for a broader refactor.
6. For each candidate, state why it is worth doing now or why it should wait.
7. If implementing, promote only obvious, low-risk abstractions whose meaning is stable across use sites.
8. Update affected call sites and tests.
9. Run the relevant validation command when code changes are made.
10. Update docs when the shared structure or durable convention changes.

Search Strategy

Prefer targeted searches over broad reading.

Examples:

rg -n "#[0-9a-fA-F]{3,8}|border-radius|font-weight|padding" apps/desktop/src/components
rg -n "interface .*Payload|type .*Status|Record<string" apps/desktop/src
rg -n "def .*|class .*|TypedDict|BaseModel" apps/backend/src
rg -n "expected|fixture|golden|must_not" . 

Use the searches as routing signals. Open only the files needed to confirm whether repetition has the same meaning.

Promotion Rules

Promote when:

• the same idea appears in multiple places,
• the shared meaning is clear,
• the shared name can be specific and honest,
• the change reduces future drift,
• validation is available or the change is documentation-only.

Do not promote when:

• code only looks similar but means different things,
• a shared abstraction would need vague names such as common, utils, or misc,
• the pattern is still changing rapidly,
• the promotion requires reading unrelated subsystems,
• the risk is high relative to the requested task.

When unsure, produce a short candidate report instead of implementing.

Mode Outputs

For scan mode, return:

• searched scope,
• shared surfaces checked,
• candidate abstractions,
• recommended action for each candidate,
• a brief "why now" or "why not yet" judgment for each candidate,
• files to inspect next,
• risks or reasons not to promote.

For implement mode, return:

• what was promoted,
• which shared layer now owns it,
• important call-site changes,
• validation run and result,
• any deferred candidates.

Context Discipline

Use narrow scope first:

• local file or component,
• domain shared primitives,
• one clearly similar neighboring implementation,
• broader scans only when the user explicitly asks for a refactor sweep.

If you discover likely duplication outside the requested scope, mention it as a follow-up rather than expanding the task silently.