@lenardangeloolajay/len-toolkit 1.1.0

package/templates/skills/ponytail-debt/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: ponytail-debt
+description: >
+  Harvest every `ponytail:` comment in the codebase into a debt ledger, so the
+  deliberate shortcuts and deferrals ponytail leaves behind get tracked instead
+  of rotting into "later means never". Use when the user says "ponytail debt",
+  "/ponytail-debt", "what did ponytail defer", "list the shortcuts", "ponytail
+  ledger", or "what did we mark to do later". One-shot report, changes nothing.
+license: MIT
+---
+
+Every deliberate ponytail shortcut is marked with a `ponytail:` comment naming
+its ceiling and upgrade path. This collects them into one ledger so a deferral
+can't quietly become permanent.
+
+## Scan
+
+Grep the repo for comment markers, skipping `node_modules`, `.git`, and build
+output:
+
+`grep -rnE '(#|//) ?ponytail:' .`  (add other comment prefixes if your stack uses them)
+
+Each hit is one ledger row. The comment prefix keeps prose that merely mentions
+the convention out of the ledger.
+
+## Output
+
+One row per marker, grouped by file:
+
+`<file>:<line>, <what was simplified>. ceiling: <the limit named>. upgrade: <the trigger to revisit>.`
+
+The convention is `ponytail: <ceiling>, <upgrade path>`, so pull the ceiling
+and the trigger straight from the comment. Want an owner per row too? add
+`git blame -L<line>,<line>`.
+
+Flag the rot risk: any `ponytail:` comment that names no upgrade path or
+trigger gets a `no-trigger` tag, those are the ones that silently rot.
+
+End with `<N> markers, <M> with no trigger.` Nothing found: `No ponytail: debt. Clean ledger.`
+
+## Boundaries
+
+Reads and reports only, changes nothing. To persist it, ask and it writes the
+ledger to a file (e.g. `PONYTAIL-DEBT.md`). One-shot. "stop ponytail-debt" or
+"normal mode" to revert.
+
+
+Read project AGENTS.md for shared workflow, scope, and evidence policy.

package/templates/skills/ponytail-gain/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: ponytail-gain
+description: >
+  Report Ponytail impact only from available, attributable benchmark evidence.
+  Use for ponytail gain or scoreboard requests; never infer savings for this repo.
+license: MIT
+---
+
+# Ponytail gain
+
+Read project AGENTS.md for evidence policy.
+The original upstream benchmark dataset is not bundled with this toolkit.
+If no verified benchmark evidence is available, report that savings are unverified here rather than displaying unsupported percentages.
+If evidence is supplied, state its source, conditions, measured baseline, and limitations before reporting results.
+Never extrapolate benchmark results into savings for the current project or compare against an implementation that was never built.
+Use ponytail-debt for counted shortcuts and ponytail-audit for proposed reductions, labeling proposals as estimates.
+This is a read-only report and does not change modes or files.

package/templates/skills/ponytail-help/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: ponytail-help
+description: >
+  Quick-reference card for all ponytail modes, skills, and commands.
+  One-shot display, not a persistent mode. Trigger: /ponytail-help,
+  "ponytail help", "what ponytail commands", "how do I use ponytail".
+license: MIT
+---
+
+# Ponytail Help
+
+Display this reference card when invoked. One-shot, do NOT change mode,
+write flag files, or persist anything.
+
+## Levels
+
+| Level | Trigger | What change |
+|-------|---------|-------------|
+| **Lite** | `/ponytail lite` | Build what's asked, name the lazier alternative in one line. |
+| **Full** | `/ponytail` | The ladder enforced: YAGNI → stdlib → native → one line → minimum. Default. |
+| **Ultra** | `/ponytail ultra` | YAGNI extremist. Deletion before addition. Challenges requirements before building. |
+
+Level sticks until changed or session end.
+
+## Skills
+
+| Skill | Trigger | What it does |
+|-------|---------|--------------|
+| **ponytail** | `/ponytail` | Lazy mode itself. Simplest solution that works. |
+| **ponytail-review** | `/ponytail-review` | Over-engineering review: `L42: yagni: factory, one product. Inline.` |
+| **ponytail-audit** | `/ponytail-audit` | Whole-repo over-engineering audit: ranked list of what to delete. |
+| **ponytail-debt** | `/ponytail-debt` | Harvest `ponytail:` shortcut comments into a tracked ledger. |
+| **ponytail-gain** | `/ponytail-gain` | Measured-impact scoreboard: less code, less cost, more speed. |
+| **ponytail-help** | `/ponytail-help` | This card. |
+
+## Deactivate
+
+Say "stop ponytail" or "normal mode". Resume anytime with `/ponytail`.
+`/ponytail off` also works.
+
+
+Read project AGENTS.md for shared workflow, scope, and evidence policy.

