refactor

On-Refactor: Safe, Documented Codebase Refactoring

Improves code quality, performance, and security while preserving existing behavior. Every session ends with a REFACTOR-yyyy-mm-dd.md report.

Context Files

• rules/security-first.md
• rules/johnweek-stack.md
• rules/code-review-standards.md

Core Principles

1. No silent breaking changes. Any change to public APIs, exported interfaces, config formats, CLI args, DB schemas, or event contracts is breaking. Permitted only when unavoidable — each must be documented with migration instructions.
2. Behavior preservation. Same inputs → same outputs. Run tests before and after.
3. Incremental batches. Group changes by concern so each batch is reviewable.
4. Measure before optimizing. Back performance changes with profiling or reasoning.

---

Orochi-Specific Refactoring Concerns

ZK Circuit Refactoring

• Constraint count changes must be tracked. Any refactoring of ZK circuit code must document the constraint count before and after. Changes to constraint count directly affect proving time and prover memory usage.
• Never refactor circuits without re-running proof roundtrip tests. After any circuit change, run the full proof generation → verification roundtrip to confirm correctness.
• Do not alter public input/output structures without a migration plan — verifier contracts on-chain depend on these.
• Ensure witness generation remains deterministic after refactoring.

Cryptographic Code

• Never refactor cryptographic primitives without security review. Changes to hash functions, signature schemes, key derivation, or encryption must be reviewed for correctness and side-channel resistance.
• Maintain constant-time guarantees. Verify that refactored code still uses constant-time comparison (e.g., subtle crate). Do not introduce branching on secret data.
• Ensure zeroization of secrets is maintained (zeroize derive annotations must survive refactoring).
• Do not add Debug implementations on types that hold secret material.

Web3 Integration

• Contract ABIs are public API. Any change to Solidity ABIs, event signatures, or function selectors requires a migration plan — deployed contracts and indexers depend on these.
• Preserve chain ID validation logic — removing or weakening it is a security regression.
• Gas estimation logic changes must be tested against actual or forked chain state.
• Event listener patterns and topic filters must remain consistent with deployed contracts.

Cross-Language Boundaries

• Rust-to-Node.js FFI changes require coordinated updates. When refactoring Rust code exposed via napi-rs, wasm-bindgen, or similar, update the TypeScript type definitions and consumer code in the same batch.
• Serialization format changes (e.g., serde attributes) at FFI boundaries break JavaScript consumers silently — always test the full roundtrip.

---

Workflow

Phase 1 — Discovery & Analysis

1. Identify the stack. view the project root. Read config files to determine languages, frameworks, dependencies, and build system.
2. Locate and run tests. Find test dirs/configs. Execute the suite. Record the baseline (pass/fail/skip counts, coverage if available).
3. Scan for issues. Look for: dead code, duplication, complexity, naming problems, deprecated APIs, hardcoded secrets, missing error handling, N+1 queries, and vulnerability patterns (SQLi, XSS, path traversal).
4. Build a plan. Prioritize changes into four categories — Quality, Performance, Security, Modernize. For each change note: files affected, what/why, risk level, and whether it could break consumers.
5. Present plan to user. Wait for approval before proceeding.

Phase 2 — Execution

Read references/refactor-checklist.md for per-language guidance before starting.

Rules:

• Work in batches by category. Run the full test suite after each batch.
• Track every change: file, one-line summary, category, breaking yes/no.
• Before modifying any public contract, check if it has external consumers. If breaking is unavoidable, add a deprecation wrapper or flag it with migration steps.
• Do not mass-reformat files unless the user requests it.

Phase 3 — Validation

1. Run the full test suite. Compare against Phase 1 baseline — fix any regressions.
2. Run linters/formatters if configured. Fix new warnings.
3. Run security audit tooling if available. Confirm no new vulnerabilities.

Phase 4 — Documentation

Read references/report-template.md for the exact template.

Generate REFACTOR-yyyy-mm-dd.md in the project root containing:

• Baseline snapshot (pre-refactor metrics)
• Changes table (every change with file, category, description, breaking flag)
• Breaking changes section with migration instructions for each
• Post-refactor results compared to baseline
• Recommendations for future work

Present the report to the user.

---

Edge Cases

• No tests: Warn user of higher risk. Offer to write smoke tests first.
• Monorepo: Scope to specific packages. Treat package boundaries as public contracts.
• Partial scope: Run only the categories the user requests.
• Massive codebase: Prioritize highest-impact files. Document what was deferred.
• Conflicting goals: Flag tradeoffs to the user and let them decide.

Reference Files

• references/refactor-checklist.md — Per-language checklists for Quality, Performance, Security, and Modernize changes, plus Orochi-specific items. Read before Phase 2.
• references/report-template.md — Markdown template for the final report. Read before Phase 4.