Better Duplication

Remove repeated knowledge, not every repeated line

Treat duplication as a change-coupling problem. Two blocks deserve one source of truth when they represent the same knowledge and should change for the same reason.

Own repeated knowledge

Own findings where a rule, decision, invariant, mapping, validation, transformation, schema, or workflow is encoded in multiple places.

Do not own general system boundaries, local readability, or speculative generality. Coordinate with better-architecture, better-maintainability, and better-simplicity when the proposed extraction changes those concerns.

Review workflow

1. Find candidates

Search for exact and near duplication, but also inspect conceptually repeated behavior that uses different syntax. Useful candidates include:

• business rules repeated across entry points;
• authorization, validation, pricing, state transition, or eligibility logic;
• mappings and data transformations that must stay synchronized;
• constants, schemas, protocol values, or error classification copied across modules;
• copy-pasted orchestration with small divergent fixes;
• parallel implementations whose tests describe the same contract;
• duplicated test setup that obscures intent or makes policy changes expensive.

Treat clone detectors and textual search as discovery tools, not verdicts.

2. Classify the relationship

Classify each candidate:

• Shared knowledge: the same rule or contract appears more than once.
• Structural repetition: the same mechanical shape recurs but represents different concepts.
• Coincidental similarity: code looks alike now but has independent reasons to change.
• Intentional duplication: separation protects ownership, deployment, performance, compatibility, or failure isolation.
• Premature abstraction: existing shared machinery forces unrelated cases together.

Ask whether the locations should change together when the underlying requirement changes. If the answer is unclear, inspect names, owners, tests, call sites, and history before extracting.

3. Measure the cost

Show at least one credible cost:

• implementations have already drifted;
• one change requires coordinated edits;
• a rule is inconsistently tested;
• a defect was fixed in one copy only;
• consumers cannot tell which copy is authoritative;
• the abstraction itself has conditionals or flags for unrelated concepts.

Repetition that is small, stable, obvious, and independently owned may be cheaper than shared indirection.

4. Choose the correction

Prefer corrections in this order:

1. Name the shared rule or value in its owning module.
2. Extract a narrow pure function or data definition.
3. Centralize policy while leaving transport-specific mechanics local.
4. Share a behavioral contract or test suite when implementations must remain separate.
5. Parameterize only true variation with a small, closed set of options.
6. Keep the duplication when the concepts or change reasons differ.

Avoid generic utils, base classes, large option objects, inheritance, or callback frameworks that merely hide the copies.

Evidence requirements

For every finding:

• cite every representative location with exact lines;
• name the repeated knowledge, not just the matching syntax;
• show why the locations should change together;
• show drift or coordination cost when available;
• propose an owner for the shared concept;
• explain why the extraction is safer than leaving the duplication;
• define tests that protect the shared rule and legitimate variations.

A copy count alone is not sufficient.

Implementation rules

When asked to implement:

• capture current variations in tests before merging paths;
• extract the smallest stable concept;
• migrate one caller at a time;
• delete old copies only after every caller is verified;
• preserve distinct error, transaction, and performance behavior unless explicitly unified;
• reject the extraction if parameters, flags, or type branching grow to encode unrelated cases.

Standalone review output

When invoked directly, return:

1. Scope and candidate search — files, concepts, and tools inspected.
2. Findings — repeated knowledge, locations, drift or coordination cost, confidence, change risk, and smallest correction.
3. Intentional duplication — candidates that should remain separate.
4. Unsafe abstractions — shared code that should be split when evidenced.
5. Verification — tests or checks for common and variant behavior.

If only harmless or intentional repetition is found, state No actionable duplication findings.

Guardrails

• Duplication is sometimes cheaper than the wrong abstraction.
• Never extract solely because blocks look alike.
• Never force different domain concepts through one option-heavy helper.
• Never centralize code across ownership or deployment boundaries without weighing the coupling.
• Never replace readable local code with a generic framework for a small line reduction.
• Never erase legitimate variations while consolidating a common rule.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: NicolasYusim
• Source: NicolasYusim/better-codebase
• License: MIT

Install and usage instructions live in the source repository linked above.