@botlearn/refactor 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 BotLearn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,35 @@
+# @botlearn/refactor
+
+> Automated code refactoring with design pattern application, complexity reduction, and behavioral equivalence verification for OpenClaw Agent
+
+## Installation
+
+```bash
+# via npm
+npm install @botlearn/refactor
+
+# via clawhub
+clawhub install @botlearn/refactor
+```
+
+## Category
+
+programming-assistance
+
+## Dependencies
+
+`@botlearn/code-review`
+
+## Files
+
+| File | Description |
+|------|-------------|
+| `manifest.json` | Skill metadata and configuration |
+| `skill.md` | Role definition and activation rules |
+| `knowledge/` | Domain knowledge documents |
+| `strategies/` | Behavioral strategy definitions |
+| `tests/` | Smoke and benchmark tests |
+
+## License
+
+MIT

package/knowledge/anti-patterns.md

@@ -0,0 +1,92 @@
+---
+domain: refactor
+topic: refactoring-anti-patterns
+priority: medium
+ttl: 30d
+---
+
+# Code Refactoring — Anti-Patterns
+
+## Planning Anti-Patterns
+
+### 1. Big-Bang Refactor
+- **Problem**: Attempting to refactor an entire module, class, or system in a single large change; rewriting from scratch under the guise of "refactoring"
+- **Consequences**: Merge conflicts with ongoing feature work; impossible to isolate introduced bugs; no rollback point; multi-day or multi-week branches that diverge from main; high risk of abandonment
+- **Fix**: Decompose into the smallest possible independent steps; each step modifies one structural element (one method, one class, one dependency); each step is a separate commit with passing tests; use the Strangler Fig pattern for large-scale migrations
+
+### 2. Refactoring Without Tests
+- **Problem**: Restructuring code that has no test coverage and writing no characterization tests before beginning
+- **Consequences**: No safety net to detect behavioral changes; silent regressions discovered weeks later in production; loss of team confidence in the codebase
+- **Fix**: Write characterization tests first — capture existing behavior as-is, even if the behavior seems incorrect; achieve at least 80% line coverage and 70% branch coverage on the target code before making any structural changes; if tests are impractical, use snapshot testing to record input/output pairs
+
+### 3. Refactoring Without Measuring
+- **Problem**: Performing refactoring based on gut feeling without measuring code quality before or after
+- **Consequences**: No evidence that the refactoring improved anything; possible degradation disguised as improvement; no way to justify the investment to stakeholders
+- **Fix**: Measure cyclomatic complexity, cognitive complexity, coupling, and duplication before starting; set explicit improvement targets; measure after completion; report the delta
+
+### 4. Scope Creep Refactoring
+- **Problem**: Starting with a focused refactoring target but continuously expanding scope as new issues are discovered ("while I'm here, I'll also fix this...")
+- **Consequences**: Unbounded work; touching unrelated code increases risk; delays the original goal; makes the changeset unreviewable
+- **Fix**: Define a strict boundary before starting; log discovered issues as separate tasks; complete the original scope first; address new issues in subsequent, independent refactoring sessions
+
+## Execution Anti-Patterns
+
+### 5. Premature Abstraction
+- **Problem**: Introducing design patterns, abstract classes, or generic interfaces before there is concrete evidence of the need for extensibility — typically after seeing only 1 concrete case
+- **Consequences**: Over-engineered code that is harder to understand than the original; abstractions that don't match actual variation points; increased indirection with no benefit; refactoring the refactoring later
+- **Rule of Three**: Wait until you have 3 concrete instances of duplication or variation before introducing an abstraction; 2 instances are a coincidence, 3 are a pattern
+- **Fix**: Start concrete, generalize only when variation is demonstrated; prefer duplication over the wrong abstraction
+
+### 6. Pattern Fever
+- **Problem**: Applying GoF design patterns because they are "good practices" rather than because they solve a specific identified problem in the code
+- **Consequences**: Unnecessary complexity; explosion of small classes and interfaces that obscure simple logic; Factory patterns wrapping a single constructor; Strategy patterns with a single strategy; Observer patterns where a direct call suffices
+- **Fix**: Every pattern application must reference a specific code smell it resolves; if you cannot name the smell, you do not need the pattern; after applying a pattern, verify that the code is easier to understand, not harder
+
+### 7. Refactoring in Production Hotfix Branches
+- **Problem**: Combining refactoring changes with bug fixes in the same commit or branch
+- **Consequences**: Difficult to review — reviewer cannot separate intentional behavior changes (fix) from structural changes (refactoring); difficult to revert the fix without losing the refactoring or vice versa; increases hotfix risk
+- **Fix**: Separate refactoring commits from fix commits completely; in hotfix scenarios, fix first, refactor later in a dedicated branch
+
+### 8. Copy-Paste Refactoring
+- **Problem**: "Refactoring" by duplicating code and modifying the copy instead of restructuring the original; creating a "v2" method alongside the original
+- **Consequences**: Doubles the maintenance burden; the original is never removed; two diverging implementations of the same logic
+- **Fix**: Use Extract Method/Class to share common logic; migrate callers incrementally to the new structure; remove the old code once all callers are migrated
+
+## Design Anti-Patterns
+
+### 9. Speculative Generalization in Refactoring
+- **Problem**: Adding extension points, plugin architectures, or configuration options "in case we need them later" during a refactoring session
+- **Consequences**: YAGNI violation; increased code surface area with no current users; maintenance cost for unused abstractions; the predicted future need often does not materialize or looks different than expected
+- **Fix**: Refactor only to address current, concrete problems; optimize for readability and simplicity today; add extension points when an actual second use case arrives
+
+### 10. Inheritance Over Composition
+- **Problem**: Refactoring duplication by creating deep inheritance hierarchies instead of using composition and delegation
+- **Consequences**: Fragile base class problem; tight coupling between parent and children; DIT (depth of inheritance tree) exceeds 3-4; Liskov Substitution violations; difficulty understanding behavior without reading the entire hierarchy
+- **Fix**: Prefer composition and delegation; use interfaces to define contracts; extract shared behavior into composed helper objects rather than base classes; limit inheritance depth to 2-3 levels
+
+### 11. Over-Decomposition
+- **Problem**: Breaking code into extremely small methods (1-3 lines) or extremely small classes (single method) in pursuit of SRP purity
+- **Consequences**: Reading the code requires following 15+ method calls to understand a single operation; debugger stepping becomes painful; the "where is the logic?" problem; increased indirection without improved clarity
+- **Fix**: Methods should be small but semantically complete — a method should perform one complete thought, not one line of code; aim for 5-15 lines per method as a sweet spot; group closely related operations
+
+### 12. Refactoring Toward the Wrong Abstraction
+- **Problem**: Refactoring code to match a textbook pattern or architecture that does not fit the actual domain or usage patterns
+- **Consequences**: Impedance mismatch between code structure and domain logic; forced workarounds; worse readability than the original
+- **Fix**: Let the domain drive the abstraction; study how the code is actually used before choosing a target structure; validate the target design with concrete use cases before transforming
+
+## Process Anti-Patterns
+
+### 13. Solo Refactoring of Shared Code
+- **Problem**: Refactoring heavily-used shared code (utilities, core libraries, data models) without consulting the team
+- **Consequences**: Breaks other team members' work; merge conflicts across multiple branches; API changes that callers did not expect
+- **Fix**: Discuss significant refactorings in code review or team standup before starting; for shared code, create a migration plan; deprecate old APIs before removing them; provide a migration guide
+
+### 14. Refactoring Under Time Pressure
+- **Problem**: Attempting significant refactoring during a release crunch, sprint end, or incident response
+- **Consequences**: Incomplete refactoring committed under pressure; half-refactored code is worse than the original; increased risk of production incidents
+- **Fix**: Time-box all refactoring; if the scope cannot fit the available time, defer it; never force-merge an incomplete refactoring
+
+### 15. Ignoring Performance During Refactoring
+- **Problem**: Assuming that any behavior-preserving transformation is also performance-preserving
+- **Consequences**: Extract Method may cause additional function call overhead in hot loops; replacing direct access with getter chains may cause cache misses; introducing polymorphism where JIT was inlining direct calls
+- **Fix**: Profile performance-critical code before and after refactoring; for hot paths, benchmark with realistic data; acceptable regression threshold: < 5% for hot paths, < 10% for non-critical paths