package/templates/skills/ponytail-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: ponytail-review
+description: >
+  Code review focused exclusively on over-engineering. Finds what to delete:
+  reinvented standard library, unneeded dependencies, speculative abstractions,
+  dead flexibility. One line per finding: location, what to cut, what replaces
+  it. Use when the user says "review for over-engineering", "what can we
+  delete", "is this over-engineered", "simplify review", or invokes
+  /ponytail-review. Complements correctness-focused review, this one only
+  hunts complexity.
+license: MIT
+---
+
+Review diffs for unnecessary complexity. One line per finding: location, what
+to cut, what replaces it. The diff's best outcome is getting shorter.
+
+## Format
+
+`L<line>: <tag> <what>. <replacement>.`, or `<file>:L<line>: ...` for
+multi-file diffs.
+
+Tags:
+
+- `delete:` dead code, unused flexibility, speculative feature. Replacement: nothing.
+- `stdlib:` hand-rolled thing the standard library ships. Name the function.
+- `native:` dependency or code doing what the platform already does. Name the feature.
+- `yagni:` abstraction with one implementation, config nobody sets, layer with one caller.
+- `shrink:` same logic, fewer lines. Show the shorter form.
+
+## Examples
+
+❌ "This EmailValidator class might be more complex than necessary, have you
+considered whether all these validation rules are needed at this stage?"
+
+✅ `L12-38: stdlib: 27-line validator class. "@" in email, 1 line, real validation is the confirmation mail.`
+
+✅ `L4: native: moment.js imported for one format call. Intl.DateTimeFormat, 0 deps.`
+
+✅ `repo.py:L88: yagni: AbstractRepository with one implementation. Inline it until a second one exists.`
+
+✅ `L52-71: delete: retry wrapper around an idempotent local call. Nothing replaces it.`
+
+✅ `L30-44: shrink: manual loop builds dict. dict(zip(keys, values)), 1 line.`
+
+## Scoring
+
+End with the only metric that matters: `net: -<N> lines possible.`
+
+If there is nothing to cut, say `Lean already. Ship.` and stop.
+
+## Boundaries
+
+Scope: over-engineering and complexity only. Correctness bugs, security holes,
+and performance are explicitly out of scope. Route them to a normal review
+pass, not this one. A single smoke test or `assert`-based
+self-check is the ponytail minimum, not bloat, never flag it for deletion.
+Does not apply the fixes, only lists them.
+"stop ponytail-review" or "normal mode": revert to verbose review style.
+
+
+Read project AGENTS.md for shared workflow, scope, and evidence policy.

package/templates/skills/refactoring/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: refactoring
+description: Apply Martin Fowler-inspired refactoring rules when improving existing code structure while preserving observable behavior.
+license: MIT
+---
+
+# Refactoring Skill
+
+Use this skill when a task involves behavior-preserving code improvement, code smells, small refactoring steps, test-backed cleanup, or separating refactoring from feature changes.
+
+Before making design or code decisions, read and apply [refactoring.mini.md](refactoring.mini.md). Use [refactoring.md](refactoring.md) only as a deeper reference when the mini rules are not enough for the current refactoring tradeoff.

package/templates/skills/refactoring/refactoring.md

