Table of Contents
Code Refinement Workflow
Analyze and improve living code quality across six dimensions.
Quick Start
/refine-code
/refine-code --level 2 --focus duplication
/refine-code --level 3 --report refinement-plan.md
When to Use
- After rapid AI-assisted development sprints
- Before major releases (quality gate)
- When code "works but smells"
- Refactoring existing modules for clarity
- Reducing technical debt in living code
Analysis Dimensions
| # |
Dimension |
Module |
What It Catches |
| 1 |
Duplication & Redundancy |
duplication-analysis |
Near-identical blocks, similar functions, copy-paste |
| 2 |
Algorithmic Efficiency |
algorithm-efficiency |
O(n^2) where O(n) works, unnecessary iterations |
| 3 |
Clean Code Violations |
clean-code-checks |
Long methods, deep nesting, poor naming, magic values |
| 4 |
Architectural Fit |
architectural-fit |
Paradigm mismatches, coupling violations, leaky abstractions |
| 5 |
Anti-Slop Patterns |
clean-code-checks |
Premature abstraction, enterprise cosplay, hollow patterns |
| 6 |
Error Handling |
clean-code-checks |
Bare excepts, swallowed errors, happy-path-only |
Progressive Loading
Load modules based on refinement focus:
modules/duplication-analysis.md (~400 tokens): Duplication detection and consolidationmodules/algorithm-efficiency.md (~400 tokens): Complexity analysis and optimizationmodules/clean-code-checks.md (~450 tokens): Clean code, anti-slop, error handlingmodules/architectural-fit.md (~400 tokens): Paradigm alignment and coupling
Load all for comprehensive refinement. For focused work, load only relevant modules.
Required TodoWrite Items
refine:context-established — Scope, language, framework detectionrefine:scan-complete — Findings across all dimensionsrefine:prioritized — Findings ranked by impact and effortrefine:plan-generated — Concrete refactoring plan with before/afterrefine:evidence-captured — Evidence appendix per imbue:evidence-logging
Workflow
Step 1: Establish Context (refine:context-established)
Detect project characteristics:
# Language detection
find . -name "*.py" -o -name "*.ts" -o -name "*.rs" -o -name "*.go" | head -20
# Framework detection
ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
# Size assessment
find . -name "*.py" -o -name "*.ts" -o -name "*.rs" | xargs wc -l 2>/dev/null | tail -1
Step 2: Dimensional Scan (refine:scan-complete)
Load relevant modules and execute analysis per tier level.
Step 3: Prioritize (refine:prioritized)
Rank findings by:
- Impact: How much quality improves (HIGH/MEDIUM/LOW)
- Effort: Lines changed, files touched (SMALL/MEDIUM/LARGE)
- Risk: Likelihood of introducing bugs (LOW/MEDIUM/HIGH)
Priority = HIGH impact + SMALL effort + LOW risk first.
Step 4: Generate Plan (refine:plan-generated)
For each finding, produce:
- File path and line range
- Current code snippet
- Proposed improvement
- Rationale (which principle/dimension)
- Estimated effort
Step 5: Evidence Capture (refine:evidence-captured)
Document with imbue:evidence-logging (if available):
[E1], [E2] references for each finding- Metrics before/after where measurable
- Principle violations cited
Fallback: If imbue is not installed, capture evidence inline in the report using the same [E1] reference format without TodoWrite integration.
Tiered Analysis
| Tier |
Time |
Scope |
| 1: Quick (default) |
2-5 min |
Complexity hotspots, obvious duplication, naming, magic values |
| 2: Targeted |
10-20 min |
Algorithm analysis, full duplication scan, architectural alignment |
| 3: Deep |
30-60 min |
All above + cross-module coupling, paradigm fitness, comprehensive plan |
Cross-Plugin Dependencies
| Dependency |
Required? |
Fallback |
pensive:shared |
Yes |
Core review patterns |
imbue:evidence-logging |
Optional |
Inline evidence in report |
conserve:code-quality-principles |
Optional |
Built-in KISS/YAGNI/SOLID checks |
archetypes:architecture-paradigms |
Optional |
Principle-based checks only (no paradigm detection) |
When optional plugins are not installed, the skill degrades gracefully:
- Without
imbue: Evidence captured inline, no TodoWrite proof-of-work
- Without
conserve: Uses built-in clean code checks (subset)
- Without
archetypes: Skips paradigm-specific alignment, uses coupling/cohesion principles only
1---2name: code-refinement3description: Triggers: refine, code quality, clean code, refactor, duplication, algorithm efficiency, complexity reduction, code smell, anti-slop, craft Analyze and improve living code quality: duplication, algorithmic efficiency, clean code principles, architectural fit, anti-slop patterns, and error handling robustness. Use when: improving code quality, reducing AI slop, refactoring for clarity, optimizing algorithms, applying clean code principles DO NOT use when: removing dead/unused code (use conserve:bloat-detector). DO NOT use when: reviewing for bugs (use pensive:bug-review). DO NOT use when: selecting architecture paradigms (use archetypes skills). This skill actively improves living code, complementing bloat detection (dead code removal) with quality refinement (living code improvement).4---5## Table of Contents
6
7- [Quick Start](#quick-start)
8- [When to Use](#when-to-use)
9- [Analysis Dimensions](#analysis-dimensions)
10- [Progressive Loading](#progressive-loading)
11- [Required TodoWrite Items](#required-todowrite-items)
12- [Workflow](#workflow)
13- [Tiered Analysis](#tiered-analysis)
14- [Cross-Plugin Dependencies](#cross-plugin-dependencies)
15
16# Code Refinement Workflow
17
18Analyze and improve living code quality across six dimensions.
19
20## Quick Start
21
22```bash
23/refine-code
24/refine-code --level 2 --focus duplication
25/refine-code --level 3 --report refinement-plan.md
26```
27
28## When to Use
29
30- After rapid AI-assisted development sprints
31- Before major releases (quality gate)
32- When code "works but smells"
33- Refactoring existing modules for clarity
34- Reducing technical debt in living code
35
36## Analysis Dimensions
37
38| # | Dimension | Module | What It Catches |
39|---|-----------|--------|----------------|
40| 1 | Duplication & Redundancy | `duplication-analysis` | Near-identical blocks, similar functions, copy-paste |
41| 2 | Algorithmic Efficiency | `algorithm-efficiency` | O(n^2) where O(n) works, unnecessary iterations |
42| 3 | Clean Code Violations | `clean-code-checks` | Long methods, deep nesting, poor naming, magic values |
43| 4 | Architectural Fit | `architectural-fit` | Paradigm mismatches, coupling violations, leaky abstractions |
44| 5 | Anti-Slop Patterns | `clean-code-checks` | Premature abstraction, enterprise cosplay, hollow patterns |
45| 6 | Error Handling | `clean-code-checks` | Bare excepts, swallowed errors, happy-path-only |
46
47## Progressive Loading
48
49Load modules based on refinement focus:
50
51- **`modules/duplication-analysis.md`** (~400 tokens): Duplication detection and consolidation
52- **`modules/algorithm-efficiency.md`** (~400 tokens): Complexity analysis and optimization
53- **`modules/clean-code-checks.md`** (~450 tokens): Clean code, anti-slop, error handling
54- **`modules/architectural-fit.md`** (~400 tokens): Paradigm alignment and coupling
55
56Load all for comprehensive refinement. For focused work, load only relevant modules.
57
58## Required TodoWrite Items
59
601. `refine:context-established` — Scope, language, framework detection
612. `refine:scan-complete` — Findings across all dimensions
623. `refine:prioritized` — Findings ranked by impact and effort
634. `refine:plan-generated` — Concrete refactoring plan with before/after
645. `refine:evidence-captured` — Evidence appendix per `imbue:evidence-logging`
65
66## Workflow
67
68### Step 1: Establish Context (`refine:context-established`)
69
70Detect project characteristics:
71```bash
72# Language detection
73find . -name "*.py" -o -name "*.ts" -o -name "*.rs" -o -name "*.go" | head -20
74
75# Framework detection
76ls package.json pyproject.toml Cargo.toml go.mod 2>/dev/null
77
78# Size assessment
79find . -name "*.py" -o -name "*.ts" -o -name "*.rs" | xargs wc -l 2>/dev/null | tail -1
80```
81
82### Step 2: Dimensional Scan (`refine:scan-complete`)
83
84Load relevant modules and execute analysis per tier level.
85
86### Step 3: Prioritize (`refine:prioritized`)
87
88Rank findings by:
89- **Impact**: How much quality improves (HIGH/MEDIUM/LOW)
90- **Effort**: Lines changed, files touched (SMALL/MEDIUM/LARGE)
91- **Risk**: Likelihood of introducing bugs (LOW/MEDIUM/HIGH)
92
93Priority = HIGH impact + SMALL effort + LOW risk first.
94
95### Step 4: Generate Plan (`refine:plan-generated`)
96
97For each finding, produce:
98- File path and line range
99- Current code snippet
100- Proposed improvement
101- Rationale (which principle/dimension)
102- Estimated effort
103
104### Step 5: Evidence Capture (`refine:evidence-captured`)
105
106Document with `imbue:evidence-logging` (if available):
107- `[E1]`, `[E2]` references for each finding
108- Metrics before/after where measurable
109- Principle violations cited
110
111**Fallback**: If `imbue` is not installed, capture evidence inline in the report using the same `[E1]` reference format without TodoWrite integration.
112
113## Tiered Analysis
114
115| Tier | Time | Scope |
116|------|------|-------|
117| **1: Quick** (default) | 2-5 min | Complexity hotspots, obvious duplication, naming, magic values |
118| **2: Targeted** | 10-20 min | Algorithm analysis, full duplication scan, architectural alignment |
119| **3: Deep** | 30-60 min | All above + cross-module coupling, paradigm fitness, comprehensive plan |
120
121## Cross-Plugin Dependencies
122
123| Dependency | Required? | Fallback |
124|------------|-----------|----------|
125| `pensive:shared` | Yes | Core review patterns |
126| `imbue:evidence-logging` | Optional | Inline evidence in report |
127| `conserve:code-quality-principles` | Optional | Built-in KISS/YAGNI/SOLID checks |
128| `archetypes:architecture-paradigms` | Optional | Principle-based checks only (no paradigm detection) |
129
130When optional plugins are not installed, the skill degrades gracefully:
131- Without `imbue`: Evidence captured inline, no TodoWrite proof-of-work
132- Without `conserve`: Uses built-in clean code checks (subset)
133- Without `archetypes`: Skips paradigm-specific alignment, uses coupling/cohesion principles only
majiayu000