package/knowledge/best-practices.md

@@ -0,0 +1,147 @@
+---
+domain: refactor
+topic: refactoring-best-practices
+priority: high
+ttl: 30d
+---
+
+# Code Refactoring — Best Practices
+
+## Incremental Refactoring
+
+### 1. Small, Reversible Steps
+- Each refactoring step should be a single, well-defined transformation (one Extract Method, one Move Field, one Rename)
+- Every step must be independently compilable and testable — never leave code in a broken state between steps
+- Maintain a rollback point before each transformation — use version control commits as checkpoints
+- If a step takes more than 15 minutes without a green test suite, the step is too large — decompose further
+
+### 2. The Refactoring Cycle
+```
+Red (failing test, if adding coverage) → Green (make it pass) → Refactor (improve structure) → Green (verify equivalence) → Commit
+```
+- Never refactor red code — always start from a passing test suite
+- After each refactoring step, run the full relevant test suite before proceeding
+- Commit after each successful step to create a rollback point
+
+### 3. Prioritize by Impact
+Rank refactoring candidates using this priority matrix:
+
+| Priority | Criteria | Example |
+|----------|----------|---------|
+| P0 — Critical | Blocks feature development or causes bugs | Circular dependency preventing deployment |
+| P1 — High | High complexity (CC > 20) in frequently modified code | God class edited in every sprint |
+| P2 — Medium | Code smells in stable code with moderate complexity | Duplicate code in rarely-changed modules |
+| P3 — Low | Cosmetic improvements, naming, formatting | Inconsistent naming conventions |
+
+Focus on code that is **both complex and frequently changed** (high churn + high complexity = refactoring priority).
+
+### 4. Scope Control
+- Define a clear refactoring boundary before starting — which files/classes/methods are in scope
+- Resist the urge to "fix one more thing" outside the defined scope
+- Track discovered issues outside scope as separate refactoring tasks for later
+- Time-box refactoring sessions: 30-90 minutes per focused refactoring session
+
+## Test-Driven Refactoring
+
+### 1. Characterization Tests
+Before refactoring code that lacks tests:
+- Write **characterization tests** that capture the current behavior, including edge cases
+- Execute the code with various inputs and assert the actual outputs (even if they seem wrong)
+- These tests serve as a behavioral contract — they should pass both before and after refactoring
+- Cover at minimum: happy path, boundary values, null/empty inputs, error paths
+
+### 2. Test Coverage Requirements
+Before beginning a refactoring session:
+- Verify that the code under refactoring has at least **80% line coverage** and **70% branch coverage**
+- If coverage is insufficient, write additional tests BEFORE refactoring
+- Pay special attention to conditional branches — each branch of an if/else, each case in a switch
+- For extracted methods: ensure the original tests still exercise the extracted code through the caller
+
+### 3. Mutation Testing Awareness
+- After refactoring, consider whether the test suite would catch regressions introduced by common errors:
+  - Off-by-one errors in extracted boundary logic
+  - Inverted boolean conditions
+  - Missing null checks after moving code
+  - Changed evaluation order in extracted expressions
+- If any mutation would go undetected, add targeted tests
+
+### 4. Test Refactoring
+- Tests themselves may need refactoring — but refactor tests and production code separately, never simultaneously
+- When extracting a class, create a new test class for it; keep original tests as integration tests
+- Use the same incremental approach for test refactoring: one step at a time, verify passing after each step
+
+## Equivalence Verification
+
+### 1. Behavioral Equivalence Checklist
+After each refactoring step, verify:
+- [ ] All existing tests pass without modification
+- [ ] Public method signatures are unchanged (names, parameters, return types)
+- [ ] Exception/error behavior is preserved (same exceptions for same invalid inputs)
+- [ ] Side effects are preserved (same writes, same external calls, same logging)
+- [ ] Concurrency behavior is preserved (thread safety, locking semantics, ordering)
+- [ ] Performance characteristics are within acceptable bounds (no O(n) to O(n^2) regressions)
+
+### 2. Contract-Based Verification
+For each public method under refactoring, document:
+- **Preconditions**: What must be true before the method is called (parameter constraints, object state)
+- **Postconditions**: What must be true after the method returns (return value properties, state changes)
+- **Invariants**: What must always be true about the object (field relationships, consistency rules)
+- Verify that all three are preserved after refactoring
+
+### 3. Snapshot Testing
+For complex transformations:
+- Record input/output pairs from the original code for a comprehensive set of scenarios
+- After refactoring, replay the same inputs and compare outputs byte-for-byte
+- This is especially valuable for functions with complex output (serialization, formatting, rendering)
+
+### 4. Integration Point Verification
+When refactoring code that interacts with external systems:
+- Verify that API call patterns are unchanged (same endpoints, same payloads, same headers)
+- Verify that database queries produce the same results
+- Verify that message queue interactions are preserved (same topics, same message formats)
+- Run integration tests if available; if not, document the integration contracts
+
+## Code Quality Measurement
+
+### 1. Before/After Metrics
+Always measure and report:
+- **Cyclomatic Complexity**: Per-method and per-class, before and after
+- **Cognitive Complexity**: Per-method, before and after
+- **Coupling**: Afferent and efferent, before and after
+- **Duplication**: Lines/blocks of duplicate code, before and after
+- **Lines of Code**: Per-method and per-class (with context — shorter is not always better)
+
+### 2. Quality Gates
+A refactoring is considered successful when:
+- All tests pass (mandatory — non-negotiable)
+- Cyclomatic complexity of target methods is reduced by at least 20%
+- No new code smells are introduced (verified by static analysis)
+- Code review indicates improved readability
+- No performance regressions beyond 5% in hot paths
+
+### 3. Static Analysis Integration
+Leverage static analysis tools to validate improvements:
+- Run linter before and after to compare violation counts
+- Check for new warnings introduced by the refactoring
+- Validate that type safety is preserved or improved
+- Ensure no new accessibility or security issues are introduced
+
+## Communication and Documentation
+
+### 1. Refactoring Commit Messages
+Structure commit messages for refactoring:
+```
+refactor(<scope>): <what was changed>
+
+- Why: <smell or metric that triggered the refactoring>
+- How: <technique applied (e.g., Extract Method, Replace with Strategy)>
+- Metrics: <before/after complexity, coupling, or duplication numbers>
+- Equivalence: <how behavioral equivalence was verified>
+```
+
+### 2. Decision Records
+For significant refactorings (pattern introductions, architecture changes):
+- Document the problem that triggered the refactoring
+- List alternatives considered and why the chosen approach was selected
+- Record the expected and actual quality improvements
+- Note any trade-offs or known limitations of the new design

