@lenardangeloolajay/len-toolkit 1.1.0

package/templates/skills/working-effectively-with-legacy-code/working-effectively-with-legacy-code.md

@@ -0,0 +1,371 @@
+# OBEY Working Effectively with Legacy Code by Michael Feathers
+
+## Purpose
+
+This repository follows the discipline of **Working Effectively with Legacy Code** in the sense of Michael Feathers:
+make risky existing code changeable by gaining understanding, creating seams, and establishing tests.
+
+All code generation, edits, and reviews must optimize for:
+- safe change in poorly understood code
+- characterization before redesign
+- breaking dependencies that block tests
+- introducing seams
+- reducing fear around modification
+- incremental improvement instead of heroic rewrites
+
+This file is a binding engineering policy: `MUST` is binding, `SHOULD` is a strong default, and `MUST NOT` is forbidden.
+
+---
+
+## Primary Directive
+
+Legacy code is code that is expensive to change safely.
+In practice, the default assumption is:
+
+**If a part of the code lacks trustworthy tests, treat it as legacy code.**
+
+When modifying legacy code:
+1. understand what it does now
+2. protect that behavior with tests where possible
+3. find or create a seam
+4. break dependencies that prevent observation or isolation
+5. make the requested change
+6. leave the area more testable than before
+
+Do not begin with a rewrite unless explicitly required.
+
+---
+
+## Non-Negotiable Rules
+
+1. **Do Not Rewrite by Reflex**
+   - Prefer targeted extraction and improvement.
+   - Rewrite only when explicitly requested or clearly safer than continued change.
+
+2. **Characterize Before You Redesign**
+   - When current behavior is uncertain, capture it.
+   - Use characterization tests to document what the code does today, even if the behavior is ugly.
+
+3. **Find or Create a Seam**
+   - A seam is a place where behavior can be changed without editing the surrounding code directly.
+   - Use seams to inject doubles, isolate dependencies, and observe behavior.
+
+4. **Break Dependencies Deliberately**
+   - Remove direct dependence on time, randomness, files, network, process environment, globals, frameworks, and static construction where they block testing.
+
+5. **Leave the Code More Changeable**
+   - Every change should ideally improve testability, visibility, or modularity.
+
+---
+
+## Default Workflow for Legacy Changes
+
+1. Identify the exact area affected.
+2. Determine whether trusted tests already protect the behavior.
+3. If not, add characterization tests around current behavior where possible.
+4. Identify the dependency that makes change difficult.
+5. Introduce or exploit a seam.
+6. Break the blocking dependency.
+7. Make the functional change.
+8. Refactor for clarity and keep the seam or new structure if it still pays for itself.
+
+Short form: identify change points, find test points, break dependencies, write tests, make changes, then refactor.
+
+Do not start by cleaning the whole module.
+
+---
+
+## Testing Strategy Rules
+
+### Characterization Tests
+1. Use characterization tests when you do not yet know whether the current behavior is intentional.
+2. Test externally visible behavior first.
+3. Prefer narrow tests around the slice you are about to modify.
+4. Capture ugly behavior if real consumers rely on it.
+5. Once behavior is protected, improve structure safely.
+6. Mark suspicious current behavior for clarification instead of silently "fixing" it during characterization.
+7. Use sensing variables or temporary probes only to confirm that a test reaches the intended path; remove them after use.
+
+### New Behavior Tests
+1. Add focused tests for the requested change.
+2. Keep old behavior tests unless the behavior change is intentional.
+3. Separate tests that describe legacy behavior from tests that describe the new requirement when useful.
+
+### Testability Improvements
+1. Make dependencies explicit.
+2. Remove hard-coded collaborators.
+3. Break apart mixed responsibilities that force expensive setup.
+4. Reduce constructor side effects and static initialization side effects.
+
+---
+
+## Seam Rules
+
+### What Counts as a Useful Seam
+A useful seam is any boundary that allows substitution, observation, or interception.
+
+Examples:
+- constructor injection
+- parameter injection
+- extracted method
+- wrapper around static call
+- adapter around framework object
+- factory indirection
+- module boundary
+- link seam, import seam, or preprocessing seam where the language/build system supports it
+- subclass seam when forced by language constraints
+
+### Required Behavior
+1. Use the smallest seam that unlocks the change.
+2. Prefer explicit seams over magical test hooks.
+3. Prefer seams that remain useful after the current task.
+4. Create seams near hard dependencies, not randomly in the code.
+5. Separate sensing from separation: decide whether the seam observes behavior, substitutes a dependency, or both.
+6. Use link and preprocessing seams carefully; they can unlock tests but do not usually improve design by themselves.
+
+---
+
+## Dependency Breaking Rules
+
+When legacy code is hard to test, first look for these dependency types:
+
+### Hidden Inputs
+- current time
+- random values
+- environment variables
+- thread-local state
+- static singletons
+- global configuration
+- implicit current user or request
+
+### Hard Outputs
+- direct file writes
+- direct network calls
+- process exits
+- direct database writes
+- direct message publication
+- logging used as control flow
+
+### Construction Problems
+- constructors that do real work
+- new allocations of complex collaborators buried inside methods
+- factory calls hidden deep in behavior
+- object graphs built in the middle of logic
+
+### Required Moves
+- wrap static and global access
+- inject clocks, random generators, external interfaces, and hard collaborators
+- split construction from use
+- extract side effects behind explicit collaborators
+- narrow the code under test to a manageable slice
+
+---
+
+## Test Selection and Understanding Rules
+
+1. Use effect sketches when the impact of a change is unclear.
+2. Start from the change point and trace affected values, calls, fields, outputs, and collaborators outward.
+3. Choose test points where effects can be observed with useful precision.
+4. Use interception points when several planned changes can be protected by one broader test.
+5. Use pinch points when many effects pass through one narrow point.
+6. Treat broad tests at interception points as a first step toward narrower tests.
+7. Use scratch refactoring to understand code, but discard it unless later backed by tests and review.
+8. Sketch, mark, or group responsibilities in large code before moving behavior.
+9. Do not check in exploratory restructuring that was only used to learn.
+
+---
+
+## Preferred Legacy Techniques
+
+### Sprout Method
+Use when new behavior can be added without deeply editing fragile code.
+
+Rules (MUST unless marked SHOULD or MUST NOT):
+- extract the new behavior into a new method
+- keep the old code mostly untouched
+- route to the new method from a small insertion point
+
+### Sprout Class
+Use when a new responsibility does not fit the old class or the old class is too risky to reshape first.
+
+Rules (MUST unless marked SHOULD or MUST NOT):
+- add a focused new collaborator
+- delegate from the legacy class
+- slowly move behavior over if later justified
+
+### Wrap Method
+Use when you need pre/post behavior around a risky method or a better way to observe effects.
+
+### Wrap Class
+Use when a class is too hard to test directly and behavior can be mediated through a new abstraction.
+
+### Extract and Override Call
+Use only when language constraints leave few better options.
+Prefer composition once a cleaner route appears.
+
+---
+
+## Dependency-Breaking Technique Index
+
+- USE Adapt Parameter when a method needs only a narrow view of a hard-to-create parameter.
+- USE Break Out Method Object when a large method has local state that blocks extraction and testing.
+- USE Definition Completion when missing definitions block tests in languages that allow completion in test code.
+- USE Encapsulate Global References when globals or singletons prevent substitution.
+- USE Expose Static Method when useful logic does not need instance state but is trapped behind instance setup.
+- USE Extract and Override Factory Method when construction of a hard dependency must vary under test.
+- USE Extract Implementer or Extract Interface when concrete dependencies make compilation or substitution hard.
+- USE Introduce Instance Delegator when static behavior needs an instance seam.
+- USE Parameterize Constructor or Parameterize Method when hidden collaborators should become explicit inputs.
+- USE Primitivize Parameter only when the real type is too costly to bring into a harness and primitive data is enough for the new logic.
+- USE Pull Up Feature or Push Down Dependency to move behavior or dependencies to a more testable level in a hierarchy.
+- USE Replace Global Reference with Getter when direct global access needs a seam.
+- USE Subclass and Override Method only when safer composition seams are not available.
+- USE Supersede Instance Variable when a test needs to replace a hard dependency held in a field.
+- USE Template Redefinition, Text Redefinition, link seams, or preprocessing seams only when language or build constraints make ordinary object seams impractical.
+
+---
+
+## Legacy Refactoring Heuristics
+
+1. Work near the change point, not across the whole system.
+2. Prefer one small dependency break over a broad redesign.
+3. If a test requires too much setup, the design is telling you something useful.
+4. If code is impossible to observe, expose outcomes through smaller units.
+5. If code is impossible to invoke without full runtime setup, isolate the policy from the runtime.
+6. If code depends on many details, separate policy from mechanism.
+7. If the old code cannot be safely changed, insert new code beside it and redirect gradually.
+
+---
+
+## Handling Risky Areas
+
+### Large Methods
+- carve out pure computation first
+- isolate side effects second
+- add tests around extracted parts
+- avoid editing many branches at once
+
+### Static and Global Dependencies
+- create a wrapper or façade
+- move callers to the wrapper
+- inject the wrapper where possible
+- reduce direct calls incrementally
+
+### Database-Heavy Code
+- separate query and mapping concerns from policy
+- test policy without a real database where possible
+- keep integration tests for actual persistence behavior
+
+### UI or Framework Code
+- move decision logic out of handlers and callbacks
+- test the moved logic independently
+- keep adapters thin
+
+### Constructors Doing Too Much
+- stop doing I/O, network, or configuration lookup in constructors
+- move setup into factories, builders, or composition roots
+- keep constructed objects easy to instantiate under test
+
+---
+
+## Review Rules
+
+When reviewing legacy-oriented changes, actively look for:
+- no tests around modified logic
+- structural and behavioral changes mixed together
+- broad edits in poorly understood modules
+- hidden global dependencies left untouched
+- hard-coded collaborators
+- direct static calls
+- constructors with side effects
+- business logic trapped in framework entry points
+- places where a sprout method or sprout class lowers risk
+
+---
+
+## Forbidden Patterns
+
+### Rewrite as the First Move
+- replacing a subsystem before understanding current behavior
+- rebuilding instead of gaining test leverage
+- assuming old behavior is irrelevant because the code looks bad
+
+### No-Safety Change
+- changing legacy code with no tests or observation strategy
+- large edits with no characterization
+- relying on manual reasoning alone for risky behavior
+
+### Hidden Dependency Expansion
+- adding more globals, statics, ambient context, or framework reach-through in already hard-to-test code
+- embedding new hard dependencies in the same style as the legacy code
+
+### Cosmetic Refactoring Only
+- renaming and formatting while leaving the real dependency knots intact
+- “cleanup” that does not make the next change safer
+
+---
+
+## Code Generation Rules
+
+When asked to modify legacy code, default to producing:
+- characterization tests where needed
+- small seams
+- wrappers around hard dependencies
+- explicit collaborators
+- extracted pure logic
+- minimal structural edits that unlock safe change
+
+Preferred first moves:
+- extract method
+- wrap static call
+- inject collaborator
+- split construction from behavior
+- move logic out of framework entry points
+- introduce a focused new class for new behavior
+- add a narrow characterization test
+
+Preferred avoidance:
+- huge dependency-breaking rewrites
+- replacing old modules wholesale
+- introducing large new architectures before basic seams exist
+- mocking untestable structure instead of improving it
+
+---
+
+## Testing Rules
+
+1. Prefer fast tests around the behavior you are changing.
+2. Use characterization tests to lock current behavior before deeper edits.
+3. Prefer tests at the highest level that still isolate the change safely.
+4. Keep integration tests for real boundaries, but do not depend on them alone.
+5. Once a seam exists, test through the seam.
+
+---
+
+## Review Checklist
+
+Before finalizing any change, verify:
+- Did we treat untested code as risky legacy code?
+- Did we capture current behavior where it was unclear?
+- Did we create or exploit a seam?
+- Did we reduce at least one hard dependency?
+- Is the changed area easier to test than before?
+- Did we avoid a rewrite as the first move?
+- Did we keep edits local to the requested change?
+- Did we separate structural changes from behavior changes where practical?
+- Did we leave the code more changeable than we found it?
+
+If any answer is no, revise before shipping.
+
+---
+
+## Final Instruction
+
+When uncertain, choose the smallest change that:
+1. increases understanding
+2. increases testability
+3. breaks one hard dependency
+4. preserves current behavior
+5. makes the next change cheaper
+
+Reject big rewrites and heroic cleanup when a seam and a test would do.

