Imported from keejkrej/rewrite-skill (skills/rewrite-assess/SKILL.md). Install upstream with npx skills add keejkrej/rewrite-skill --skill rewrite-assess. Copyright stays with the author.

Assess a repository rewrite

Treat a rewrite as a falsifiable investment thesis, not an implementation preference. Determine whether it attacks measured strategic pain, whether compatibility can be proved, and whether expected gains can be attributed rather than merely observed after a large bundle of changes.

Read bootstrap protocol/schemas, then require byte/digest equality for every state-pinned protocol/suite/fingerprint-tool resource. Continue from pinned assess skill/template, source synthesis, and attribution resources. Repository evidence controls when the essays disagree.

Keep the assessment boundary

Own only one uniquely named immutable package per invocation:

• .rewrite/assessments/<assessment-id>/decision.md: the decision record and phase handoff;
• .rewrite/assessments/<assessment-id>/probes/: disposable evidence, commands, raw results, and probe reports;
• .rewrite/assessment.md: a pointer-only index refreshed after publication, never gate authority.

Generate a unique assessment ID before writing and never overwrite or reuse a published package.

Follow the shared protocol for state changes. Do not create preparation, execution, proof, or rollout artifacts. Do not port a production module or turn a probe into the first migration batch. This suite never merges source, publishes or releases an artifact, deploys a new artifact, changes exposure in assessment, or retires the incumbent. A code probe must be isolated under the owned probe evidence, time-boxed, reversible, explicitly disposable, absent from the production dependency graph, and outside the canonical product/source closure.

At entry, require a fresh non-null route.dispatch_token, route.work_item: null, and the matching active dispatch lease owned by this context; record the token, lease owner, path, and digest. Record the canonical input closure. At publication, record the equal output revision and same token, validate/freeze the lease, and consume it through the journaled transaction. Any unexplained source mismatch invalidates publication. Consume the exact route predecessor unless this is initial/reset assessment. For reset, verify chain-reset evidence, use no predecessor, retain prior artifacts only as history, and reassess without carrying a pass. Keep state/source revisions distinct and bind conclusions to exact revisions, scope, requirements, and cutoff.

Answer three questions independently

Do not let a strong answer to one question stand in for another.

1. Should we rewrite? Answer YES, NO, or DEFER. Require measurable strategic pain, a causal diagnosis, and evidence that rewriting beats credible incumbent remediation and narrower alternatives.
2. Can equivalence be demonstrated? Answer YES, NO, or DEFER. Inspect compatibility surfaces, independent oracles, historical and production corpora, supported modes, and acceptable divergences. A large green suite is not automatically a complete oracle.
3. Which gains are attributable? List only gains isolated by a counterfactual or mechanism. Label every other benefit HYPOTHESIS, MIXED EFFECT, or NOT DEMONSTRATED. Include regressions and costs. An attribution plan is not evidence that a gain exists.

A decisive DEFER forces the overall verdict to PROBE; uncertainty never produces a proceed verdict. If no safe, affordable probe can resolve a decisive unknown, use STOP and state what future evidence could reopen the decision.

Build the decision case

1. Frame the decision and thresholds

Record the current implementation, proposed target, boundaries, users, compatibility obligations, non-goals, horizon, risk tolerance, and decision owner. Convert aspirations into thresholds: incident reduction, security class eliminated, latency or throughput, memory, clean and incremental build time, artifact size, delivery lead time, staffing, platform coverage, and total migration and dual-maintenance cost.

Name evidence that would make the proposal fail. Reject “modernize,” “clean up,” or “the target is safer/faster” until they become measurable and repository-specific.

2. Diagnose causes before choosing a treatment

Classify representative incidents, regressions, delays, and maintenance work. Trace them to language-permitted invalid states, unsafe or foreign boundaries, architecture, local conventions, missing ownership, weak review, absent tests, build configuration, dependencies, process, staffing, or cleanup debt.

For each important failure class:

• reproduce it or cite durable incident evidence;
• show whether the target structurally prevents it, detects it earlier, or leaves it possible through unsafe code, FFI, reflection, generated code, or misuse;
• estimate how much affected code lies inside that protection;
• separate the language mechanism from engineering attention spent during a rewrite.

Do not infer a universal language verdict from one repository's practices. Do not infer that poor practices disprove a useful target-language guarantee.

3. Test the incumbent-remediation counterfactual

Compare the rewrite with focused repair under comparable engineering effort. Investigate:

• ownership/lifetime conventions, safer libraries, boundary isolation, and subsystem replacement;
• sanitizers, fuzzers, static analysis, mutation/characterization tests, and stronger review;
• compiler, linker, LTO, profile, allocator, packaging, dependency, and build settings available to the incumbent;
• modularization, generated/dead-code cleanup, and narrow algorithm or data-layout changes;
• current toolchain and ecosystem-maintainer advice, including application cost and risk.

Record advice tried, declined, or unavailable and why. Use a time-boxed repair experiment when it can cheaply show whether the incumbent crosses the threshold. Do not credit the target with improvements the incumbent achieves under the same configuration or cleanup.

4. Assess feasibility and readiness

Inspect target compiler/toolchain maturity on every supported platform and mode; team proficiency, reviewers, hiring, operations, and ownership; dependency, licensing, supply-chain, FFI/ABI, generated-code, plugin, persistence, and deployment constraints; source quality and architecture; target escape hatches and expected unsafe/foreign share; capacity, schedule, resource limits, feature work, and opportunity cost.