@@ -0,0 +1,433 @@
+# OBEY Refactoring by Martin Fowler
+
+## Purpose
+
+This repository follows the discipline of **Refactoring** in the sense of Martin Fowler:
+improve the internal structure of code **without changing its observable behavior**.
+
+All code generation, edits, and reviews must optimize for:
+- small behavior-preserving changes
+- clearer names and simpler control flow
+- lower duplication
+- smaller units of responsibility
+- explicit movement from bad design toward good design
+- steady design improvement as part of daily work
+
+This file is a binding engineering policy: `MUST` is binding, `SHOULD` is a strong default, and `MUST NOT` is forbidden.
+
+---
+
+## Primary Directive
+
+When modifying existing code, do **not** start by rewriting large areas.
+Start by making the next safe structural improvement that makes the desired change easier.
+
+Prefer:
+1. establish a safety net
+2. make a preparatory refactoring
+3. make the functional change
+4. refactor again if needed
+
+Reject changes that bundle large functional changes with unrelated structural churn.
+
+---
+
+## What Counts as Refactoring
+
+Refactoring here means:
+- changing structure without changing external behavior
+- applying small, composable transformations
+- removing code smells before or during feature work
+- making the next change easier
+- improving readability, locality, and testability
+
+Refactoring here does **not** mean:
+- large rewrites
+- unverified cleanup
+- “modernization” with unclear behavioral impact
+- renaming everything at once
+- mixing architecture migration, feature work, and cleanup in one uncontrolled patch
+
+---
+
+## Non-Negotiable Rules
+
+1. **Preserve Behavior**
+   - Refactorings must preserve observable behavior.
+   - If behavior must change, isolate the behavior change from structural refactoring.
+   - Never disguise a feature change as a refactoring.
+
+2. **Work in Small Steps**
+   - Prefer many small safe edits over one large transformation.
+   - Each step should be understandable and reversible.
+   - If a patch feels too large to reason about locally, split it.
+
+3. **Keep the System Running**
+   - Do not leave code in a broken intermediate state unless explicitly asked for a draft.
+   - Every refactoring sequence should maintain a runnable, buildable state where practical.
+
+4. **Refactor Before and After Feature Work**
+   - If code is hard to change, first reshape it.
+   - After the feature lands, clean remaining structural debt introduced by the change.
+
+5. **Use the Simplest Helpful Refactoring**
+   - Do not introduce patterns or abstractions earlier than needed.
+   - Prefer local simplification before large-scale abstraction.
+
+---
+
+## Safety Rules
+
+### Tests and Verification
+1. Create or identify a safety net before risky refactoring.
+2. Prefer characterization tests when working on unclear existing behavior.
+3. If tests are absent, make the smallest changes possible and improve testability first.
+4. Keep refactoring and test updates aligned with preserved behavior.
+5. Never delete a failing test just to complete a refactoring.
+
+### Commit and Patch Discipline
+1. Separate structural edits from behavior changes whenever practical.
+2. Group related refactorings together.
+3. Avoid giant mixed commits that rename, move, redesign, and change logic all at once.
+4. Prefer reviewable sequences of transformations.
+
+### Preparatory Refactoring
+Before implementing a feature, ask:
+- what makes this change awkward?
+- what local structural change would make it straightforward?
+- can I rename, extract, move, split, or inline first?
+
+Do the preparatory refactoring before the feature change.
+
+---
+
+## Code Smell Policy
+
+When modifying code, actively look for these smells.
+
+### Duplicated Code
+- Duplicate logic is a default target for elimination.
+- Remove duplication by extracting shared behavior, not by introducing vague utility dumping grounds.
+- Do not abstract coincidental similarity.
+
+### Long Functions
+- Split long functions when they mix responsibilities, levels of abstraction, or phases of work.
+- Extract meaningful chunks with names that explain intent.
+- Do not create micro-method noise with no explanatory value.
+
+### Long Parameter Lists
+- Replace repeated clumps with parameter objects or richer domain objects where appropriate.
+- Remove boolean flags that switch behavior.
+- Avoid signatures that require callers to memorize argument order.
+
+### Global Data and Hidden Dependencies
+- Reduce reliance on globals, singletons, and ambient context.
+- Make dependencies explicit where possible.
+- Refactor toward injection, parameters, or clear ownership.
+
+### Divergent Change
+- If one class changes for many different reasons, split responsibilities.
+- Separate business logic, formatting, transport, persistence, and integration concerns.
+
+### Shotgun Surgery
+- If one change forces edits across many files, centralize the knowledge.
+- Introduce a better boundary or clearer ownership.
+
+### Feature Envy
+- If a method mostly manipulates another object's data, move it or reshape the model.
+- Put behavior near the data or concept it belongs to.
+
+### Data Clumps and Primitive Obsession
+- Replace repeated primitive bundles with meaningful types.
+- Give recurring business concepts names and validation.
+
+### Switch Statements and Conditionals
+- Reduce repeated branching on type or mode when polymorphism, tables, strategies, or better data structures fit.
+- Do not replace a single honest conditional with needless indirection.
+
+### Temporary Fields and Weird Lifecycles
+- Remove fields that exist only for unusual code paths when a separate object or clearer phase model is better.
+- Prefer modeling states explicitly over half-initialized objects.
+
+### Middle Man and Speculative Generality
+- Remove forwarding layers that add no value.
+- Delete abstractions created “just in case” if they are not earning their keep.
+
+---
+
+## Preferred Refactoring Moves
+
+### Naming Refactorings
+- Rename variables to reveal intent.
+- Rename functions to describe behavior, not mechanism.
+- Rename types and modules to align with problem-domain terminology.
+- Rename before deeper refactoring when bad names block understanding.
+
+### Extraction Refactorings
+- Extract function when a block has a coherent purpose.
+- Extract variable when an expression is hard to read.
+- Extract class when one class has multiple reasons to change.
+- Extract module when a file mixes unrelated concerns.
+
+### Movement Refactorings
+- Move function to the module or type where the data or concept lives.
+- Move field when ownership is clearer elsewhere.
+- Move statements to group related operations and reduce cognitive jumps.
+
+### Simplification Refactorings
+- Inline accidental abstractions.
+- Collapse unnecessary layers.
+- Replace nested conditionals with guard clauses where it improves clarity.
+- Consolidate duplicate conditional fragments.
+
+### Data Refactorings
+- Encapsulate mutable state.
+- Replace magic values with named constants or domain types.
+- Introduce parameter objects for repeated argument groups.
+- Replace raw collections with named abstractions when behavior accumulates around them.
+
+---
+
+## Refactoring Catalog Index
+
+### Composing Methods
+- USE Extract Method when a code fragment has a coherent purpose and a useful name.
+- USE Inline Method when a method body is clearer than its indirection.
+- USE Inline Temp when a temporary variable obscures a direct expression.
+- USE Replace Temp with Query when a calculated value deserves a named query and can be reused safely.
+- USE Introduce Explaining Variable when a complex expression needs named parts.
+- USE Split Temporary Variable when one variable carries multiple meanings.
+- USE Remove Assignments to Parameters when parameter mutation obscures input meaning.
+- USE Replace Method with Method Object when local state prevents clean extraction.
+- USE Substitute Algorithm when a clearer algorithm can replace a tangled one without changing behavior.
+
+### Moving Features
+- USE Move Method or Move Field when behavior or state belongs more naturally to another object.
+- USE Extract Class when one class has more than one reason to change.
+- USE Inline Class when a class no longer earns its existence.
+- USE Hide Delegate when clients know too much about an object's collaborator.
+- USE Remove Middle Man when a forwarding object no longer hides useful detail.
+- USE Introduce Foreign Method only when you cannot edit the class that should own the behavior.
+- USE Introduce Local Extension when repeated foreign methods need a local, coherent extension point.
+
+### Organizing Data
+- USE Self Encapsulate Field when direct field access blocks flexibility.
+- USE Replace Data Value with Object when a primitive carries behavior, validation, or meaning.
+- USE Change Value to Reference when identity and shared updates matter.
+- USE Change Reference to Value when value semantics simplify ownership.
+- USE Replace Array with Object when positions in a collection have names or rules.
+- USE Duplicate Observed Data only when UI or framework synchronization forces it; keep synchronization explicit.
+- USE Change Unidirectional Association to Bidirectional only when traversal is needed both ways.
+- USE Change Bidirectional Association to Unidirectional when one direction is unnecessary coupling.
+- USE Encapsulate Collection when external mutation can bypass invariants.
+- USE Replace Record with Data Class when raw records need named access and behavior can grow safely.
+- USE Replace Type Code with Class, Subclasses, or State/Strategy according to whether behavior varies by type.
+- USE Replace Subclass with Fields when subclass variation is only data.
+
+### Simplifying Calls and Conditionals
+- USE Decompose Conditional, Consolidate Conditional Expression, and Consolidate Duplicate Conditional Fragments to make branching intent visible.
+- USE Remove Control Flag when loop or conditional state can be expressed directly.
+- USE Replace Nested Conditional with Guard Clauses when it clarifies the normal path.
+- USE Replace Conditional with Polymorphism only when repeated type-based behavior justifies it.
+- USE Introduce Null Object when repeated null behavior has a stable meaning.
+- USE Introduce Assertion when an assumption should be explicit during development.
+- USE Rename Method, Add Parameter, Remove Parameter, Parameterize Method, or Replace Parameter with Explicit Methods to make caller intent clearer.
+- USE Preserve Whole Object when callers pass several values from the same object.
+- USE Replace Parameter with Method when the receiver can obtain the value itself without hidden coupling.
+- USE Remove Setting Method when post-construction mutation should not be allowed.
+- USE Hide Method when public surface exposes unnecessary operations.
+- USE Replace Constructor with Factory Method when creation intent or subtype selection needs a name.
+- USE Encapsulate Downcast when callers should not own cast details.
+- USE Replace Error Code with Exception or Replace Exception with Test according to the expected failure model.
+
+### Generalization and Big Refactorings
+- USE Pull Up Field, Pull Up Method, or Pull Up Constructor Body when duplicated superclass behavior is real.
+- USE Push Down Method or Push Down Field when only some subclasses need the feature.
+- USE Extract Subclass, Extract Superclass, or Extract Interface only when callers or variation points justify them.
+- USE Collapse Hierarchy when inheritance no longer adds meaning.
+- USE Form Template Method when similar algorithms differ in controlled steps.
+- USE Replace Inheritance with Delegation when inheritance couples unrelated responsibilities.
+- USE Replace Delegation with Inheritance only when the subtype relationship is genuine and stable.
+- USE Tease Apart Inheritance when one hierarchy mixes multiple variation axes.
+- USE Convert Procedural Design to Objects when data and behavior need clearer ownership.
+- USE Separate Domain from Presentation when UI and policy are tangled.
+- USE Extract Hierarchy when several types share behavior with meaningful variation.
+
+---
+
+## Function-Level Rules
+
+1. One function should usually perform one coherent task.
+2. Keep abstraction level consistent inside a function.
+3. Remove hidden side effects unless the function's purpose is to cause them.
+4. Prefer guard clauses over deeply nested conditionals when that clarifies the happy path.
+5. Split phases like parsing, validation, computation, and I/O when they are mixed together.
+6. Keep variable scope tight.
+7. Delete dead code rather than comment it out.
+
+---
+
+## Class and Module Rules
+
+1. A class or module should have a narrow reason to change.
+2. Separate policy from presentation, I/O, persistence, and framework details.
+3. Prefer composition of small focused units over god objects.
+4. Delete or inline abstractions that no longer pay for themselves.
+5. Do not create `utils`, `helpers`, or `common` modules as a default response to duplication.
+6. Organize modules around concepts and behavior, not leftover convenience.
+
+---
+
+## Rules for Working with Conditionals
+
+1. Replace repeated branching on type or status with stronger modeling when useful.
+2. Use lookup tables for stable mapping logic.
+3. Replace nested if/else pyramids with guard clauses, extracted predicates, or strategies when that reduces branching complexity.
+4. Keep explicit conditionals when they are simple and honest.
+5. Never introduce polymorphism merely to avoid a small local conditional.
+
+---
+
+## Data and Mutation Rules
+
+1. Encapsulate mutation.
+2. Narrow write access to the smallest useful surface.
+3. Replace ad hoc mutations with intention-revealing operations.
+4. Remove duplicated update logic by centralizing state transitions.
+5. Prefer immutable intermediate values when that simplifies reasoning.
+
+---
+
+## Error Handling Rules
+
+1. Refactor error handling to make the main path visible.
+2. Keep cleanup, validation, and recovery logic from drowning core behavior.
+3. Standardize similar error paths when they duplicate structure.
+4. Preserve existing error semantics unless intentionally changing behavior.
+
+---
+
+## Review Rules
+
+When reviewing or generating changes, actively look for:
+- duplicated logic
+- long functions
+- long classes
+- tangled control flow
+- mixed abstraction levels
+- feature envy
+- shotgun surgery
+- divergent change
+- pass-through layers
+- speculative generality
+- hidden side effects
+- global state reliance
+- code that requires too much context to change safely
+
+---
+
+## Forbidden Patterns
+
+Do not generate or keep these patterns unless explicitly required and justified.
+
+### Big-Bang Rewrite
+- replacing a working subsystem wholesale to “clean it up”
+- rewriting before understanding current behavior
+- changing structure and behavior in one giant move
+
+### Mixed-Intent Patches
+- feature work mixed with huge unrelated renames
+- behavior changes hidden inside cleanup
+- code motion that makes review impossible
+
+### Abstracting Too Early
+- introducing interfaces or strategy hierarchies before a second real need appears
+- creating common libraries for one caller
+- replacing understandable duplication with unclear shared code
+
+### Refactoring Theater
+- renaming things while deeper design problems remain untouched
+- introducing patterns instead of removing complexity
+- creating more files, layers, or wrappers without improving changeability
+
+### Untested Structural Surgery
+- large refactors without any safety net
+- “cleanup” on fragile code with no verification strategy
+- assuming behavior is obvious when it is not
+
+---
+
+## Code Generation Rules
+
+When asked to modify existing code, use this default order:
+1. understand current behavior
+2. identify the friction for the requested change
+3. add or improve the safety net if needed
+4. perform preparatory refactoring
+5. implement the behavioral change
+6. perform follow-up cleanup
+7. stop when the design is clearly better
+
+Preferred first moves:
+- rename badly named things
+- extract coherent functions
+- isolate side effects
+- split mixed responsibilities
+- move behavior closer to the owning concept
+- remove duplication
+- simplify conditionals
+
+Preferred avoidance:
+- unnecessary framework migrations
+- gratuitous API redesign
+- large hierarchy introduction
+- replacing all old code with new code because the old code is ugly
+
+---
+
+## Testing Rules
+
+1. Add characterization tests before risky edits when behavior is unclear.
+2. Keep tests focused on externally visible behavior.
+3. Update tests only when behavior intentionally changes.
+4. Do not couple tests to private implementation details more than necessary.
+5. Refactor tests too when they become noisy or duplicative.
+6. Keep test data expressive and minimal.
+
+---
+
+## Stopping Rules
+
+Stop refactoring when:
+- the requested change is easy to implement
+- the main smells blocking change are removed
+- further cleanup would become speculative
+- the next abstraction is not yet justified
+- readability and local changeability are clearly improved
+
+---
+
+## Review Checklist
+
+Before finalizing any change, verify:
+- Did we preserve observable behavior during refactoring?
+- Did we separate structural change from behavior change where practical?
+- Did we remove at least one real source of friction?
+- Is the code easier to read than before?
+- Is the code easier to test or change than before?
+- Did we reduce duplication or accidental complexity?
+- Did we avoid speculative abstraction?
+- Did we avoid a giant mixed patch?
+- Did names improve?
+- Did control flow become simpler?
+- Did responsibilities become clearer?
+
+If any answer is no, revise before shipping.
+
+---
+
+## Final Instruction
+
+When uncertain, choose the next **small, behavior-preserving transformation**
+that makes the requested change easier and the code easier to understand.
+Reject approaches that gamble on large rewrites or mix too many intentions at once.