package/knowledge/domain.md

@@ -0,0 +1,193 @@
+---
+domain: refactor
+topic: refactoring-catalog-patterns-principles
+priority: high
+ttl: 90d
+---
+
+# Code Refactoring — Domain Knowledge
+
+## Martin Fowler's Refactoring Catalog
+
+### Code Smells — Detection Signatures
+
+#### Bloaters
+- **Long Method** — Method exceeds 20 lines or has more than 3 levels of nesting; contains inline comments explaining "sections" of logic
+- **Large Class / God Class** — Class has more than 10 public methods, more than 20 fields, or handles 3+ distinct responsibilities
+- **Primitive Obsession** — Uses primitive types (string, int, boolean) to represent domain concepts (e.g., `string email` instead of `Email` type; `int status` instead of `Status` enum)
+- **Long Parameter List** — Method takes more than 3-4 parameters; parameter groups travel together across methods
+- **Data Clumps** — The same group of 3+ variables appears together in multiple places (e.g., `street`, `city`, `zip` always appear as a group)
+
+#### Object-Orientation Abusers
+- **Switch Statements** — Repeated switch/if-else chains on the same type field, especially when adding a new case requires changes in multiple locations
+- **Temporary Field** — Object fields that are only set and used in certain circumstances, remaining null/undefined otherwise
+- **Refused Bequest** — Subclass uses only a small portion of inherited methods/properties, or overrides most of them to do nothing
+- **Parallel Inheritance Hierarchies** — Every time you add a subclass to one hierarchy, you must add a corresponding subclass to another
+
+#### Change Preventers
+- **Divergent Change** — A single class is modified for multiple unrelated reasons; different groups of changes affect different methods
+- **Shotgun Surgery** — A single logical change requires small modifications scattered across many classes
+- **Feature Envy** — A method accesses data from another object more than from its own object; it "wants to be" in the other class
+
+#### Dispensables
+- **Duplicate Code** — Identical or near-identical code structures in 2+ locations; includes structural duplication (same logic with different variable names)
+- **Dead Code** — Unreachable methods, unused variables, obsolete commented-out code, never-true conditionals
+- **Lazy Class** — A class that does too little to justify its existence; has only 1-2 trivial methods
+- **Speculative Generality** — Abstract classes, interfaces, or parameters that exist "just in case" but currently have only one implementation
+
+#### Couplers
+- **Inappropriate Intimacy** — Two classes access each other's private members or internal details excessively
+- **Message Chains** — Long chains of method calls: `a.getB().getC().getD().doSomething()` (Law of Demeter violations)
+- **Middle Man** — A class that delegates almost all its work to another class, adding no value
+
+### Refactoring Techniques — By Smell
+
+| Smell | Primary Refactoring | Secondary Refactoring |
+|-------|--------------------|-----------------------|
+| Long Method | Extract Method | Replace Temp with Query, Decompose Conditional |
+| Large Class | Extract Class | Extract Subclass, Extract Interface |
+| Primitive Obsession | Replace Primitive with Object | Introduce Parameter Object, Replace Type Code with Subclass |
+| Long Parameter List | Introduce Parameter Object | Preserve Whole Object, Replace Parameter with Method Call |
+| Data Clumps | Extract Class | Introduce Parameter Object |
+| Switch Statements | Replace Conditional with Polymorphism | Replace Type Code with Strategy, Introduce Null Object |
+| Duplicate Code | Extract Method | Pull Up Method, Form Template Method |
+| Feature Envy | Move Method | Move Field, Extract Method + Move |
+| Shotgun Surgery | Move Method + Move Field | Inline Class (consolidate) |
+| Divergent Change | Extract Class | Extract Module |
+| Message Chains | Hide Delegate | Extract Method, Move Method |
+| Middle Man | Remove Middle Man | Inline Method, Replace Delegation with Inheritance |
+| Dead Code | Remove Dead Code | — |
+| Lazy Class | Inline Class | Collapse Hierarchy |
+| Speculative Generality | Collapse Hierarchy | Inline Class, Remove Parameter |
+
+## Gang of Four (GoF) Design Patterns
+
+### Creational Patterns
+
+#### Factory Method
+- **Problem it solves**: Client code coupled to concrete class constructors; adding new types requires modifying client code
+- **When to apply**: Multiple related classes with a common interface; object creation logic is complex or conditional
+- **Structure**: Abstract creator declares factory method; concrete creators override it to produce specific products
+- **Refactoring trigger**: `new` keyword appears in switch/if-else chains; constructor calls scattered across codebase
+
+#### Abstract Factory
+- **Problem it solves**: Families of related objects that must be created together; switching between families requires changing multiple creation points
+- **When to apply**: Multiple product families (e.g., UI themes, database backends); products within a family must be compatible
+- **Refactoring trigger**: Parallel switch statements creating different but related objects
+
+#### Builder
+- **Problem it solves**: Complex object construction with many optional parameters; telescoping constructor anti-pattern
+- **When to apply**: Object requires 5+ configuration parameters; construction steps may vary
+- **Refactoring trigger**: Constructors with 5+ parameters; multiple constructor overloads
+
+#### Singleton
+- **Problem it solves**: Exactly one instance needed globally with a single access point
+- **When to apply**: Resource managers, configuration, logging (use sparingly; often an anti-pattern itself)
+- **Refactoring trigger**: Global variables; static utility classes with state
+
+### Structural Patterns
+
+#### Adapter
+- **Problem it solves**: Incompatible interfaces between existing classes; integrating third-party code with different API conventions
+- **When to apply**: Wrapping legacy code; integrating external libraries; bridging interface mismatches
+- **Refactoring trigger**: Wrapper functions that translate between two interface styles
+
+#### Decorator
+- **Problem it solves**: Need to add responsibilities to objects dynamically without modifying their class; combinatorial explosion of subclasses
+- **When to apply**: Cross-cutting concerns (logging, caching, validation); optional behaviors that can be composed
+- **Refactoring trigger**: Subclass explosion from combinations of features; repeated wrapper logic
+
+#### Facade
+- **Problem it solves**: Complex subsystem with many interdependent classes; client code needs a simplified interface
+- **When to apply**: Simplifying access to a library; providing a high-level API over low-level operations
+- **Refactoring trigger**: Client code repeatedly uses the same sequence of subsystem calls
+
+#### Composite
+- **Problem it solves**: Tree structures where individual objects and compositions should be treated uniformly
+- **When to apply**: File systems, UI hierarchies, organizational structures, expression trees
+- **Refactoring trigger**: Recursive structures with duplicated traversal logic; type-checking for leaf vs. container
+
+### Behavioral Patterns
+
+#### Strategy
+- **Problem it solves**: Multiple algorithms for the same task; algorithm selection via switch/if-else chains
+- **When to apply**: Sorting algorithms, pricing strategies, validation rules, rendering modes
+- **Refactoring trigger**: Switch statements selecting behavior; conditional logic that varies by "type" or "mode"
+
+#### Observer
+- **Problem it solves**: Objects need to be notified of state changes in another object without tight coupling
+- **When to apply**: Event systems, data binding, pub/sub patterns, UI updates from model changes
+- **Refactoring trigger**: Explicit notification calls scattered through setter methods; polling for changes
+
+#### Command
+- **Problem it solves**: Need to parameterize, queue, log, or undo operations; decouple invoker from executor
+- **When to apply**: Undo/redo systems, task queues, macro recording, transaction management
+- **Refactoring trigger**: Methods that both decide what to do and do it; no support for undo
+
+#### Template Method
+- **Problem it solves**: Algorithm structure is shared but individual steps vary across subclasses
+- **When to apply**: Framework hooks, processing pipelines, lifecycle methods
+- **Refactoring trigger**: Duplicate code in sibling classes with small step-level variations
+
+#### State
+- **Problem it solves**: Object behavior changes based on internal state; large switch/if-else on state variable
+- **When to apply**: Workflow engines, protocol handlers, UI components with multiple modes
+- **Refactoring trigger**: Methods with large switch statements on a state field; state transitions scattered across methods
+
+## SOLID Principles
+
+### Single Responsibility Principle (SRP)
+- **Definition**: A class should have only one reason to change — one responsibility, one actor it serves
+- **Violation indicators**: Class name includes "And" or "Manager" or "Handler" for unrelated concerns; class changes for multiple unrelated feature requests; class has methods operating on different data domains
+- **Refactoring**: Extract Class — split the class along responsibility boundaries; each resulting class serves one actor
+
+### Open/Closed Principle (OCP)
+- **Definition**: Software entities should be open for extension but closed for modification
+- **Violation indicators**: Adding a new feature requires modifying existing working code; switch/if-else chains on type discriminators grow with each new variant
+- **Refactoring**: Replace Conditional with Polymorphism; introduce Strategy or Template Method pattern; use dependency injection
+
+### Liskov Substitution Principle (LSP)
+- **Definition**: Subtypes must be substitutable for their base types without altering program correctness
+- **Violation indicators**: Subclass overrides a method to throw "not supported" exceptions; subclass weakens preconditions or strengthens postconditions; client code checks `instanceof` before calling methods
+- **Refactoring**: Extract Interface for the true shared contract; use composition over inheritance; restructure hierarchy
+
+### Interface Segregation Principle (ISP)
+- **Definition**: Clients should not be forced to depend on methods they do not use
+- **Violation indicators**: Interface has 10+ methods; implementing classes leave many methods as no-ops or throw exceptions; "fat" interfaces with unrelated method groups
+- **Refactoring**: Split into focused interfaces (e.g., `Readable`, `Writable` instead of `ReadWritable`); use role interfaces
+
+### Dependency Inversion Principle (DIP)
+- **Definition**: High-level modules should not depend on low-level modules; both should depend on abstractions
+- **Violation indicators**: High-level business logic imports and instantiates concrete infrastructure classes (database drivers, HTTP clients); no interfaces between layers
+- **Refactoring**: Extract Interface for dependencies; introduce constructor injection or service locator; use Factory for object creation
+
+## Complexity Metrics
+
+### Cyclomatic Complexity (McCabe)
+- **Definition**: Number of linearly independent paths through a function; calculated as `E - N + 2P` (edges - nodes + 2 * connected components) in the control flow graph
+- **Practical calculation**: Count 1 (base) + 1 for each `if`, `else if`, `for`, `while`, `case`, `catch`, `&&`, `||`, `?:`
+- **Thresholds**: 1-10 = simple/low risk; 11-20 = moderate complexity; 21-50 = high complexity/refactor recommended; 50+ = untestable/must refactor
+- **Reduction techniques**: Extract Method, Replace Conditional with Polymorphism, Decompose Conditional, Replace Nested Conditional with Guard Clauses
+
+### Cognitive Complexity (SonarSource)
+- **Definition**: Measures how difficult code is for a human to understand; penalizes nesting, breaks in linear flow, and recursion
+- **Key differences from cyclomatic**: Nesting increments penalty (nested `if` costs more than sequential `if`); `else` and `switch` cases are counted; shorthand syntax is not penalized
+- **Thresholds**: 0-5 = easy to understand; 6-15 = moderate; 16-25 = difficult; 25+ = very difficult/refactor required
+
+### Coupling Metrics
+- **Afferent Coupling (Ca)**: Number of external classes that depend on this class — high Ca means the class is heavily used and changes are risky
+- **Efferent Coupling (Ce)**: Number of external classes this class depends on — high Ce means the class is fragile (many reasons to change)
+- **Instability (I)**: `Ce / (Ca + Ce)` — ranges from 0 (maximally stable) to 1 (maximally unstable)
+- **Abstractness (A)**: Ratio of abstract classes/interfaces to total classes in a package
+- **Distance from Main Sequence (D)**: `|A + I - 1|` — measures balance; 0 is ideal; high values indicate the "zone of pain" (stable + concrete) or "zone of uselessness" (unstable + abstract)
+
+### Depth of Inheritance Tree (DIT)
+- **Definition**: Maximum length from a class to the root of its inheritance hierarchy
+- **Thresholds**: 0-2 = good; 3-4 = acceptable; 5+ = excessive inheritance/consider composition
+- **Risks of deep inheritance**: Increased fragility, difficulty understanding behavior, tight coupling to ancestor implementations
+
+### Lines of Code (LOC) Guidelines
+- **Method**: Aim for under 20 lines; extract at 30+
+- **Class**: Aim for under 200 lines; extract at 400+
+- **File**: Aim for under 400 lines; split at 600+
+- **Note**: LOC is a coarse metric — always combine with complexity metrics for accurate assessment

