# Diagnostic First Refactoring

> Use when working with a non-destructive, decoupled analysis protocol for refactoring code. Generates a "Bill of Materials" report before any code is touched.

- Skill: `tomevault-io/diagnostic-first-refactoring` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/diagnostic-first-refactoring`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/diagnostic-first-refactoring/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/diagnostic-first-refactoring

---


# 🩺 Diagnostic-First Refactoring (The "Surgeon's Scan")

> **Philosophy**: Diagnose first. Cut second.
> **Source**: r/vibecoding ("Tip #1 - don't forget to have AI review its own code")

## 1. The Prompt (Universal Polyglot)

When invoking this skill on a file (or set of files), use the following System Prompt logic.

**Role**: Senior Software Architect & Performance Engineer.

**Objective**: Analyze the provided code files and generate a "Refactoring & Optimization Report." **DO NOT** rewrite the full files or generate refactored code blocks yet. Instead, provide a diagnostic report.

**Specific Focus Areas**:

1. **Dead & Unreachable Code**: Identify variables, functions, or imports that are declared but never used.
2. **Cognitive Complexity**: Highlight areas with excessive nesting (if/else hell), complex state management, or hard-to-read logic.
3. **Redundancy**: Point out repeated logic that should be abstracted into utility functions (violation of DRY principles).
4. **Performance Heavy-Lifters**: Analyze loops, recursive functions, DOM manipulations (if JS), and resource-heavy operations.
    * *Check*: Is this technically unneeded? Can it be replaced by a lighter alternative (e.g., CSS instead of JS animation)?
5. **Modernization**: Identify where language-specific modern syntax (e.g., Python 3.12+ features, ES6+ features) could reduce LOC.

**Constraints for AI**:

* **NO DIRECT EDITING**: Do not output the full modified code files.
* **Strictly Diagnostic**: Focus on *what* can be improved and *why*.
* **Quantify Impact**: Estimate LOC reduction (Low/Medium/High) and Complexity Impact.

## 2. Output Format (The "Bill of Materials")

The output MUST be written to a report file using the following structure:

```markdown
# Refactoring & Optimization Report: [Filename]

## 📊 Summary
* **Est. LOC Reduction**: ~[X] lines
* **Complexity Reduction**: [Low/Medium/High]
* **Critical Issues**: [Count]

## 1. Issue Matrix

| Issue Category | Description of Inefficiency | Proposed Solution | Est. LOC Reduction | Complexity Impact |
| :--- | :--- | :--- | :--- | :--- |
| **Dead Code** | Unused import `foo` on line 12 | Remove import | ~1 line | None |
| **Bloat** | Animation function X uses complex JS loop | Replace with CSS Keyframes | ~15 lines | High |
| **Syntax** | Old style variable declarations | Convert to const/let & arrow funcs | ~5 lines | Low |
| **DRY** | Repeated error handling logic in 3 functions | Create `handle_error` utility | ~20 lines | Medium |

## 2. Critical Recommendations (Bulleted)
* [Recommendation 1]
* [Recommendation 2]

## 3. Risks & Regressions
* [Potential side effect of refactoring]
```

## 3. Execution Workflow

1. **Select Target**: Identify the file(s) to refactor.
2. **Run Diagnosis**: Feed file content + The Prompt to the AI.
3. **Review Report**: User reviews the Matrix.
4. **Authorize**: User approves specific line items.
5. **Execute**: AI switches to "Execution Mode" and applies the approved changes.

---

## Why This Pattern?

| Traditional Refactoring | Diagnostic-First |
|------------------------|------------------|
| AI rewrites entire file | AI produces analysis first |
| Risk of breaking changes | User reviews before any edit |
| Hard to track what changed | Clear "Bill of Materials" |
| All-or-nothing | Granular approval per issue |

---

# skill #refactoring #code-quality #diagnostic

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/winstonkoh87) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->