Rate technical, quality, and organizational readiness separately. Missing enthusiasm is not proof of infeasibility; missing owners, platform support, or maintainable dependencies can be.

5. Audit compatibility and oracle quality

Inventory APIs, protocols, files, data, CLI behavior, errors, ordering, timing, resource lifetimes, observability, security controls, supported platforms, undocumented behavior, and relied-on bugs.

For critical behavior, identify an independent oracle: differential execution, a standards suite, stable goldens, downstream conformance, property/model tests, historical incidents, production replay, fuzzing, or a separate reference. Record discovered, selected, passed, failed, skipped, filtered, flaky, and missing tests. Compile success and exit status without selection evidence do not establish equivalence.

If required behavior cannot be observed or compared at acceptable cost, answer equivalence NO or DEFER; do not approve on faith that tests can be added later.

6. Compare alternatives and migration shapes

Compare at least: focused hardening/no rewrite, isolated subsystem replacement, incremental/strangler migration, and full mechanical port. Add other targets or architectures that fit the diagnosed cause.

Evaluate seams, cycles, bridge and schema complexity, integration feedback, drift while both trees change, feature freeze, opportunity cost, temporary and permanent dual maintenance, rollout granularity, rollback, and retirement. Full replacement avoids some bridge cost but concentrates integration and reversal risk. Incremental replacement limits blast radius only when a credible seam and oracle exist.

7. Make attribution hypotheses testable

Pre-register every decision-driving claim with a metric, threshold, matched controls, raw-evidence path, plausible classes, counterfactual, and negative surfaces. Include runtime, memory, artifact size, CI reliability, clean build, and representative incremental edit-build measurements when relevant.

Use the canonical causal classes from manifest resource ref.attribution: LANGUAGE_GUARANTEE, TOOLCHAIN_CONFIG, MECHANICAL_CLEANUP, LATER_OPTIMIZATION, INSTRUMENTATION_CHANGE, and ENGINEERING_EFFORT. Prefer incumbent/candidate ablations, a backport, or a factorial comparison. Narrow unresolved bundles to “observed in the candidate.”

8. Run the cheapest falsifying probe

Choose the smallest probe that can overturn the preferred decision, not a showcase likely to succeed. State one decisive question, prediction, failure threshold, exact procedure, representative inputs, time/resource cap, owner, and how each outcome changes the verdict.

Prefer measurements, oracle audits, platform/dependency spikes, incumbent-hardening experiments, or seam simulations over translation. If translation is necessary, use a disposable slice that exercises a representative hard boundary. Save results under the current immutable assessment package's probes/ directory, record confounders and negative outcomes, and discard or quarantine probe code. Never promote it into production migration.

Select exactly one verdict

• STOP: pain does not justify rewriting; the diagnosed cause is not addressed; an incumbent or narrower remedy dominates; target feasibility, equivalence, rollout, or reversal is unacceptable; or decisive evidence cannot be obtained affordably.
• PROBE: at least one decisive answer is DEFER and a bounded falsifying probe can resolve it. Name the probe and prohibit preparation until reassessment consumes its evidence.
• PROCEED_INCREMENTALLY: the case survives the counterfactual, equivalence is demonstrable at stable seams, target and team are ready, attribution can be controlled, and bounded rollout/reversal reduce risk.
• PROCEED_FULL: all proceed gates pass and repository evidence shows a full mechanical port is safer or cheaper than bridge-driven alternatives despite concentrated risk. Require strong whole-system oracles, drift control, capacity, rollback, and an explanation of why incremental shapes lose. Treat this as exceptional.

Confidence is LOW, MEDIUM, or HIGH and reflects evidence quality; it never relaxes a gate. Record dissent, negative evidence, risks, waivers, and approvers. A waiver may accept a non-decisive risk but cannot waive an unknown root cause, absent critical oracle, unsupported target, or impossible reversal.

Emit a revision-bound handoff

Write .rewrite/assessments/<assessment-id>/decision.md from the template and make the state assess pointer name it. Its phase_status, transaction ID, and dispatch token must match the committed publication journal and pointer. Publication atomically consumes and clears the route token. Refresh .rewrite/assessment.md only as a path/digest index. For STOP or PROBE, name the next allowed assessment action and prohibit preparation. For either proceed verdict, hand rewrite-prepare exact prerequisites rather than doing preparation:

• verdict, confidence, based_on_state_revision, recorded_at_state_revision, exact input_source_revision, exact output source_revision, scope, target, and shape;
• thresholds and causal evidence;
• compatibility surfaces, oracle inventory, gaps preparation must close, and required corpora/baselines;
• target/toolchain/dependency/platform constraints and owners;
• attribution hypotheses, incumbent-counterfactual results, risks, waivers, rollout/reversal constraints, and expiry;
• evidence paths and changes that invalidate the verdict.

Normalize the phase result exactly:

• STOP -> gate FAIL, owner_phase: assess; stop unless new evidence justifies reassessment.
• PROBE -> gate DEFER, owner_phase: assess; run only the named probe and reassess.
• PROCEED_INCREMENTALLY or PROCEED_FULL -> gate PASS, owner_phase: null; the router may next select prepare.

The terminal handoff must list consumed pointer inputs and owned supporting artifacts by path and digest, and must not contain its own decision.md path or hash. A proceed PASS opens preparation only. It does not authorize production porting, scaling, merge, artifact publication or release, deployment, exposure, cutover, or incumbent retirement.