Claude Code Review & Refactoring: Honest Quality Assessment

Review this codebase for architectural concerns. Focus on structure,
not style. For each concern found, use this format:

SEVERITY: [Critical / Major / Minor / Observation]
LOCATION: [File:line or architectural boundary]
ISSUE: [Clear description of the problem]
WHY IT MATTERS: [Concrete scenario where this causes pain]
SUGGESTION: [Specific alternative approach]

Areas to examine:
1. COUPLING: Where are modules too tightly coupled?
   Look for: import cycles, shared mutable state, modules that know about each other's internals
2. COHESION: Where are responsibilities scattered?
   Look for: classes/modules doing too many unrelated things, logic duplicated across files
3. ABSTRACTION: Where are abstractions missing or wrong?
   Look for: primitive obsession, missing interfaces, leaky abstractions
4. DEPENDENCY DIRECTION: Do dependencies flow toward stability?
   Look for: unstable code depending on stable code (correct) vs. reverse
5. BOUNDARIES: Where are domain boundaries violated?
   Look for: business logic in UI, persistence concerns in domain objects

If you're uncertain about the impact of a finding (e.g., "this seems coupled but
I can't see all the callers"), say so explicitly rather than assuming.

Review this code for security vulnerabilities. For each finding:

SEVERITY: [Critical / High / Medium / Low]
VULNERABILITY: [OWASP category if applicable]
LOCATION: [File:line]
DESCRIPTION: [What's wrong]
EXPLOIT SCENARIO: [How an attacker would exploit this]
FIX: [Specific code change or approach]

Checklist:
- Input validation (SQL injection, XSS, command injection)
- Authentication (session management, password handling, MFA bypass)
- Authorization (missing access controls, IDOR, privilege escalation)
- Data exposure (secrets in code, sensitive data in logs, verbose errors)
- Dependency vulnerabilities (outdated packages with known CVEs)

IMPORTANT: Do NOT flag issues you're uncertain about as vulnerabilities.
If something looks suspicious but you can't confirm it's exploitable,
mark it as "Requires further investigation" with your reasoning.

Review this pull request. The change is: [description of what the PR does].

1. CORRECTNESS: Does this change do what it claims to do?
   - Are there edge cases not handled?
   - Could this change introduce regressions?

2. DESIGN: Is this the right approach?
   - Is there a simpler way to achieve the same result?
   - Does this fit with the existing architecture?

3. COMPLETENESS: What's missing?
   - Tests?
   - Documentation updates?
   - Error handling?
   - Logging/monitoring?

4. RISK: What's the blast radius if this goes wrong?
   - What other systems/components depend on the changed code?
   - Is there a safe rollback path?

5. NITS (optional, low priority):
   - Naming suggestions
   - Minor style inconsistencies

Prioritize issues that would cause bugs or outages. De-prioritize style nits.

Refactor [specific code/module] to improve [specific quality: readability, performance, testability].

CONSTRAINTS:
- DO NOT change the external behavior. All existing tests must pass.
- DO NOT change the public API. Other modules depend on it.
- DO NOT introduce new dependencies.
- DO modify: [specific files allowed]
- DO NOT modify: [files to leave alone]

For each change:
1. Show the BEFORE and AFTER code
2. Explain WHY the new version is better
3. Identify what COULD break (even if you think it won't)
4. Suggest what test to run to verify correctness

Modernize this legacy code. The codebase is [language/framework], currently using
[old pattern], and should be updated to [new pattern].

APPROACH:
1. IDENTIFY all the places that need to change — don't start coding until
   you've mapped the full scope.
2. PROPOSE an incremental migration strategy. Can we do this file by file?
   Or does it need a big-bang change?
3. IMPLEMENT the changes one logical unit at a time.
4. After EACH unit, verify that existing functionality is preserved.

PATTERNS TO MODERNIZE:
- [Pattern 1: e.g., callbacks → async/await]
- [Pattern 2: e.g., class components → functional components]
- [Pattern 3: e.g., raw SQL → ORM queries]

DO NOT:
- Mix modernization with feature changes
- Modernize code you don't fully understand
- Remove comments that explain WHY something is done a certain way

Review [code]. For anything you're uncertain about, use these signals:

"I'M CONFIDENT: [finding]" — you're sure this is an issue.
"I SUSPECT: [finding]" — this looks problematic but you could be wrong.
"I'M UNSURE: [observation]" — something seems off but you can't articulate why.
"I'D NEED TO SEE: [missing context]" — you can't assess this without more information.

Never present an uncertain finding as a confident one. I'd rather have
5 confident findings than 20 findings of mixed reliability.