@crossplatformai/skills/skills/post-build-ship/references/reuse-before-inventing.md

Reusable Agent Skills for CrossPlatform.ai projects.

# Reuse Before Inventing

This is a Post.Build.Ship reference, not a standalone skill.

Use this reference when a feature, defect, or refactor appears to need a new helper, abstraction,
platform branch, normalization layer, test-contract change, or adjacent runtime support before the
repository owner of the behavior is known.

This reference governs discovery and order of operations. It supplements Post.Build.Ship without
adding handoff fields, QA commands, gates, refusal conditions, or commit-message rules.

## Discovery Before Design

Capture the exact failure contract before proposing a solution: the caller-supplied input, observed
output, expected output, failing assertion, and the boundary where the representation changes.

Search primitives, siblings, tests, and history before designing a new mechanism.

Use this order:

1. Search existing helpers, primitives, types, conventions, and vocabulary by concept, not only by
   the failing string or file name.
2. Inspect sibling implementations and call sites that already produce or consume the same concept.
3. Read analogous tests, fixtures, snapshots, and assertions to identify the repository contract.
4. Use `git log -S '<symbol-or-contract>' -- <paths>` to find when the concept entered or changed.
5. Use blame and nearby history to recover intent when the current code does not explain ownership.
6. Name the primitive, convention, module, or boundary that owns the concept and the call sites that
   compose it incorrectly.

Identify the repository owner of the concept before adding an abstraction.

If no owner exists, record the searches and evidence that justify creating one. A new abstraction
should follow failed discovery, not replace it.

## Separate Representations

Separate logical caller values, native host resources, and downstream runtime representations.

1. **Caller-supplied logical values** may intentionally carry a path flavor, identifier form, or
   protocol representation that differs from the current host. Preserve that contract unless the
   owning boundary says otherwise.
2. **Native host resources** are physical files or directories created and consumed on the current
   machine. Use native host APIs for those resources when the repository contract requires them.
3. **Downstream shell, protocol, or runtime values** belong to the boundary that prepares values for
   that consumer. Reuse its existing conversion or composition primitive.

Do not normalize all three categories because one host exposed a mismatch. A physical temporary
file can require native joining while a caller-supplied POSIX path in the same function must remain
POSIX for a downstream shell.

## Compose The Existing Owner

Prefer composing the existing owner at incorrect call sites.

Keep the fix at the boundary that bypassed, duplicated, or misused the owner. Extend the owner only
when repository evidence shows its contract is incomplete, and add a new owner only when discovery
shows none exists.

Existing tests are contracts unless repository evidence proves them wrong.

Do not normalize an assertion first. Check whether the fixture intentionally specifies a
representation or path flavor. Preserve tests when the implementation failed to use the repository
owner; change them only when history, sibling behavior, or an explicit product contract proves the
expectation is wrong.

## Scope Brake

Stop and investigate again when a narrow defect starts adding any of these:

1. new helpers, abstractions, adapters, or normalization machinery
2. explicit platform branches or host detection
3. relaxed assertions, rewritten fixtures, or broader test changes
4. adjacent shell, runtime, protocol, or platform support
5. changes across more than two or three implementation files

Treat more than two or three implementation files as a reinvestigation signal, not a hard limit or
refusal rule. Broad changes can be correct, but unexplained growth should trigger another ownership
search, a minimum-diff comparison, and a written reason for the expansion.

## Example

Two path-separator failures on Windows initially suggested normalization machinery and additional
platform handling. The repository already had a host-flavor-aware path joiner. Reusing it at two
incorrect production call sites fixed the contract, kept native joining for physical temporary
files, and required no test changes. The lesson is not Windows-specific: find the representation
owner before designing around the symptom.

## Phase Responsibilities

### Post

Record the discovered owner, the minimum implementation scope, rejected expansion, and the tests,
sibling code, or history that support the plan. If ownership is still unknown, keep discovery open
instead of presenting new machinery as the default design.

### Build

Rerun the scope brake before adding a helper, platform branch, normalization layer, adjacent runtime
support, or test change. Prefer composing the discovered owner at the incorrect call sites and keep
representation-specific operations at their owning boundaries.

### Ship

Perform a read-only staged-diff cross-check. Flag unexplained abstractions, weakened tests, adjacent
support, or scope disproportionate to the failure contract. Use existing handoff fields and refusal
conditions; do not create a new Ship gate or mirrored metadata.

## Relationship To Other References

- `host-portability.md` decides whether code, tests, and tooling preserve their contract across host
  operating systems.
- `elegant-code.md` evaluates abstraction quality, duplication, and whether the resulting design is
  simple and powerful.
- `engineering-judgment.md` evaluates workarounds, suppressions, compatibility paths, and fidelity
  to a rule's intent.
- This reference decides what to inspect first and who already owns the concept before any of those
  implementation judgments expand the design.