feat: add refactoring advisor skill

README.md

@@ -87,19 +87,20 @@ The JS and Python versions are kept in lock-step by `release-please` and guarded
 ## Extensions Catalog
 
 <!-- BEGIN AUTO-GENERATED CATALOG -->
-This repository contains **2 marketplace(s)** with **63 extensions** (53 skills, 10 plugins).
+This repository contains **2 marketplace(s)** with **64 extensions** (54 skills, 10 plugins).
 
 ### large-codebase
 
 OpenHands skills for interacting, improving, and refactoring large codebases
 
-**4 extensions** (2 skills, 2 plugins)
+**5 extensions** (3 skills, 2 plugins)
 
 | Name | Type | Description | Commands |
 |------|------|-------------|----------|
 | add-javadoc | skill | Add comprehensive JavaDoc documentation to Java classes and methods. Use when documenting Java code, adding API docum... | — |
 | cobol-modernization | plugin | End-to-end COBOL to Java migration workflow. Handles build setup, mainframe dependency removal, and code migration wi... | — |
 | migration-scoring | plugin | Evaluate code migration quality with coverage, correctness, and style scoring. Generates executive reports with actio... | — |
+| refactoring-advisor | skill | Analyze codebases for structural problems and produce concrete, prioritized refactoring plans without implementing ch... | — |
 | spark-version-upgrade | skill | Upgrade Apache Spark applications between major versions (2.x→3.x, 3.x→4.x). Covers build files, deprecated APIs, con... | — |
 
 ### openhands-extensions

marketplaces/large-codebase.json

@@ -48,6 +48,20 @@
         "reporting"
       ]
     },
+    {
+      "name": "refactoring-advisor",
+      "source": "./skills/refactoring-advisor",
+      "description": "Analyze codebases for structural problems and produce concrete, prioritized refactoring plans without implementing changes.",
+      "category": "code-quality",
+      "keywords": [
+        "refactoring",
+        "architecture",
+        "code-smells",
+        "technical-debt",
+        "dependency-injection",
+        "testability"
+      ]
+    },
     {
       "name": "spark-version-upgrade",
       "source": "./skills/spark-version-upgrade",

skills/refactoring-advisor/.claude-plugin

@@ -0,0 +1 @@
+.plugin

skills/refactoring-advisor/.codex-plugin

@@ -0,0 +1 @@
+.plugin

skills/refactoring-advisor/.plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "refactoring-advisor",
+  "version": "1.0.0",
+  "description": "Analyze codebases for structural problems and produce concrete, prioritized refactoring plans without implementing changes.",
+  "author": {
+    "name": "OpenHands",
+    "email": "contact@all-hands.dev"
+  },
+  "homepage": "https://github.com/OpenHands/extensions",
+  "repository": "https://github.com/OpenHands/extensions",
+  "license": "MIT",
+  "keywords": [
+    "refactoring",
+    "architecture",
+    "code-smells",
+    "technical-debt",
+    "dependency-injection",
+    "testability"
+  ]
+}

skills/refactoring-advisor/README.md

@@ -0,0 +1,32 @@
+# Refactoring Advisor
+
+Analyze a codebase for structural problems and produce an evidence-backed refactoring plan without changing code.
+
+## What It Covers
+
+- Function-level complexity and mixed responsibilities
+- Class cohesion, collaborator count, and construction problems
+- Module and package boundaries, including circular dependencies
+- Cross-cutting concerns such as hidden dependencies, duplicated policy, configuration, and untestable side effects
+- Dependency injection decisions for every proposal
+- Prioritization by impact, effort, confidence, and prerequisite order
+
+The skill supports Java, Python, TypeScript, and C# with language-specific discovery guidance. It treats size and complexity thresholds as investigation signals rather than automatic defects.
+
+## Usage
+
+Ask OpenHands to audit a repository or a narrower scope, for example:
+
+- "Scan this repository for code smells and create a refactoring plan."
+- "These modules are too coupled. How should we separate them?"
+- "Make this service easier to test with dependency injection."
+- "Diagnose the circular dependencies in this package."
+
+The output contains a scope statement, architecture snapshot, evidence-linked findings, independently executable proposals, an explicit dependency injection evaluation for each proposal, and a prioritized implementation handoff.
+
+## Skill Resources
+
+- `SKILL.md` defines the analysis workflow and quality gate.
+- `references/discovery.md` describes repository scanning and language-specific cues.
+- `references/smells-and-strategies.md` maps named smells to refactoring and DI strategies.
+- `references/report-template.md` defines the required report structure.

