@crossplatformai/skills/skills/post-build-ship/references/engineering-judgment.md

Reusable Agent Skills for CrossPlatform.ai projects.

# Engineering Judgment

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

Use this reference when `post`, `build`, or `ship` is already active and the work involves lint, design-system, test, repository-convention, compatibility, adapter, alias, shim, suppression, workaround decisions, legacy code, outdated process flow, backward-compatibility behavior, or old migration paths.

This reference supplements Post.Build.Ship. It must preserve Authorizing User authority, observable
acceptance, material boundaries, fail-fast approvals, proportionate QA, hunk ownership, and Ship
safety. It adds no mandatory review or presentation fields.

## Baler Twine And Jumper Cables

`Baler Twine and Jumper Cables` describes a solution that works under real constraints but is harder to follow than the clean design would be. It is honest constrained pragmatism: visible, explainable, and chosen because time, platform limits, dependency behavior, migration risk, or compatibility constraints made the clean path unavailable or unsafe.

It is legitimate when:

1. the constraint is real and named
2. the workaround is the smallest safe thing
3. the debt is visible rather than disguised
4. the code still fails loudly on unexpected cases
5. a clean alternative is unavailable, unsafe, or explicitly out of scope

It is a smell when a clean alternative exists. Do not use the phrase to justify unclear code, hidden debt, broad shims, compatibility layers, aliases, suppressions, or confusing names that only avoid fixing the real issue.

## Technicalities And Specification Gaming

Technicalities or specification gaming happen when the implementation optimizes for a proxy, such as `lint passes`, `the matcher no longer sees the string`, `the test no longer fails`, or `the handoff technically says yes`, while violating the rule's purpose.

When a check blocks work, ask what behavior the rule is trying to prevent and fix that behavior. Prefer the simplest intent-aligned change over machinery that only makes the check quiet.

Examples of specification gaming:

1. renaming a value only so a lint matcher no longer recognizes it, while preserving the forbidden behavior
2. wrapping a forbidden variant in a constant such as `WHITE_BUTTON_VARIANT = 'white'` and block-disabling ESLint around the assignment
3. adding an adapter, alias, or compatibility shim that hides the real mismatch when a direct semantic fix is available
4. changing a test to assert the workaround instead of the intended behavior
5. treating a repo rule's wording as a loophole when the intended convention is clear

The `WHITE_BUTTON_VARIANT = 'white'` pattern is an anti-pattern because it camouflages a workaround as compliance. If the intent is to avoid a raw `white` visual treatment in a design-system variant, fix the variant semantics or component API directly when possible. A truthful semantic variant such as `elevated` is appropriate only when `elevated` accurately describes the component's actual UI role and treatment. A fake semantic rename made only to evade a matcher is also specification gaming.

Design-token examples in this reference are illustrative, not a new universal rule. Apply the target repo's actual design-system policy and the purpose of the specific check.

## Honest Hacks And Suppressions

Hacks and suppressions are sometimes valid. They must be honest.

Use a suppression only when the rule is genuinely wrong for the case, the clean semantic fix is unavailable or worse, and the explanation names the real reason. Do not use suppressions as a convenience to avoid a small clean fix.

If a hack is necessary:

1. keep it narrow
2. make it visible
3. name the constraint honestly
4. avoid broad compatibility machinery when a local exception is enough
5. avoid local exceptions when a simple semantic fix is available

Semantic renames are valid only when the new name truthfully describes the thing. Renaming `white` to `elevated`, `primary`, `surface`, or any other label is correct only if that label accurately describes the component's real meaning and behavior. Cosmetic string dodges are not semantic fixes.

## Legacy And Compatibility Cutover

Do not treat legacy code as load-bearing just because it is old or reflects a previous process. The default stance is that legacy paths, outdated process flows, backward-compatibility behavior, old migration paths, and compatibility layers are candidates for clean removal, not automatic preservation.

When in-scope work touches any of the following, surface the decision before acting:

1. legacy code or a deprecated module
2. an outdated process or workflow path
3. backward-compatibility behavior or a compatibility layer or shim
4. an old migration path or dual-write or dual-read bridge
5. branching that exists only to support an older format, version, or caller

Stop and ask the user one concise question: keep the legacy or compatibility path, or cut over cleanly to the new path?

Offer a recommendation when one is clear, but do not preserve, extend, or quietly route around the legacy path on assumption, and do not delete it on assumption either. Record the user's choice in scope or non-goals so the decision is intentional and traceable.

Relationship to `Fail Fast Over Fallbacks`: that policy governs masking failures; this rule governs whether legacy or compatibility behavior is preserved at all. A compatibility layer kept without an explicit keep decision is also an unapproved fallback.

When the user chooses a compatibility window, make the lifecycle explicit:

1. Separate the persisted schema version, the compatibility implementation, and
   the repository history. Keeping a version field does not justify keeping an
   old reader forever, and removing a reader does not erase its history.
2. Prefer read-time conversion with canonical writes. Do not rewrite files at
   startup, and do not add a dual-write mirror merely to make rollback feel
   easier; both choices can turn temporary compatibility into a permanent format.
3. Define the support window as `max(time, releases)` from the release that
   actually ships the compatibility behavior. Record that exact release at ship
   time; never infer it from a working-tree version or the newest existing tag.
4. Enumerate consumers before removal. Audit tracked files and repositories,
   identify what local or ignored files cannot be searched, and provide a local
   diagnostic or explicit owner check for that gap. Do not add telemetry by
   default when configuration content can contain paths, commands, or secrets.
5. Write down every compatibility threshold separately: which clients read the
   old shape, which read the canonical shape, which write each shape, and which
   rollback paths fail loudly or silently lose behavior.
6. Remove the bridge only when the time window, consumer audit, remediation path,
   and unresolved-report review all pass. Preserve strict validation for new
   writes and future versions, and make post-cutover errors name the affected
   resource and the required edit.

Tests for a compatibility window cover canonical idempotence, unchanged file
bytes and timestamps after load, local/shared precedence, malformed input,
future-version rejection before conversion, rollback-sensitive client skew, and
the removal error. The issue records the gates and the eventual removal scope;
the implementation does not preserve compatibility solely for historical
interest.

## Spirit Over Letter

Follow the spirit of repo rules, lint rules, design-system rules, tests, and handoff scope by preserving the behavior they are trying to protect.

When the written rule and inferred intent conflict, escalate instead of silently self-authorizing. State the conflict, the likely intent, the literal requirement, and the smallest safe options. Do not override explicit instructions based only on guessed intent.

Good engineering judgment means choosing the clear, boring, intent-aligned fix when it exists, and using baler-twine pragmatism only when the constraints are real enough to justify it.