refactoringminer-review

RefactoringMiner review

Use the connected refactoringminer MCP server for detected refactorings and AST diff views. This skill is a review workflow on top of MCP; it should not run RefactoringMiner from the shell unless the MCP server is unavailable.

The goal is to help reviewers spend attention on changes that are not explained by RefactoringMiner-detected refactoring structure.

If the MCP server is not configured, say that RefactoringMiner MCP is required and point the user to documentation/mcp.md. Do not pretend the review used RefactoringMiner.

Output should look like a code review. Do not add decorative preambles, insight boxes, praise, or generic conclusions. Start with the tool used or the RefactoringMiner result.

Inputs

First identify the review target:

• GitHub pull request: repository clone URL and pull request number. A pull request URL can be used for the browser view, but analysis should use the pull request source fields.
• Local worktree: MCP server working directory or relative source.workingDirectory, base ref, and whether to include untracked files.
• Commit: MCP server working directory or relative source.workingDirectory, commit id, and optional parent index.
• Explicit file contents: before and after file maps.

If the target is ambiguous, ask one concise clarification before calling tools.

Core workflow

1. Build the MCP source object for the target. The MCP server exposes a compact three-tool surface, so do not look for per-source tool names.

   • PR: { "type": "pullRequest", "cloneUrl": "<repo-url>", "pullRequestId": <number> }
   • worktree: { "type": "worktree", "workingDirectory": "<relative-path-if-needed>", "baseRef": "HEAD", "includeUntracked": false }
   • commit: { "type": "commit", "workingDirectory": "<relative-path-if-needed>", "commitId": "<sha>" }
   • file contents: { "type": "fileContents", "beforeFiles": { ... }, "afterFiles": { ... } }
   • URL browser view only: { "type": "url", "url": "<pull-request-or-commit-url>" }

2. Run refactoringminer_analyze with the source object to detect refactorings and get summary counts. If the user states an intended refactoring, run refactoringminer_validate with the same source and an intent object.

3. When the change includes moved, renamed, extracted, or inlined code, or when the ordinary diff is hard to interpret, run refactoringminer_diff with the same source object to open the RefactoringMiner AST diff browser. For a GitHub pull request or commit URL, refactoringminer_diff may use a source.type of url.

4. Use RefactoringMiner's analysis result and AST diff view as the source of truth for refactoring-aware structure. Ordinary GitHub/git diffs are useful for line references, changed-file discovery, and residual context, but they do not preserve code-move mappings the way RefactoringMiner's AST diff does.

5. Build a review map:

   • list detected refactorings by type, entity, and affected file
   • mark code regions whose movement or rename is visible in the AST diff
   • mark files or regions that appear mixed
   • mark files or regions that are not explained by the detected refactoring structure
   • keep unknown cases explicit instead of guessing

6. Review the non-refactoring and mixed regions first. Refactorings reported by RefactoringMiner are not always pure; a detected refactoring can overlap behavior-relevant edits. Look for behavior changes, missed tests, compatibility risks, broken API expectations, data loss, performance regressions, and error-handling gaps.

7. Report findings in normal code-review format. Lead with actionable issues and file or line references when available. Use severity labels such as P1, P2, and P3 when reporting issues. If there are no findings, say so and mention any remaining risk.

If a result says output was truncated, rerun with a higher MCP limit when the missing detail matters. If the PR is too large for a complete pass, review a bounded set of files and state the boundary.

Browser workflow

Use a browser tool when the user wants a visual AST diff, asks for a WebDiff page, or the ordinary Git diff shows large delete/add blocks that may be code moves:

• PR: call refactoringminer_diff with source.type set to pullRequest, or use source.type: "url" with the pull request URL when a browser-only view is enough
• worktree: call refactoringminer_diff with source.type set to worktree
• commit: call refactoringminer_diff with source.type set to commit, or use source.type: "url" with the commit URL when a browser-only view is enough
• file contents: call refactoringminer_diff with source.type set to fileContents

Return the url, summary, and any warnings. Keep the Claude Code session open while the user inspects the WebDiff page, because the local WebDiff server lives inside the MCP process.

How to treat refactorings

Detected refactorings and AST mappings are not proof of behavior preservation. Use them as review guidance, not as a verdict.

When listing detected refactorings:

• name the refactoring type, entity, and file
• do not call them safe, clean, harmless, or behavior-preserving
• do not say "no behavior changed" for refactored paths unless you reviewed those exact code regions
• if you have not reviewed a refactoring region, call it "detected by RefactoringMiner", not "verified"

Can be reviewed after higher-risk changes:

• rename, move, extract, inline, and signature-shape changes whose surrounding code has also been checked in the AST diff view
• import/package updates caused only by moves or renames
• call-site updates that exactly follow a detected rename or move

Still review:

• changed conditions, loops, arithmetic, parsing, serialization, persistence, or error handling
• changed public API behavior, configuration keys, CLI flags, JSON fields, file formats, or database access
• added or removed side effects
• test changes that weaken assertions
• any code region in a refactored file that does more than route through the new name/location

Output shape

For a full review, use:

RefactoringMiner found <N> refactorings.

Refactoring-aware structure:
- <detected refactoring list and AST-diff move/rename evidence, without safety claims>

Changes to review:
- <file or area>: <why this is not covered by detected refactoring structure>

Findings:
- <P1/P2/P3> <file:line> <issue and impact>

Residual risk:
- <limits of this review, including truncated MCP output or unavailable diff context>

For a quick answer, keep it short:

RefactoringMiner found <N> refactorings. The changes not explained by the detected refactoring structure are in <files/areas>. I found <issue/no issue>.

Keep the answer shaped like a code review.

Limits

RefactoringMiner detects refactoring structure and can show AST mappings for moved code in WebDiff. It does not prove that the change is behavior-preserving, and it does not replace tests or domain review.

Current MCP JSON results summarize detected refactorings and AST diff counts. They do not stream full machine-readable AST mappings or moved-node ranges. Use the WebDiff browser view for mapping-level review, and state this limitation when it affects confidence.

If MCP output is truncated, rerun with a higher limit or state that the review is partial.