package/templates/skills/refactoring/refactoring.mini.md

@@ -0,0 +1,49 @@
+# OBEY Refactoring by Martin Fowler
+
+## When to use
+
+Use when changing existing code, preparing a feature or bug fix, reviewing cleanup, or reducing structural friction without intending to change observable behavior.
+
+## Primary bias to correct
+
+Refactoring is behavior-preserving design work in small steps. Do not turn cleanup into a rewrite, a hidden feature change, or speculative architecture.
+
+## Decision rules
+
+- Preserve observable behavior during refactoring. Isolate behavior changes from structural changes and never disguise a feature, migration, or redesign as cleanup.
+- Work in small, reversible, buildable, testable, reviewable steps. Split a patch when it is too large to reason about locally.
+- Establish or identify a safety net before risky refactoring. Use characterization tests for unclear behavior, keep test updates aligned with intended behavior, and never delete a failing test to finish cleanup.
+- Use preparatory and follow-up refactoring around feature work: identify what makes the requested change awkward, reshape that local structure first when useful, make the behavior change, then clean debt introduced by the change.
+- Refactor the current blocking smell, not every smell in sight: duplication, long functions, long parameter lists, globals, divergent change, shotgun surgery, feature envy, primitive obsession, repeated conditionals, temporary fields, middle men, or speculative generality.
+- Prefer the simplest named move that helps: rename, extract, inline, move, split meanings, introduce a parameter or value object, encapsulate a field or collection, decompose conditionals, use guard clauses, or substitute a clearer algorithm.
+- Make names and functions reveal intent. Rename before deeper work when bad names block understanding; keep functions coherent, at one abstraction level, with tight variable scope and separated phases.
+- Put behavior and state with the concept that owns them. Split classes or modules with multiple reasons to change; separate business policy from formatting, transport, persistence, I/O, frameworks, and integration details.
+- Keep data, mutation, and call contracts explicit. Avoid behavior-switching boolean flags, confusing argument order, parameter reassignment, exposed mutable collections, unnecessary setters, public fields, and duplicated state-transition logic.
+- Simplify conditionals honestly. Use guard clauses, extracted predicates, lookup tables, consolidated duplicate fragments, state, strategy, polymorphism, or null objects only when they reduce repeated branching or clarify variation.
+- Use abstraction and generalization only when current evidence justifies them. Remove pass-through layers, vague utilities, middle men, unused hierarchy, and just-in-case interfaces that do not improve changeability.
+- Preserve error semantics unless intentionally changing behavior. Refactor error handling to reveal the main path and consolidate duplicate validation, cleanup, recovery, or error structures.
+- Keep patch intent reviewable. Group related refactorings, separate structural edits from behavior where practical, and avoid giant patches that rename, move, redesign, and change logic together.
+- Stop when the requested change is easy, the blocking smell is gone, readability and local changeability are clearly better, and the next cleanup would be speculative.
+
+## Trigger rules
+
+- When adding behavior, first ask what structural friction blocks the change; refactor before the feature only when it makes the feature safer or simpler.
+- When fixing a bug in unclear code, characterize the current failure and refactor only enough to make the fix visible before changing behavior.
+- When tests are absent or weak, make the smallest possible structural move and improve testability before attempting broader cleanup.
+- When the same edit appears for a third time, remove duplication through clearer ownership instead of copying again.
+- When a function mixes responsibilities, abstraction levels, phases, or hidden side effects, rename, extract, split phases, or isolate side effects before adding more logic.
+- When one change forces edits across many files, centralize the knowledge or introduce a clearer boundary.
+- When repeated conditionals or type codes grow, decompose intent first; introduce polymorphism, state, strategy, or a table only when the variation is real.
+- When UI and domain behavior mix, move rules toward domain objects and verify any required presentation synchronization.
+- When a patch mixes intents or code motion makes review hard, split the change unless context makes that impractical.
+- When tempted to rewrite, choose the next small behavior-preserving transformation that recovers control.
+
+## Final checklist
+
+- Observable behavior preserved?
+- Structural change, behavior change, and test updates separated where practical?
+- Safety net, characterization, or verification gap recorded?
+- At least one real source of friction removed?
+- Names, responsibilities, control flow, data ownership, and interfaces clearer?
+- Patch still reviewable and runnable?
+- Cleanup stopped before speculative abstraction or rewrite pressure took over?