Refactor Plan FAQ

What is refactor plan?

Refactor plan scans your code for structural problems — god classes, duplicated blocks, high cyclomatic complexity, tight coupling, poor naming, dead code — and produces a prioritized roadmap with effort estimates and risk levels for each item.

When should I use it?

Use refactor plan when a module feels hard to change or test, before adding features to a tangled area, or when you need data to justify refactoring time to stakeholders. If you want a broader code quality review rather than a structural refactoring roadmap, that's a different feature.

How do I run it?

The fastest way is to describe what you want analyzed:

analyze src/auth/ for refactoring opportunities

Or invoke the skill directly:

/refactor-plan src/auth/

You can point it at a single file, a directory, or the whole project. See How to Run a Refactor Plan for the full breakdown.

What does the output look like?

The report has three sections: a Summary with an overall tech debt score (0–100) and an executive summary, a Refactoring section with a prioritized list of issues including effort estimates (small/medium/large) and risk levels (low/medium/high), and a Suggestions section with actionable next steps ordered by priority.

How does it decide what comes first?

Items are ranked by severity, effort, impact, and risk. Issues that are high-severity, low-effort, and high-impact float to the top. Risky changes are flagged so you can plan extra testing around them.

What generates the report programmatically?

Call format_refactor_plan_report(result, input_data) from workflows.refactor_plan_report — it takes the raw result dict and your input data and returns a human-readable string. To run the full workflow, instantiate RefactorPlanWorkflow from workflows.refactor_plan and call its execute() method.

Is there a CLI entry point?

Yes. main() in workflows.refactor_plan_report is the CLI entry point for the refactor planning workflow.

How do I debug a failure?

Run the related tests first with pytest -k "refactor-plan" -v. If the tests pass but your code still fails, add a logger.debug statement at the suspected failure point and re-run with logging enabled.

Where are the source files?

• src/attune/workflows/refactor_plan.py
• src/attune/workflows/refactor_plan_report.py

Tags: refactor, tech-debt, complexity

Unresolved references

Auto-generated by attune-author fact-check. Review and either fix the source code, fix this doc, or add an override.