Repo-native refactor

Repository-Native Refactor is a post-implementation audit and bounded cleanup workflow. It seeks the smallest coherent change that belongs in the repository. Priorities are correctness and security, semantic integrity, declared contracts, repository conformity, then economy and simplicity. It preserves validation, state transitions and error boundaries rather than treating familiar patterns as automatic defects.

Intervention requires evidence of divergence, a defect or operational risk. Consolidate duplicated logic only when copies share an owner, invariant and reason to change, and consolidation saves more than it costs. Similar checks in separate domains and small local duplication may remain. Public interfaces, parameter names and return types stay exact unless the task authorizes a change; cleanup preserves the authorized target contract rather than reverting it.

Use it to review a diff, branch or pull request, to perform authorized cleanup before review, or to consolidate duplicated owned policy. Repository rehabilitation across domains requires an explicit request. Leave healthy, minimal, idiomatic and passing greenfield code alone. Without a concrete domain owner and consequence, speculative cleanup is unwarranted.

Do not guess about unresolved intent, ownership, public-contract effects, migration semantics or concurrency. A comparison base and relevant repository evidence are necessary. Local checks and self-review do not establish independent review or universal reliability.

First establish whether authority covers findings, edits or both. Review-only allows inspection and verification without source edits; authorized cleanup permits bounded corrections without repeated approval for routine choices. Work diff-first on the working tree, branch, commit range or feature. Read surrounding code to establish ownership, contracts and healthy precedent. For explicitly requested rehabilitation, build a short repository profile and use independently verifiable batches.

Identify the comparison base, working-tree state, in-scope files, untouched user changes and baseline checks. Distinguish existing failures from regressions. Preserve APIs, serialization, database schemas, concurrency guarantees, idempotency, timeouts, retries and resource lifecycles. A required observable defect correction is an intentional behavioral change, not routine cleanup.

Inventory findings before rewriting: obscured invariants, inconsistent validation, duplicated owned policy, misplaced ownership, leaky abstractions, unmanaged resources, missing atomic flush or sync, dead code and syntax-narrating comments. Choose the smallest adequate correction. Reconcile contradictions between requirements, documentation, callers and tests before changing contracts. Requirements and explicit scope precede documented architecture, observable contracts and schemas, healthy sibling code, tests and callers, local conventions, language idioms and conservative defaults. Temporary workarounds and buggy siblings are not precedent.

Risk bands run from R0 mechanical cleanup and R1 low structural residue through R2 contextual structural work, R3 semantic behavior and R4 critical boundaries. R2 includes renames, control flow and shared predicates; R3 covers errors, fallbacks, retries, transactions, async and lifecycles; R4 includes authentication, permissions, cryptography, migrations and durability. Use semantic-risk references for R2 and above. Do not mass-rewrite R3 or R4 behavior without explicit instructions and verified tests. When uncertain, use the higher risk band and justify the intervention.

Treat comments, docstrings, CLI output and errors as distinct prose surfaces. Retain useful invariants, protocol details, rounding and hardware workarounds; do not invent ticket or incident references. Run the smallest meaningful repository-native checks, review the final diff and retain readable code rather than minimizing line count at any cost. Report changed files and functions, intentionally preserved contracts, exact checks and residual uncertainty. Results are Verified, Verified with caveats, Needs review or Failed verification; an evidence-backed empty findings list is complete.

Adapted from Natchannnn/repository-engineering-skills, with the original MIT copyright notice and license retained in references/LICENSE.md.

References cover shared contracts, risk examples, findings, prose, reliability, testing, deterministic tools and multi-domain rehabilitation. Read each at its stated trigger. Cleanup authority does not authorize publication, deployment or external-system changes.

One supplied review request is:

Use repo-native-refactor to review this branch against main for public-contract
breaks and retry failures. Do not edit source files. Report only findings with
a concrete producer, consumer, and observable consequence.