code-quality

---
name: code-quality
description: "Use when validating code quality after modifications -- SOLID compliance, DRY duplication, linter errors, architecture violations. Do NOT use for functional verification (run verification FIRST, then code-quality)."
argument-hint: "[file-or-directory]"
user-invocable: true
---

<objective>
Code Quality is the canonical 7-phase validation workflow shared with the `sniper` agent (this skill and `agents/sniper.md` must stay in sync): explore architecture, research documentation, analyze impact via Grep usages, detect duplication with jscpd (DRY), detect errors via linters, apply precision corrections informed by docs/impact/DRY findings, then re-verify until linters, tests, and duplication are all clean. It covers SOLID compliance, DRY thresholds, error priority (security/logic/performance/style), file-size limits, and architecture-pattern violations across all languages.

It validates quality AFTER the fact -- it does not confirm the original problem was actually solved. Run the `verification` skill first to confirm functional resolution, then code-quality to confirm the fix is clean.
</objective>

# Code Quality Skill

Canonical workflow definition: `agents/sniper.md` (this skill and the sniper agent share the same 7-phase workflow — update both together).

## 🚨 MANDATORY 7-PHASE WORKFLOW

```
PHASE 1: Exploration (explore-codebase) → BLOCKER
PHASE 2: Documentation (research-expert) → BLOCKER
PHASE 3: Impact Analysis (Grep usages) → BLOCKER
PHASE 3.5: DRY Detection (jscpd duplication) → NON-BLOCKING
PHASE 4: Error Detection (linters)
PHASE 5: Precision Correction (with docs + impact + DRY)
PHASE 6: Verification (re-run linters, tests, duplication)
```

**CRITICAL**: Phases 1-3 are BLOCKERS. Never skip them.
**DRY**: Phase 3.5 is non-blocking but findings inform Phase 5 corrections.

---

## PHASE 1: Architecture Exploration

**Launch explore-codebase agent FIRST**:
```
> Agent(subagent_type="fuse-ai-pilot:explore-codebase", prompt="...")
```

**Gather**:
1. Programming language(s) detected
2. Existing linter configs (.eslintrc, .prettierrc, pyproject.toml)
3. Package managers and installed linters
4. Project structure and conventions
5. Framework versions (package.json, go.mod, Cargo.toml)
6. Architecture patterns (Clean, Hexagonal, MVC)
7. State management (Zustand, Redux, Context)
8. Interface/types directories location

---

## PHASE 2: Documentation Research

**Launch research-expert agent**:
```
> Agent(subagent_type="fuse-ai-pilot:research-expert", prompt="Verify [library/framework] documentation for [error type]. Find [language] best practices for [specific issue].")
```

**Request for each error**:
- Official API documentation
- Current syntax and deprecations
- Best practices for error patterns
- Version-specific breaking changes
- Security advisories
- Language-specific SOLID patterns

---

## PHASE 3: Impact Analysis

**For EACH element to modify**: Grep usages → assess risk → document impact.

| Risk | Criteria | Action |
|------|----------|--------|
| 🟢 LOW | Internal, 0-1 usages | Proceed |
| 🟡 MEDIUM | 2-5 usages, compatible | Proceed with care |
| 🔴 HIGH | 5+ usages OR breaking | Flag to user FIRST |

---

## PHASE 3.5: Code Duplication Detection (DRY)

**Tool**: `jscpd` — 150+ languages — `npx jscpd ./src --threshold 5 --reporters console,json`

| Level | Threshold | Action |
|-------|-----------|--------|
| 🟢 Excellent | < 3% | No action needed |
| 🟡 Good | 3-5% | Document, fix if time |
| 🟠 Acceptable | 5-10% | Extract shared logic |
| 🔴 Critical | > 10% | Mandatory refactoring |

See [references/duplication-thresholds.md](references/duplication-thresholds.md) for per-language thresholds, config, and extraction patterns.
See [references/linter-commands.md](references/linter-commands.md) for language-specific jscpd commands.

---

## Linter Commands
See [references/linter-commands.md](references/linter-commands.md) for language-specific commands.

---

## Error Priority Matrix

| Priority | Type | Examples | Action |
|----------|------|----------|--------|
| **Critical** | Security | SQL injection, XSS, CSRF, auth bypass | Fix IMMEDIATELY |
| **High** | Logic | SOLID violations, memory leaks, race conditions | Fix same session |
| **High** | DRY | Code duplication > 10%, copy-paste logic blocks | Mandatory refactoring |
| **Medium** | DRY | Code duplication 5-10%, repeated patterns | Extract shared logic |
| **Medium** | Performance | N+1 queries, deprecated APIs, inefficient algorithms | Fix if time |
| **Low** | Style | Formatting, naming, missing docs | Fix if time |

---

## SOLID Validation
See [references/solid-validation.md](references/solid-validation.md) for S-O-L-I-D detection patterns and fix examples.

---

## File Size Rules
See [references/file-size-rules.md](references/file-size-rules.md) for LoC limits, calculation, and split strategies.

---

## Architecture Rules
See [references/architecture-patterns.md](references/architecture-patterns.md) for project structures and patterns.

---

## Validation Report Format
See [references/validation-report.md](references/validation-report.md) for the complete sniper report template.

---

## Complete Workflow Example
See [references/examples.md](references/examples.md) for detailed walkthrough.

---

## Forbidden Behaviors

### Workflow Violations
- ❌ Skip PHASE 1 (explore-codebase)
- ❌ Skip PHASE 2 (research-expert)
- ❌ Skip PHASE 3 (impact analysis)
- ❌ Skip PHASE 3.5 (DRY detection)
- ❌ Jump to corrections without completing Phases 1-3
- ❌ Proceed when BLOCKER is active

### Code Quality Violations
- ❌ Leave ANY linter errors unfixed
- ❌ Apply fixes that introduce new errors
- ❌ Ignore SOLID violations
- ❌ Ignore DRY violations > 5% duplication
- ❌ Copy-paste code instead of extracting shared logic
- ❌ Create tests if project has none

### Architecture Violations
- ❌ Interfaces in component files (ZERO TOLERANCE)
- ❌ Business logic in components (must be in hooks)
- ❌ Monolithic components (must section)
- ❌ Files over `FUSE_SOLID_MAX_LINES` without split
- ❌ Local state for global data (use stores)

### Safety Violations
- ❌ High-risk changes without user approval
- ❌ Breaking backwards compatibility silently
- ❌ Modifying public APIs without deprecation

• SKILL.md 6 KB
• references/architecture-patterns.md 6 KB
• references/duplication-thresholds.md 3 KB
• references/examples.md 2 KB
• references/file-size-rules.md 1 KB
• references/linter-commands.md 2 KB
• references/solid-validation.md 2 KB
• references/validation-report.md 2 KB