Repo-native refactor

When to Use

• Use when the user asks to review a diff, branch, or PR for correctness, contract breaks, or operational risk.
• Use when the user authorizes bounded cleanup before opening a PR or asks to consolidate duplicated policy with shared ownership.
• Use for repository rehabilitation only when the user explicitly requests work across multiple domains.
• Establish review-only, edit, or combined authority before choosing the operating mode.

Produce the smallest coherent change that belongs naturally in the target repository.

Prioritize in order:

1. Correctness and security: prevent regressions, avoid new security vulnerabilities, handle boundary conditions.
2. Semantic integrity: preserve existing invariants, state transitions, validation, and error boundaries.
3. Contracts stay as declared: the rule lives in references/shared-contracts.md §1. Preserve the authorized target contract; otherwise keep exact declared types. Internal helpers are fine when exposed contracts stay exact.
4. Repository conformity: match surrounding naming, domain conventions, and architectural precedents.
5. Economy and simplicity: minimal intervention. Delete dead weight, avoid premature abstractions.

This is a post-implementation audit and small cleanup skill. It is not permission to redesign the repository. Establish a concrete consequence such as inconsistent behavior, duplicated policy that must change together, unclear ownership, avoidable resource cost, or a demonstrated maintenance obstacle. Leave healthy code unchanged when the benefit is speculative.

Minimal intervention and evidence gate

• Evidence-based intervention: refactor only with concrete evidence of divergence, defect, or operational risk. If greenfield code or an additive diff is already minimal, idiomatic, and passing, leave it. A pattern you recognize is a candidate finding, not a reason to change anything.
• Semantic DRY (Cost-benefit consolidation): merge duplicated logic only when the copies share an owner, an invariant, and a reason to change, and only if merging saves more than it costs. Leave similar-looking checks in separate domains alone, and keep small local duplication when merging would obscure ownership.
• Contract boundary protection: preserve public interfaces, parameter names, and return types, except where the task clearly authorizes the change. During cleanup, keep the authorized target contract; don't revert to the old one.

Operating modes

• Review vs. Refactor Authority: first establish the outcome: findings, edits, or both. Review-only means inspection and verification, no source edits. Authorized cleanup allows bounded corrections; don't ask approval again for routine choices.
• Change-set cleanup: for a working tree, branch, commit range, feature, or bounded checkpoint. Work diff-first; read surrounding code only to understand ownership, contracts, and precedent.
• Repository rehabilitation: only when explicitly requested across multiple domains. Read repository rehabilitation, build a short profile, and work in batches you can verify independently.

Evidence hierarchy

Use the evidence hierarchy to guide investigation, not to resolve material contradictions automatically. Reconcile conflicting requirements, documentation, callers, and tests before changing the affected contract. When repository patterns conflict, resolve in order:

1. User requirements and explicitly authorized scope.
2. Documented architecture and repository guidelines.
3. Observable public contracts and persisted schemas.
4. Healthy sibling code within the same domain and runtime boundary.
5. Relevant tests, schemas, callers, and dependencies.
6. Dominant local conventions.
7. Language and runtime idioms.
8. Conservative, idiomatic defaults.

Never treat a temporary workaround, buggy sibling, or accidental pattern as precedent.

Workflow

1. Establish scope and baseline

Before mutating code, identify:

• Comparison base and working-tree state.
• In-scope files vs. untouched user modifications.
• Existing verification commands and their current pass/fail status.

Differentiate pre-existing failures from regressions introduced by this pass. Never claim a check ran when it did not.

2. Establish intent, ownership, and preservation

Refactoring is behavior-preserving by default. Protect:

…