qodana-review

name	qodana-review
description	Run Qodana static analysis. ALL issues must be fixed. No exceptions.

/qodana-review [path]

Run Qodana static analysis. ALL issues must be fixed.

No arguments? Describe this skill and stop. Do not execute.

First: Activate Workflow

mkdir -p .claude && echo '{"skill":"static-analysis","started":"'$(date -Iseconds)'"}' > .claude/active-workflow.json

Craft Standards (MANDATORY)

Fix toward code a master craftsperson would be proud of.

When fixing static analysis issues, ensure the result looks like it was written by a skilled human engineer, not generated by AI.

AI Antipatterns to FLAG and FIX

Beyond Qodana findings, actively look for and fix:

• Over-abstraction that Qodana missed (wrappers used once)
• Defensive checks that the type system makes impossible
• Unused imports, parameters, and variables
• Comment spam and obvious documentation
• Over-engineered types and unnecessary generics

Human Craft Standard for Fixes

After fixing, code should:

• Be simpler, not more complex
• Have no line a senior engineer would question
• Pass static analysis AND smell like clean human code

The goal isn't just passing the checks - it's code worth reading.

---

Scope Constraint (MANDATORY)

Fix ALL findings for production readiness. Every issue gets fixed. No deferring, no "backlog for next cycle," no "appropriate for MVP."

ALLOWED:

• Change logic within an existing function
• Add validation/checks to existing code paths
• Fix crypto/security bugs in existing implementations
• Add private helper methods within existing files
• Add config entries, constants, enums to existing files
• Add interfaces to existing files if needed for proper typing
• Restructure function internals (keep same signature)

FORBIDDEN:

• Adding new source files (config files are OK)
• Moving code between files
• Adding new external dependencies

If a finding seems to require restructuring: fix it anyway by restructuring within the existing file. The only acceptable unfixed items are findings that require adding new external dependencies — report those with a one-line explanation.

---

⚠️ STRICT REQUIREMENTS - NO EXCEPTIONS

You MUST fix EVERY issue Qodana and lint find. ALL of them. No exceptions.

FORBIDDEN (Phase will FAIL if detected):

• Marking issues as "false positive" without proof
• Saying "this is by design"
• Skipping issues because they're LOW severity
• Punting issues to "future work"
• Making judgment calls about what's worth fixing
• Leaving ANY issue unfixed

If an analyzer found it, YOU FIX IT. Period.

Process

Step 1: Run Qodana Scan (MANDATORY)

mcp__qodana__qodana_scan
  projectDir: <project path>

Step 2: Get All Problems

mcp__qodana__qodana_problems
  projectDir: <project path>

Step 3: Run Linting

npx tsc --noEmit
npm run lint

Step 4: Fix ALL Issues (MANDATORY - NO EXCEPTIONS)

For EACH issue:

1. Read the affected file
2. Fix with Edit tool
3. Verify the fix
4. Record in ISSUES_FIXED

The ONLY exception: third-party library code with documented evidence.

REQUIRED Output Format

QODANA_RESULT: called - [N] issues

ISSUES_FOUND:
[SEVERITY] description (file:line) [source: qodana/lint]

ISSUES_FIXED:
[SEVERITY] description - FIXED

UNFIXED: 0 (must be zero or phase fails)

ANALYSIS_ISSUES: N
SECURITY_REVIEW_COMPLETE: yes

Final: Record Lessons Learned

After fixing all issues, record NEW findings so earlier phases learn from them.

Write to TWO files:

1. Project-local: .claude/lessons.md

Append the specific finding with file paths and context:

## {date} - {target path}
### Qodana Found (phase 7)
- {CATEGORY}: {specific description with file:line} → {which earlier phase should catch this and how}

2. Universal: .claude/universal-lessons.md

Read this file first. If the general pattern is already listed, skip. If it's a NEW general pattern not already covered, append it to the appropriate section (LOGIC Patterns, DESIGN Patterns, CODE_QUALITY Patterns, or DUPLICATION Patterns). Write the general rule, not the project-specific instance:

### {Pattern Name}
- {General description of the pattern, not tied to specific files} → {how to avoid it}

Categories: LOGIC, DESIGN, CODE_QUALITY, DUPLICATION

Common Qodana findings that indicate earlier-phase gaps:

• Unused imports → implementation should not import "just in case"
• Dead functions → implementation should verify exports are used; refactoring should grep for callers
• Dead constants → deduplication should catch same-name constants in different files

If no new lessons were learned (already in both files), skip this step.

Validation (Phase will FAIL if violated)

• Qodana not called (unless unsupported project)
• UNFIXED > 0
• Contains "false positive", "by design", "won't fix" without evidence