Restore the Tool Before You Chase Zero Findings

When a framework removes a familiar developer command, the visible failure often looks like a one-line script fix. It rarely is. The real work is usually a small tooling migration with several coupled defects—and a design decision about what "fixed" actually means.

The problem

The symptom was simple: a lint command that used to work was gone. The framework had removed its wrapper, and the package script still pointed at the old entry point.

That was the surface. Underneath sat a chain of problems that only surfaced once someone looked past the missing script:

• no repository lint configuration in the format the current toolchain expects
• a major-version mismatch between the linter and its framework preset
• a root dependency version incompatible with part of the lint dependency graph
• obsolete framework configuration that the new toolchain no longer supports
• canonical engineering documentation still describing the old command

Classifying this as "fix the script" would have missed most of the work—and invited the wrong fix.

What actually happened

The baseline audit added real value. It mapped the dependency graph, confirmed which configuration formats were invalid, located the authoritative documentation, and separated what this item needed to do from unrelated repository debt.

The scope stayed tight despite the hidden complexity. The product change touched only package management, lint configuration, framework configuration, and engineering documentation. No application source, CI workflow, deployment configuration, or unrelated dependency was changed.

The most important design decision was separating restoring lint execution from making lint pass. The finished command correctly exits non-zero because it now exposes hundreds of existing findings—errors and warnings that were always there but no longer hidden behind a broken command. Treating that as an acceptable outcome prevented the item from expanding into a large, unrelated cleanup.

The fix was structural rather than cosmetic:

• the supported linter CLI now runs
• the flat configuration loads
• the required framework presets are applied
• the peer dependency graph is valid
• generated outputs are explicitly ignored in configuration
• obsolete framework settings and documentation were corrected
• the old "invalid project directory" failure was removed

A minimal dependency upgrade was a legitimate hidden repair, not scope creep. It was constrained to a compatible minor version, and the unit suite and build passed without requiring application changes.

Verification needed to prove more than command success. Listing ignore patterns in configuration is not the same as proving generated paths are actually excluded. Targeted probes against the ignore logic were part of the acceptance evidence.

Residual risks were correctly kept outside the item: the backlog of existing findings, the absence of CI enforcement, and the fact that the restored command still exits with a failure code. Those are real follow-up concerns—but they are separate decisions.

The lesson

A removed framework command can expose dependency drift, missing configuration, generated-file leakage, and stale documentation simultaneously. The investigation should inspect all of those surfaces before classifying the change as mechanical.

Three goals that look similar are not the same goal:

1. Restore tool execution — the command runs, loads config, and produces genuine output.
2. Produce a baseline — capture what the working tool reports today before any remediation policy.
3. Enforce a clean gate — the command exits zero, ideally in CI.

Do not combine them by default. A working lint mechanism with a non-zero exit can be a correct, complete implementation of goal one—and a necessary prerequisite to goal two.

The broader principle

Framework tooling repairs are often deeper than their visible error. What looks like "the script is wrong" is frequently "the toolchain moved, and several coupled surfaces did not move with it."

For similar upgrades, start with a bounded compatibility audit covering:

• command removal and its replacement
• configuration format migration
• peer dependencies and version constraints
• generated-artifact handling (configuration ignores, not just version-control ignores)
• build integration and what the build no longer enforces implicitly
• canonical documentation and CI enforcement status

Define up front whether the goal is restore, baseline, or enforce. Use an explicit file allowlist and prohibit opportunistic cleanup—rule suppression, severity reduction, broad dependency upgrades, and unrelated refactors are how small repairs become large ones.

For dependency repairs, require the smallest compatible version change, a clean dependency tree check, lockfile containment review, and reruns of existing tests and build.

Verify ignored paths behaviourally, not only by inspecting configuration.

Negative constraints can be as important as positive requirements. "Do not suppress, weaken, or opportunistically clean up" is often what keeps a tooling migration honest.

How to apply it

When you inherit a broken or removed developer command:

1. Audit before you fix. Map commands, config formats, peer dependencies, generated outputs, docs, and CI in one pass.
2. Choose the goal explicitly. Restore execution, baseline findings, or enforce zero exit—pick one primary outcome for this item.
3. Scope with an allowlist. Name the files that may change. Everything else is out of scope unless a hidden dependency forces a minimal, documented repair.
4. Accept non-zero exit when appropriate. If the tool now works and surfaces pre-existing debt, that is progress—not failure.
5. Verify behaviourally. Prove ignores, presets, and command paths with probes, not just config inspection.
6. Schedule follow-ups separately. Backlog remediation, CI enforcement, and policy decisions (zero errors, zero warnings, or no regression from baseline) deserve their own items—especially if adding CI now would install a permanently failing check.

A restored gate that tells the truth is more valuable than a green check that lies.