| name | Diagnostic-First Refactoring |
| description | A non-destructive, decoupled analysis protocol for refactoring code. Generates a "Bill of Materials" report before any code is touched. |
| created | "2026-02-04T00:00:00.000Z" |
| source | r/vibecoding community pattern |
| auto-invoke | false |
| model | default |
| context_trigger | refactor, code smell, tech debt, cleanup, restructure, modularize, extract function, DRY |
🩺 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:
- Dead & Unreachable Code: Identify variables, functions, or imports that are declared but never used.
- Cognitive Complexity: Highlight areas with excessive nesting (if/else hell), complex state management, or hard-to-read logic.
- Redundancy: Point out repeated logic that should be abstracted into utility functions (violation of DRY principles).
- 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)?
- 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:
# 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
- Select Target: Identify the file(s) to refactor.
- Run Diagnosis: Feed file content + The Prompt to the AI.
- Review Report: User reviews the Matrix.
- Authorize: User approves specific line items.
- 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