skills/refactoring-advisor/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: refactoring-advisor
+description: Analyze a codebase to identify structural problems and propose concrete refactoring plans using design patterns, dependency injection, and established refactoring techniques. This skill should be used when the user asks to "refactor", find "code smells" or "technical debt", "extract method", "reduce complexity", "clean up this codebase", simplify complex code, break up a "god class", reduce coupling or duplication, resolve circular dependencies, introduce dependency injection, improve testability, or create a refactoring plan for a function, class, module, package, or repository. Produce analysis and proposals only, without writing implementation code.
+triggers:
+  - refactor
+  - code smells
+  - technical debt
+  - god class
+  - spaghetti code
+  - too coupled
+  - hard to test
+  - simplify
+  - dependency injection
+  - extract method
+  - reduce complexity
+  - clean up this codebase
+---
+
+# Refactoring Advisor
+
+Act as a senior software architect. Inspect the requested scope, diagnose structural causes, and produce an evidence-backed plan that a human or implementation agent can execute.
+
+Do not modify production code, tests, configuration, or generated files. Do not provide implementation patches, executable pseudocode, or full replacement code. Use dependency diagrams and named interface or method signatures only when they clarify a proposed boundary.
+
+## Core Principles
+
+- Ground every finding in repository evidence. Cite file paths, symbols, and line ranges.
+- Treat metric thresholds as investigation signals, not automatic defects.
+- Diagnose causes and consequences before recommending patterns.
+- Prefer the smallest refactoring that creates a meaningful boundary.
+- Preserve externally observable behavior unless the user explicitly requests a behavior change.
+- Evaluate dependency injection for every proposal. Recommend it when it moves volatile I/O, infrastructure, time, randomness, configuration, or external services behind an explicit boundary. State why it is unnecessary when direct dependencies are already stable and cohesive.
+- When multiple designs are otherwise comparable, prefer explicit dependency injection as the default decoupling technique.
+- Avoid adding interfaces, factories, layers, or patterns without a concrete consumer, testability need, or source of variation.
+- Separate confirmed findings from hypotheses that require runtime data or owner input.
+
+## Workflow
+
+### 1. Establish Scope and Constraints
+
+1. Read repository-level instructions such as `AGENTS.md`, `CONTRIBUTING.md`, and relevant package documentation.
+2. Resolve the requested scope. For an unspecified request, inspect the whole repository while prioritizing production code and architectural boundaries.
+3. Identify languages, frameworks, package boundaries, build systems, test layout, generated or vendored directories, and public APIs.
+4. Exclude generated, vendored, dependency, build-output, fixture, and snapshot files unless they reveal an architectural boundary relevant to the request.
+5. Record constraints that affect sequencing: compatibility promises, framework lifecycle, deployment topology, ownership, migrations, and test coverage.
+
+Read `references/discovery.md` for repository mapping commands, language-specific cues, sampling strategy, and fallback methods. Use available static-analysis tools when the repository already provides them; do not install new tools merely to produce the report.
+
+### 2. Discover Structural Signals
+
+Inspect all relevant levels before drawing conclusions:
+
+| Level | Signals to investigate |
+| --- | --- |
+| Function | More than roughly 50 lines, more than 4-5 parameters, nesting deeper than 3 levels, many branches, mixed I/O and domain logic, boolean control flags |
+| Class | Too many responsibilities, low cohesion, many collaborators, feature envy, mutable global state, difficult construction, broad public surface |
+| Module/package | Cycles, unstable boundaries, duplicated policies, leaky abstractions, shotgun changes, unrelated exports, infrastructure mixed with domain logic |
+| Cross-cutting | Service locator use, hidden dependencies, inconsistent error handling, repeated validation, scattered configuration, temporal coupling, untestable side effects |
+
+Corroborate each signal with at least one consequence, such as change amplification, fragile tests, duplicated fixes, unclear ownership, runtime risk, or blocked reuse. Do not report long code or a high count alone as a smell.
+
+Build a compact evidence inventory before prioritizing. Include:
+
+- exact path and symbol;
+- narrow line range or call sites;
+- dependency direction and affected consumers;
+- tests that cover or fail to isolate the area;
+- confidence level: high, medium, or low.
+
+### 3. Diagnose Root Causes
+
+Map each material finding to one or more named smells from `references/smells-and-strategies.md`. Distinguish the visible symptom from the architectural cause.
+
+For each finding:
+
+1. State the observed evidence.
+2. Name the smell.
+3. Explain the root cause and why the current boundary permits it.
+4. Describe the maintenance, testability, reliability, or delivery impact.
+5. Note uncertainty or missing evidence.
+
+Merge findings that share one root cause. Do not inflate the report with multiple symptoms of the same dependency problem.
+
+### 4. Design Refactoring Proposals
+
+Create one proposal per independently executable change. Each proposal must include:
+
+1. **Target and evidence** - exact files, symbols, and line ranges.
+2. **Desired boundary** - named functions, classes, modules, interfaces, or packages to extract, move, split, or replace.
+3. **Step sequence** - behavior-preserving steps small enough for incremental review.
+4. **Dependency injection evaluation** - recommend constructor, parameter, factory, or framework-native injection when applicable; otherwise state `Not needed` with a specific reason.
+5. **Pattern choice** - name a design or refactoring pattern only when it solves the diagnosed problem; explain why it fits better than a simpler extraction.
+6. **Behavior and API constraints** - contracts that must remain stable.
+7. **Verification** - existing tests to run and focused characterization, unit, integration, or architecture tests to add.
+8. **Risks and rollback boundary** - likely regressions, migration concerns, and a safe commit boundary.
+9. **Effort and impact** - low, medium, or high, with a short rationale.
+
+Prefer dependency direction from policy toward abstractions, with infrastructure implementing those abstractions. Keep domain logic independent of frameworks where the repository's architecture supports that separation. Do not recommend a dependency injection container when explicit constructor or parameter injection is sufficient.
+
+### 5. Prioritize the Plan
+
+Rank proposals by impact, confidence, dependency order, and effort. Put enabling characterization tests or cycle-breaking boundaries before broad extractions. Identify quick wins separately from foundational work, and call out proposals that should not proceed until a hypothesis is verified.
+
+Use `references/report-template.md` exactly for the final report. Include every section even when no material issues are found. In that case, document the inspected scope, evidence, and residual risks rather than inventing findings.
+
+## Quality Gate
+
+Before returning the report, verify that:
+
+- Discovery covered functions, classes, modules or packages, and cross-cutting concerns.
+- Every finding names a recognized smell and cites concrete evidence.
+- Every proposal names affected paths and symbols, not generic layers such as "add a service".
+- Every proposal contains an explicit dependency injection decision.
+- Proposed steps preserve behavior and are independently verifiable.
+- The action plan reflects prerequisites and impact versus effort.
+- No implementation code, patch, or unrequested file modification was produced.
+
+## References
+
+- `references/discovery.md` - Repository scanning, evidence collection, language cues, and large-repository sampling
+- `references/smells-and-strategies.md` - Named smells, root-cause prompts, DI guidance, and fitting strategies
+- `references/report-template.md` - Required output structure for findings, proposals, and prioritized actions

