Initial commit

commands/fix-quality.md

@@ -0,0 +1,89 @@
+---
+description: Fix linting and quality issues following root-cause-first philosophy
+argument-hint: [FILES OR PATTERN]
+---
+
+# Fix Quality Issues
+
+Fix quality issues in `{{ARGS}}` (files, glob pattern, or `.` for entire project).
+
+## Priority Order
+
+**1. Fix Root Cause** (ALWAYS first)
+- Remove unused imports/variables
+- Fix type errors properly
+- Add missing return types
+- Fix naming violations
+
+**2. Maintain/Improve Safety & Reliability** (if #1 complicates)
+- Find alternative approach that keeps code at least as safe as before
+- Don't add hacks or workarounds that deteriorate quality
+- Refactor to simpler patterns if needed
+- Add proper validation/checks
+
+**3. Local Ignores** (ONLY when #1 and #2 both complicate)
+- Use most LOCAL scope: inline > file > pattern > global
+- Document WHY (comment above ignore)
+- Use specific rule name (not blanket disable)
+
+## Process
+
+**1. Gather & Categorize**
+Run linting and type checking tools to collect all issues. Group by: root cause fixable, needs alternative approach, legitimate ignore.
+
+**For large codebases (>20 issues)**: Use TodoWrite to track fixes by category:
+```
+☐ Root cause fixes (X issues)
+  ☐ Remove unused imports (N files)
+  ☐ Fix type errors (N issues)
+  ☐ Add missing return types (N functions)
+☐ Safety alternatives (Y issues)
+☐ Legitimate ignores (Z issues)
+☐ Validate all checks pass
+☐ Run full test suite
+```
+
+**2. Fix in Priority Order**
+- Root causes: Remove unused, fix types, add return types
+- Safety alternatives: Refactor without deteriorating quality
+- Ignores: Document reason, choose local scope, specific rule
+
+Mark todos completed as you fix each category. This prevents losing track when interrupted.
+
+**3. Validate**
+All linting checks + full test suite must pass.
+
+**4. Report**
+```
+✅ Quality Fixed: X root cause, Y alternatives, Z ignores
+All checks ✓ | Tests X/X ✓
+```
+
+## Locality Hierarchy (for ignores)
+
+1. **Inline**: Single line ignore
+2. **Block**: Section/function ignore
+3. **File**: Entire file ignore
+4. **Pattern**: Glob pattern ignore (e.g., test files, generated code)
+5. **Global**: Config-level disable (LAST RESORT)
+
+## Anti-Patterns
+
+❌ Blanket disable without justification
+❌ Global disable for local issue
+❌ Ignoring without understanding why
+❌ Fixing symptoms instead of root cause
+❌ Making code less safe to silence warnings
+
+## Valid Ignore Reasons
+
+- Test code needs flexibility for mocking third-party APIs
+- Generated code shouldn't be modified
+- Performance-critical code needs specific optimization
+- Third-party contract requires specific implementation
+
+## Notes
+
+- Run full test suite after fixes
+- Review ignores periodically (some may become fixable)
+- If >10% needs ignores, reconsider the rule