| name | x-ipe-tool-refactoring-analysis |
| description | Analyze refactoring scope, expand dependencies, and evaluate code quality across 5 dimensions. Use when starting a refactoring initiative or assessing code quality gaps. Triggers on requests like "analyze for refactoring", "evaluate refactoring scope", "assess code quality". |
Refactoring Analysis Tool
Purpose
AI Agents follow this skill to analyze and expand refactoring scope, then evaluate code quality by:
- Checking existing quality baseline
- Parsing and iteratively expanding scope via dependency analysis
- Evaluating quality across 5 perspectives (requirements, features, tech spec, tests, tracing)
- Generating actionable refactoring suggestions with applicable principles
Important Notes
BLOCKING: This is a tool skill — it performs analysis only, no task board interaction.
CRITICAL: Called by x-ipe-task-based-code-refactor as Step 1 of the refactoring workflow.
About
Refactoring analysis is the foundation of safe refactoring. It discovers the true scope of changes by iteratively expanding from initial files to all related code, then evaluates how well documentation, specs, and tests align with the actual code state.
Key Concepts:
- Scope Expansion — Iteratively discover related files via imports, shared interfaces, and coupling
- Quality Perspectives — 5 dimensions: requirements, features, tech spec, test coverage, tracing
- Gap Analysis — Categorized gaps (undocumented, unimplemented, deviated, missing, etc.)
When to Use
triggers:
- "analyze for refactoring"
- "evaluate refactoring scope"
- "assess code quality"
- "code quality analysis"
not_for:
- "execute refactoring" → use x-ipe-task-based-code-refactor
- "sync docs with code" → use x-ipe-tool-code-quality-sync
Input Parameters
input:
operation: "full_analysis"
scope:
scope_level: "feature | custom"
feature_id: "{FEATURE-XXX}"
refactoring_purpose: "<why refactoring is needed>"
files: []
modules: []
description: "<user's refactoring intent>"
quality_baseline_path: "x-ipe-docs/planning/project-quality-evaluation.md"
Input Initialization
<input_init>
<field name="operation" source="Caller specifies — currently only full_analysis" />
<field name="scope.scope_level">
<steps>
1. IF caller provides scope_level → use provided value
2. IF feature_id is provided but scope_level is not → default to "feature"
3. IF files[] is provided but feature_id is not → default to "custom"
4. ELSE → default to "custom"
</steps>
</field>
<field name="scope.feature_id">
<steps>
1. IF caller provides feature_id → use provided value
2. IF scope_level == "feature" AND feature_id is null → ASK human
3. IF scope_level == "custom" → set to null
</steps>
</field>
<field name="scope.files">
<steps>
1. IF scope_level == "feature" → auto-resolve from feature artifacts:
a. Read specification.md → extract file references
b. Read technical-design.md → extract component files
c. Collect test files referenced in technical design
2. IF scope_level == "custom" AND caller provides files[] → use provided list
3. IF scope_level == "custom" AND files[] is empty → ASK human
</steps>
</field>
<field name="quality_baseline_path" source="default: x-ipe-docs/planning/project-quality-evaluation.md" />
Definition of Ready
<definition_of_ready>
<checkpoint required="true">
<name>Scope provided</name>
<verification>scope_level set; if feature: feature_id exists; if custom: files[] non-empty</verification>
</checkpoint>
<checkpoint required="true">
<name>Target code accessible</name>
<verification>All listed files/modules can be read from filesystem</verification>
</checkpoint>
<checkpoint required="true">
<name>Code compiles without errors</name>
<verification>Run build/lint to confirm no pre-existing failures</verification>
</checkpoint>
</definition_of_ready>
Operations
Operation: Full Analysis
When: Starting a refactoring initiative — analyze scope and evaluate quality.
<operation name="full_analysis">
<action>
Phase 1 — Baseline Check:
1. CHECK for quality evaluation at quality_baseline_path
2. IF exists: READ report, EXTRACT baseline data (scores, violations, gaps)
3. IF not exists: SET quality_baseline.exists = false
Phase 2 — Parse & Expand Scope:
1. IF scope_level == "feature":
a. RESOLVE feature artifacts from x-ipe-docs/requirements/EPIC-XXX/FEATURE-XXX/
b. READ specification.md → extract file references
c. READ technical-design.md → extract component files, module boundaries
d. POPULATE files[] and modules[] from resolved artifacts
2. VALIDATE scope (files exist, modules identifiable)
3. SCOPE EXPANSION LOOP (max 10 iterations):
a. FOR EACH file: ANALYZE imports/dependencies
b. FOR EACH module: IDENTIFY sibling/parent/child modules, assess coupling
c. REFLECT: check hidden dependencies, config files, test files
d. LOG expansion (iteration, files added, reason)
e. REPEAT until no new items found OR iteration > 10
Phase 3 — Evaluate Quality (5 perspectives):
When scope_level=feature, use feature_id as primary anchor.
3a. Requirements: SEARCH x-ipe-docs/requirements/**/*.md, compare with code, identify gaps
Gap types: undocumented | unimplemented | deviated
3b. Features: READ specification.md, compare behavior, identify gaps
Gap types: missing | extra | deviated
3c. Tech Spec: READ technical-design.md, compare structure/interfaces/patterns
Gap types: structure | interface | data_model | pattern
3d. Test Coverage: RUN coverage tool, analyze line/branch coverage
Gap types: business_logic | error_handling | edge_case
3e. Tracing: SCAN for @x_ipe_tracing decorators, check coverage and redaction
Gap types: untraced | unredacted | wrong_level
CRITICAL: Evaluate ALL 5 perspectives even if docs missing (set status: not_found)
Phase 4 — Generate Suggestions:
1. ANALYZE quality gaps → derive suggestion categories
2. SCAN code for principle violations (SRP, DRY, KISS, YAGNI, SoC)
3. PRIORITIZE into primary (MUST) and secondary (nice-to-have) principles
4. FORMULATE specific, measurable goals with priority and rationale
5. DEFINE target structure and constraints (backward compat, API stability)
BLOCKING: Every suggestion must trace back to a documented gap
Phase 5 — Compile Output:
1. CALCULATE dimension scores (1-10): score = 10 - SUM(violations × weights), clamped 1-10
2. DERIVE status: 8-10 = aligned, 6-7 = needs_attention, 1-5 = critical
3. CALCULATE overall_quality_score (weighted avg: req 0.20, feat 0.20, tech 0.20, test 0.20, tracing 0.10, code 0.10)
4. GENERATE report to x-ipe-docs/refactoring/analysis-{context}.md
5. SELF-REVIEW: check for missing content, inconsistencies
- BLOCKING: Scope expansion must iterate until stable (no new items) or cap at 10
- BLOCKING: Every suggestion must trace to a documented gap
- CRITICAL: Constraints must include backward compatibility and API stability
- MANDATORY: All markdown links use project-root-relative paths
refactoring_scope, code_quality_evaluated, refactoring_suggestion, refactoring_principle
Output Result
operation_output:
success: true | false
result:
quality_baseline:
exists: true | false
overall_score: "<1-10>"
refactoring_scope:
scope_level: "feature | custom"
feature_id: "{FEATURE-XXX or null}"
refactoring_purpose: "<purpose>"
files: [<expanded file list>]
modules: [<expanded module list>]
dependencies: [<identified dependencies>]
scope_expansion_log: [<log entries>]
code_quality_evaluated:
requirements_alignment: { score: "<1-10>", status: "<aligned|needs_attention|critical>", gaps: [] }
specification_alignment: { score: "<1-10>", status: "<aligned|needs_attention|critical>", gaps: [] }
test_coverage: { score: "<1-10>", line_coverage: "<XX%>", critical_gaps: [] }
{ , [], {}, {} }
[{ , , }]
[{ , , [] }]
[{ , }]
[{ , }]
[]
Evaluation Thresholds: Line Coverage ≥80%, File Size ≤800 lines, Function Size ≤50 lines
Definition of Done
<definition_of_done>
<checkpoint required="true">
<name>Scope expansion completed</name>
<verification>Loop terminated with no new items or at iteration cap</verification>
</checkpoint>
<checkpoint required="true">
<name>All 5 quality perspectives evaluated</name>
<verification>Requirements, features, tech spec, test coverage, tracing all have status and gaps</verification>
</checkpoint>
<checkpoint required="true">
<name>Suggestions generated with principles</name>
<verification>refactoring_suggestion and refactoring_principle populated</verification>
</checkpoint>
<checkpoint required="true">
<name>Analysis report generated</name>
<verification>Report at x-ipe-docs/refactoring/analysis-{context}.md exists</>
Error Handling
| Error | Cause | Resolution |
|---|
SCOPE_EMPTY | No files provided or resolved | Ask caller for file paths |
FEATURE_NOT_FOUND | Feature artifacts not at expected path | Verify feature_id, check x-ipe-docs/requirements/ |
CIRCULAR_DEPS | Scope expansion exceeds 10 iterations | Warn about circular dependencies, cap scope |
BUILD_FAILURE | Code doesn't compile before analysis | Fix build errors before analysis |
References