skills/refactoring-advisor/references/discovery.md

@@ -0,0 +1,107 @@
+# Repository Discovery
+
+Use this reference while mapping a repository and collecting evidence. Adapt commands to the available shell and tools.
+
+## 1. Read the Repository Contract
+
+Locate and read applicable instruction and architecture files before evaluating structure:
+
+```text
+AGENTS.md, CONTRIBUTING.md, README.md, docs/architecture/*
+package.json, pyproject.toml, pom.xml, build.gradle*, *.sln, *.csproj
+```
+
+Treat documented boundaries and public compatibility promises as constraints, not unquestioned proof that the implementation is healthy.
+
+## 2. Map the Codebase
+
+Prefer fast, read-only inventory commands:
+
+```sh
+git status --short
+git ls-files
+find . -maxdepth 3 -type d
+rg -n "^(class|interface|def|async def|function|export class|public class) " <scope>
+rg -n "TODO|FIXME|HACK|deprecated" <scope>
+```
+
+Use repository-provided analyzers, dependency graphs, coverage tools, and linters when already configured. Their output is evidence to inspect, not a substitute for reading the implicated code.
+
+Identify:
+
+- entry points and composition roots;
+- package or project boundaries;
+- domain, application, and infrastructure layers if present;
+- high fan-in and high fan-out modules;
+- cycles and reversed dependency directions;
+- test seams and direct construction of external dependencies;
+- repeated concepts with different names and shared names with different meanings.
+
+Ignore `.git`, dependency caches, virtual environments, build outputs, generated clients, migrations generated by tools, minified files, snapshots, and vendored code unless explicitly in scope.
+
+## 3. Inspect by Granularity
+
+### Functions and methods
+
+Use roughly 50 lines, 4-5 parameters, 3 nesting levels, and high branch count as prompts to inspect. Confirm a real issue by looking for multiple reasons to change, mixed abstraction levels, control flags, repeated condition families, or side effects intertwined with decisions.
+
+### Classes and components
+
+Inspect constructor dependencies, field groups, method clusters, public surface, lifecycle responsibilities, and reasons to change. A large cohesive parser can be healthier than a small class coordinating unrelated workflows.
+
+### Modules and packages
+
+Trace imports in both directions. Look for cycles, broad utility modules, duplicated orchestration, domain code importing concrete infrastructure, and changes that repeatedly cross the same set of files.
+
+### Cross-cutting behavior
+
+Trace configuration, logging, validation, authorization, error translation, retries, caching, transactions, time, and randomness. Flag inconsistent or scattered policy only when consolidation would clarify ownership or prevent drift.
+
+## 4. Language-Specific Cues
+
+### Java
+
+- Inspect constructor and field injection, static service access, framework annotations, package cycles, oversized Spring services/controllers, and interfaces with only speculative value.
+- Use Maven or Gradle dependency and test tasks already defined by the project.
+- Respect framework-managed lifecycles and transaction boundaries in proposals.
+
+### Python
+
+- Inspect imports executed at module load, mutable module globals, broad `except` blocks, mixins, monkeypatch-heavy tests, circular imports hidden by local imports, and functions mixing orchestration with data transformation.
+- Distinguish flexible duck-typed boundaries from missing contracts. Recommend protocols or abstract base classes only when multiple implementations, substitution, or static typing benefits justify them.
+
+### TypeScript
+
+- Inspect barrel-file cycles, type/value import confusion, service singletons, React components mixing effects with domain decisions, large union switches, and modules that combine transport, validation, and business rules.
+- Respect framework composition patterns. Prefer explicit parameters or constructors over introducing a container by default.
+
+### C#
+
+- Inspect service registration, service locator calls, static mutable services, broad controllers, partial classes hiding split responsibilities, project reference cycles, and inappropriate service lifetimes.
+- Preserve disposal, async, transaction, and scoped-service semantics in proposed boundaries.
+
+## 5. Scale the Audit
+
+For a large repository:
+
+1. Inventory all packages and dependency boundaries.
+2. Rank hotspots using repository-provided complexity data, change history, test concentration, file size, and dependency centrality.
+3. Inspect representative entry points and the highest-risk hotspots.
+4. Trace at least one important flow end to end.
+5. State what was sampled and what was not inspected.
+
+Never claim a complete audit when context or tool limits required sampling.
+
+## 6. Record Evidence
+
+For each candidate, record:
+
+```text
+Location: path:start-end and symbol
+Signal: observable structural fact
+Corroboration: consequence, repeated call site, dependency direction, or test friction
+Scope: function | class | module/package | cross-cutting
+Confidence: high | medium | low
+```
+
+Discard candidates that lack a plausible consequence or whose proposed cure would cost more than the documented problem.