Codebase Audit & Refactoring Workflow

A systematic workflow for auditing and improving the entire codebase.

Workflow

1. Audit
   → Dead code + duplicates + God Object + Parameter Bloat detection
2. Triage
   → Verdict: candidate / refactoring / defer, backed by caller evidence
3. Scope and plan
   → Record keep/change/delete decisions; tracking updates only when requested
4. Workspace Isolation
   → Worktree isolation
5. Implementation + Verification
   → Delete/extract/convert then lint + test
6. Docs-sync + authorized integration
   → CHANGELOG for functional changes; tracking docs follow their main-owned workflow

An audit alone does not authorize implementation, merge, global reinstall, or runtime restart. Use the canonical workflow for the requested scope; deploy or restart only when separately in scope.

Phase 1: Audit

Dead Code Detection

# Check import status per module
for f in $(find core/ -name "*.py" -not -name "__init__.py" -not -path "*__pycache__*"); do
    basename=$(basename $f .py)
    # Check using actual import path (basename match alone causes false positives)
    module_path=$(echo $f | sed 's/\.py$//' | tr '/' '.')
    count=$(grep -rn "from ${module_path}\|import ${module_path}" core/ --include="*.py" | grep -v "$f" | wc -l)
    if [ "$count" -eq 0 ]; then
        echo "CANDIDATE: $f ($(wc -l < $f) lines; no matching textual imports)"
    fi
done

Note: Search by full module path, not basename, to reduce false positives. This core-only text scan misses relative imports, outer-package callers, entrypoints, registries, public exports, and dynamic loading. Apply the deletion gate below before deciding that a module is unused.

Duplicate Function Detection

grep -rn "^def " core/ --include="*.py" | awk -F: '{split($NF,a," "); print a[2]}' | sort | uniq -c | sort -rn | head -10

Repeated names are discovery candidates, not proof of duplication. Trace full call paths and compare behavior; protocol methods and local helpers commonly share names legitimately.

God Object Detection (Kent Beck criteria)

find core/ -name "*.py" -not -path "*__pycache__*" -exec wc -l {} + | sort -rn | head -10

• Large files are candidates for responsibility tracing, not automatic splits.
• grep -c "^def " FILE counts top-level function declarations, not responsibilities. Trace callers, state ownership, and reasons to change before proposing a split.

Parameter Bloat Detection

grep -rn "def __init__" core/ --include="*.py" -A20 | grep -B1 "def __init__" | head -20
# Review call-site cohesion; parameter count alone is not a finding.

Phase 2: Triage

Classification	Criteria	Action
Deletion candidate	No textual imports found	Apply the agent anti-pattern deletion gate
Refactoring	Multiple proven responsibilities or drift paths	Use the smallest extraction that removes the failure
Defer	Planned for future use, or requires large-scale changes	Kanban Backlog

Before implementation, use the finding record to connect the violated contract, actual caller, counterexample, smallest correction and surviving oracle. Review entry/registration, persisted readers and failure branches; discovery counts are not findings. For deletion, apply the existing deletion gate. Similar setup does not make distinct provider, route, cancellation or cleanup checks redundant. Keep the behavior oracle after refactoring or test deduplication.

Phase 3: Module Extraction Patterns

Circular Import Prevention

Trace dependency direction before extraction. A deferred back-import can hide the cycle rather than remove it; do not bypass a package boundary that way. Use naming conventions §1 and §6 for ownership and the limited reasons to defer an import.

Thin Wrapper (Delegation Function)

Keep a wrapper only for a named compatibility consumer and one canonical implementation. If only symbol identity must be preserved, prefer the existing explicit re-export pattern instead of introducing another function.

re-export (ruff F401 prevention)

from core.cli.tool_handlers import _build_tool_handlers as _build_tool_handlers

Phase 4: Verification

Preserve a surviving check for every affected behavior or invariant after deletion. Follow the verification reference for scope and evidence reuse; do not run a full suite merely to report an audit. Use scripts/preflight.sh when broad checks are warranted and report all skips.

Anti-patterns

1. Searching imports by basename → false positives (e.g., "repl" matching the string "REPL")
2. Treating shared names as duplicate behavior → trace callers before changing either implementation
3. Not deleting originals after refactoring → the most dangerous pattern; old version called from serve, leading to lengthy debugging
4. Reinstalling or restarting as an audit side effect → require an in-scope deployment request and verify the installation/process owner first

For dead-code or test-deletion decisions, follow .agents/skills/agent-anti-pattern/references/field-guide.md. Zero textual imports, file size, parameter count, and test-only callers are insufficient on their own; check entrypoints, registries, public exports, persisted state, and compatibility contracts first.