package/templates/skills/working-effectively-with-legacy-code/working-effectively-with-legacy-code.mini.md

@@ -0,0 +1,50 @@
+# OBEY Working Effectively with Legacy Code by Michael Feathers
+
+## When to use
+
+Use when changing code that is expensive to change safely because behavior is unclear, tests are weak or missing, dependencies are hidden, or runtime/framework setup blocks local feedback.
+
+## Primary bias to correct
+
+Gain control before improving design. Understand current behavior, protect what must stay, create the smallest useful seam, break the dependency that blocks feedback, make the requested change, then leave the area more testable.
+
+## Decision rules
+
+- Treat any area without trustworthy tests as legacy code; do not start with rewrite or module-wide cleanup unless that is explicitly required or clearly safer.
+- Before editing, state the requested behavior change and the current behavior that must remain; characterize uncertain or suspicious behavior instead of silently fixing it.
+- Follow the legacy loop: identify the change point, check existing protection, add characterization where possible, find or create a seam, break the blocking dependency, change behavior, then refactor locally.
+- Prefer fast, focused tests around the slice being changed; use broader interception or integration tests only when they are the safest first observation point.
+- Choose test points by tracing effects outward from the change point through values, calls, fields, outputs, collaborators, interception points, and pinch points.
+- Use the smallest seam that allows substitution, observation, or interception; make clear whether the seam is for sensing, separation, or both.
+- Break dependencies deliberately: expose hidden inputs, hard outputs, hard construction, globals, statics, ambient context, and framework callbacks only where they block testing or safe change.
+- Keep behavior changes, structural refactorings, and cleanup separate; verify small steps and avoid checking in exploratory restructuring used only for understanding.
+- When direct edits are risky, add behavior with sprout method, sprout class, wrap method, wrap class, or extract-and-override style moves, then fold the temporary structure into better design when tests support it.
+- For hard-to-test methods, split construction from use, extract side effects behind collaborators, carve pure computation first, and isolate policy from runtime, persistence, UI, or framework mechanisms.
+- Use dependency-breaking techniques according to the actual barrier: adapt narrow parameters, extract interfaces or implementers, parameterize constructors or methods, encapsulate globals, introduce instance delegators, override factories/calls, or use link/preprocessing seams only when ordinary object seams are impractical.
+- In large code, sketch effects and group responsibilities before moving behavior; let excessive setup, impossible observation, and repeated changes point to smaller extracted responsibilities.
+- During review, treat no tests around modified logic, mixed structural and behavioral edits, broad edits in poorly understood modules, hard-coded collaborators, global/static reach-through, constructor side effects, and business logic trapped in framework entry points as legacy-change risks.
+- Reject changes that expand hidden dependencies, mock around untestable structure without improving it, rename or format while leaving the real dependency knots intact, or introduce large architecture before basic seams exist.
+- Leave the touched area easier to understand, test, or change; do not mistake test-only seams, wrappers, subclass tricks, or build tricks for design improvement by themselves.
+
+## Trigger rules
+
+- When behavior is uncertain, consumers may rely on ugly behavior, or a branch/path is hard to prove, add characterization or another explicit observation path before changing semantics.
+- When tests require too much setup or a class cannot be instantiated cheaply, break the first real barrier: constructor work, hidden allocation, factory call, global state, static construction, framework object, or hard parameter.
+- When time, randomness, environment, thread-local state, current user/request, files, network, process exits, database writes, messages, or control-flow logging block repeatable tests, wrap or inject that boundary.
+- When a large method or class defeats local reasoning, sketch effects, find interception or pinch points, extract pure computation first, and avoid editing many branches at once.
+- When changing database-heavy, UI, framework, or API-boundary code, separate policy from query/mapping/persistence, handlers/callbacks, adapters, and runtime setup; keep real-boundary integration tests where they matter.
+- When a seam is magical, temporary, public-for-test, subclass-only, link/preprocessor-based, or probe/sensing-variable-based, add a cleanup obligation and remove it once safer structure exists.
+- When repeated edits cluster across several places, remove duplication incrementally under tests instead of launching a broad redesign.
+- When rewrite or heroic cleanup feels tempting, choose the smallest sprout, wrap, seam, characterization, or refactoring step that makes today's requested change safer.
+
+## Final checklist
+
+- Untested or weakly tested area treated as legacy risk?
+- Behavior delta and behavior-to-preserve stated?
+- Uncertain current behavior characterized or explicitly observed?
+- Tests close enough and fast enough to diagnose the change?
+- Smallest useful seam chosen, with sensing vs separation clear?
+- Blocking dependency reduced without expanding hidden dependencies?
+- Behavior change, refactoring, and cleanup kept separate?
+- Temporary seam or dependency-breaking trick has a cleanup path?
+- Touched area is more understandable, testable, or changeable?

