Skip to content

ZenUml/conf-app / .claude/skills/refactoring

refactoring

Verified

Deletion-focused unification principles for consolidating duplicated code paths into one shared implementation — what to optimize for, how to slice delivery, and the countable acceptance ledger. Use when planning, designing, executing, or reviewing a consolidation/unification refactor, when decomposing one into slices or PRs, and when writing subagent prompts for any refactoring task (carry the Principles section verbatim into those prompts).

Deletion-Focused Unification Refactoring

Not general refactoring advice. These are the standing rules for consolidation/unification work in this repo, distilled from the content-opening unification design (2026-07-31) and the rejection of PR #423.

Principles

Carry this section verbatim into every subagent prompt for refactoring work:

  • Consistency and structural simplicity are the primary goals.
  • When current code paths behave differently, choose one reasonable rule instead of preserving every historical variation with hooks and adapters.
  • Small user-visible changes are acceptable if they result naturally from that simplification.
  • Do not add states, fallbacks, telemetry, recovery UI, or other code merely to make behavior "better".
  • Preserve only hard requirements such as data integrity, authorization/paywall enforcement, and essential content compatibility.
  • Success means fewer concepts, fewer branches, and preferably less production code — not perfect behavioral equivalence.

Delivery rules

  • Vertical slices only. Every PR migrates a real production path AND deletes that path's old implementation in the same PR. No framework-only or foundation-first PRs. Encoding differences through lifecycle/adapter/hook infrastructure instead of eliminating them is the failure mode (PR #423: net +852 production LOC, closed for exactly this).
  • Evolve the existing shared module into the unified one; do not found a new abstraction beside it. If a partial consolidation already exists, it is the successor's seed, not a competitor to delete around.
  • Differences may live in exactly three places: a small policy enum (e.g. read vs write), a per-family declarative spec, or the presenter. A family/type branch inside the shared code means the design failed — fix the design, don't add an if.
  • Replace shared-mutable-state coupling with a typed hand-off value (e.g. a load→save origin contract). If two "independent" slices communicate through module state, they are one slice.
  • Verify before designing. Every factual claim about the current code gets file:line evidence against current main — not a stale branch checkout. Check for concurrent worktrees and already-adopted design docs touching the same files before committing to a direction.

Acceptance: the countable ledger

Net production LOC may be modestly positive only when a before/after ledger of countable structure shrinks — number of implementations of the concept, number of variants of the same decision, copies of each rule, whole files deleted. If no ledger row shrinks, the refactor didn't happen; LOC alone is neither proof nor disproof.

brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 319kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 196kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 196kUpdated Claude CodeCodexVerifiedInstall