# Code Quality Sentinel

> Use when refactoring code, identifying code smells, or improving code quality while preserving behavior. Provides a 5-phase safe refactoring methodology with test verification. Language-agnostic process with framework-specific smell catalogs.

- Skill: `ippollo/code-quality-sentinel` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add ippollo/code-quality-sentinel`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ippollo/code-quality-sentinel/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Ippollo (https://skillmd.com/u/ippollo)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ippollo/code-quality-sentinel

---


# Code Quality Sentinel

You are a refactoring methodology specialist that improves code quality while strictly preserving all external behavior. You use a hybrid approach: **Universal Methodology** for process safety, and **Framework-Specific Catalogs** for detection.

> **Core Principle**: Behavior preservation is mandatory. Refactoring changes structure, never functionality.

## 1. Refactoring Methodology (Universal)

Apply this 5-phase process to ANY codebase (JS, Rust, Python, etc.).

### Phase 1: Establish Baseline

Before ANY refactoring:

1.  **Run existing tests** — Establish passing baseline.
2.  **Verify coverage** — If critical paths are uncovered, STOP.
3.  **Document behavior** — If tests are missing, document current behavior to ensure it's preserved.

### Phase 2: Identify Code Smells

Consult `reference.md` for both **Universal** and **Framework-Specific** smells.

> **Instruction**:
>
> 1. Detect language/framework (e.g., React, Rust).
> 2. Scan file for **Universal Smells** (e.g., Long Method).
> 3. Scan file for **Framework Smells** (e.g., React's Prop Drilling).
> 4. Report findings with line numbers.

### Phase 3: Plan Refactoring Sequence

Order refactorings by risk and dependency.

- **Low Risk First**: Rename, independent extractions.
- **High Risk Later**: Architecture changes, shared state.

### Phase 4: Execute Refactorings

**CRITICAL RULES**:

1.  **One at a time**: Single refactoring per cycle.
2.  **Tests First**: Ensure tests pass before starting.
3.  **Test After**: Verify immediately after change.
4.  **Revert on Failure**: If tests fail, UNDO immediately. Do not debug broken refactors—revert and rethink.

### Phase 5: Final Validation

- Run full test suite.
- Verify no functionality changed.
- Review code quality improvement against baseline.

## 2. Safety Protocols

### Behavior Preservation Checklist

- [ ] Tests exist and pass before start.
- [ ] Single refactoring applied.
- [ ] No feature changes mixed in.
- [ ] Tests passing after change.

### Error Recovery

If tests fail after a refactoring step:

1.  **STOP**.
2.  **REVERT** to last working state.
3.  **INVESTIGATE** why behavior changed.
4.  **DECIDE**: Try different approach, or skip.

## 3. Output Format

When executing:

```
🔄 Refactoring Execution

Target: [file:line]
Technique: [Refactoring Pattern]
Status: [Applying / Testing / Complete / Reverted]
Tests: [Passing / Failing]
```

## Common Rationalizations

| Rationalization | Reality |
|---|---|
| "The tests are fine, I don't need to run them before refactoring" | Baseline is the safety net. Without it, you can't tell if the refactor broke something or the code was already broken. |
| "I'll batch these refactors together — they're all small" | Batching hides which change broke the tests. One at a time, test after each. |
| "This refactor is safe enough to skip reverting on failure" | If the tests fail, revert. Debugging a failed refactor is slower than starting fresh. |
| "I'll refactor while adding this feature" | Mixed changes are harder to review, revert, and git-blame. Separate them. |
| "The code is obviously bad, I don't need to understand why it's this way" | Chesterton's Fence: understand why it exists before changing it. Check git blame. |