package/templates/skills/working-effectively-with-legacy-code/working-effectively-with-legacy-code.nano.md

@@ -0,0 +1,35 @@
+# OBEY Working Effectively with Legacy Code by Michael Feathers
+
+## When to use
+
+Use when changing poorly tested or poorly understood code under a tight context budget.
+
+## Primary bias to correct
+
+Legacy work starts with control, not cleanup, rewrite, or elegance.
+
+## Decision rules
+
+- Treat code without trustworthy tests as legacy code: state what changes and what must remain.
+- Characterize uncertain current behavior before changing it, including ugly behavior consumers may rely on.
+- Use the legacy loop: find the change point, find an observation point, create or exploit a seam, break the blocking dependency, test, change, then refactor locally.
+- Prefer fast focused tests; use broader harnesses only as temporary first coverage when no narrow test point exists.
+- Create the narrowest useful seam for sensing or separation, and break only dependencies that block feedback.
+- Use sprout, wrap, parameterize, inject, extract, or override moves when direct edits would be unsafe.
+- Keep behavior changes, structural refactorings, and cleanup separate and small.
+- Do not leave test-only seams, hidden dependencies, wrappers, globals, subclass tricks, or link/preprocessor tricks without a cleanup plan.
+
+## Trigger rules
+
+- When behavior is unclear, characterize first.
+- When constructors, globals, statics, frameworks, I/O, clocks, randomness, environment, or deep object graphs block testing, break one dependency at the narrowest point.
+- When a large method or class defeats local reasoning, sketch effects and create a seam before semantic edits.
+- When rewrite or broad cleanup feels tempting, choose the next smaller verified move.
+
+## Final checklist
+
+- Behavior characterized?
+- Feedback fast enough?
+- Dependency isolated?
+- One kind of change?
+- Safer and clearer now?