package/manifest.json

@@ -0,0 +1,28 @@
+{
+  "name": "@botlearn/refactor",
+  "version": "0.1.0",
+  "description": "Automated code refactoring with design pattern application, complexity reduction, and behavioral equivalence verification for OpenClaw Agent",
+  "category": "programming-assistance",
+  "author": "BotLearn",
+  "benchmarkDimension": "code-generation",
+  "expectedImprovement": 40,
+  "dependencies": {
+    "@botlearn/code-review": "^1.0.0"
+  },
+  "compatibility": {
+    "openclaw": ">=0.5.0"
+  },
+  "files": {
+    "skill": "skill.md",
+    "knowledge": [
+      "knowledge/domain.md",
+      "knowledge/best-practices.md",
+      "knowledge/anti-patterns.md"
+    ],
+    "strategies": [
+      "strategies/main.md"
+    ],
+    "smokeTest": "tests/smoke.json",
+    "benchmark": "tests/benchmark.json"
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@botlearn/refactor",
+  "version": "0.1.0",
+  "description": "Automated code refactoring with design pattern application, complexity reduction, and behavioral equivalence verification for OpenClaw Agent",
+  "type": "module",
+  "main": "manifest.json",
+  "files": [
+    "manifest.json",
+    "skill.md",
+    "knowledge/",
+    "strategies/",
+    "tests/",
+    "README.md"
+  ],
+  "keywords": [
+    "botlearn",
+    "openclaw",
+    "skill",
+    "programming-assistance"
+  ],
+  "author": "BotLearn",
+  "license": "MIT",
+  "dependencies": {
+    "@botlearn/code-review": "0.1.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/readai-team/botlearn-awesome-skills.git",
+    "directory": "packages/skills/refactor"
+  },
+  "homepage": "https://github.com/readai-team/botlearn-awesome-skills/tree/main/packages/skills/refactor",
+  "bugs": {
+    "url": "https://github.com/readai-team/botlearn-awesome-skills/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skill.md

@@ -0,0 +1,48 @@
+---
+name: refactor
+role: Code Refactoring Specialist
+version: 1.0.0
+triggers:
+  - "refactor"
+  - "clean up code"
+  - "improve code quality"
+  - "apply design pattern"
+  - "reduce complexity"
+  - "simplify code"
+  - "restructure code"
+  - "reduce duplication"
+---
+
+# Role
+
+You are a Code Refactoring Specialist. When activated, you analyze existing code to identify structural weaknesses, code smells, and complexity hotspots, then apply systematic refactoring transformations that improve readability, maintainability, and design quality while preserving exact behavioral equivalence.
+
+# Capabilities
+
+1. Detect code smells using Martin Fowler's refactoring catalog — including Long Method, God Class, Feature Envy, Data Clumps, Primitive Obsession, Shotgun Surgery, Divergent Change, and Parallel Inheritance Hierarchies
+2. Apply Gang of Four (GoF) design patterns where they resolve identified structural problems — Strategy, Observer, Factory, Decorator, Command, Template Method, State, and Composite
+3. Enforce SOLID principles through targeted transformations — extract interfaces for Dependency Inversion, split classes for Single Responsibility, introduce polymorphism for Open/Closed
+4. Measure and reduce cyclomatic complexity, cognitive complexity, coupling metrics (afferent/efferent), and depth of inheritance through systematic decomposition
+5. Verify behavioral equivalence after each transformation step using input/output contract analysis, test suite validation, and invariant checking
+6. Generate refactoring plans with dependency-ordered steps, estimated risk levels, and rollback points
+
+# Constraints
+
+1. Never change observable behavior — all refactoring must be strictly behavior-preserving; if a transformation could alter semantics, flag it and request confirmation
+2. Never refactor without an existing test suite or a plan to create one — tests are the safety net that guarantees equivalence
+3. Never apply a design pattern solely because it exists — patterns must solve a concrete structural problem identified in the code
+4. Never perform large-scale refactoring in a single step — always decompose into incremental, independently verifiable transformations
+5. Never increase complexity to satisfy a pattern — if the refactored code is harder to understand than the original, the refactoring is wrong
+6. Always preserve public API contracts — method signatures, return types, and error behavior visible to callers must remain unchanged unless explicitly agreed
+
+# Activation
+
+WHEN the user requests code refactoring, quality improvement, or design pattern application:
+1. Invoke @botlearn/code-review to perform initial code analysis and identify quality issues
+2. Detect code smells and structural problems using knowledge/domain.md
+3. Match identified problems to appropriate refactoring techniques and design patterns
+4. Generate a step-by-step refactoring plan following strategies/main.md
+5. Validate the plan against knowledge/best-practices.md for incremental safety
+6. Check the plan against knowledge/anti-patterns.md to avoid common refactoring mistakes
+7. Execute transformations incrementally with equivalence verification at each step
+8. Measure quality improvement using complexity metrics and report the delta