vanara 0.1.0 → 0.2.0

package/catalog/skills/readme-writing/scripts/lint-readme.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// Runnable check: lints a README for the required sections and a runnable
+// quickstart code block. Demonstrates an *executed*, verifiable example asset.
+// Zero dependencies — Node built-ins only.
+//
+// Usage:
+//   node lint-readme.mjs README.md            # lint a file
+//   node lint-readme.mjs --selftest           # run built-in test cases (exit 0/1)
+//   echo '<markdown>' | node lint-readme.mjs  # lint from stdin
+//
+// A README passes when it has a title (# H1), a one-line description, every
+// required section heading, and at least one fenced code block (the quickstart).
+
+import { readFileSync } from 'node:fs';
+
+// Each rule: [label, predicate(markdown) -> boolean]. Heading matches are
+// case-insensitive and accept common synonyms.
+const REQUIRED_SECTIONS = [
+  ['Install', /^#{1,6}\s+(install|installation|setup|getting started)\b/im],
+  ['Usage', /^#{1,6}\s+(usage|quick ?start|getting started|examples?)\b/im],
+  ['License', /^#{1,6}\s+licen[sc]e\b/im],
+];
+
+const RULES = [
+  ['has a top-level title (# H1)', (md) => /^#\s+\S+/m.test(md)],
+  ['has a one-line description under the title', (md) => hasDescription(md)],
+  ['has at least one fenced code block (quickstart)', (md) => /```[\s\S]*?```/.test(md)],
+  ...REQUIRED_SECTIONS.map(([name, re]) => [`has a "${name}" section`, (md) => re.test(md)]),
+];
+
+// A description is a non-empty, non-heading, non-badge line appearing after the
+// H1 title within the first several lines.
+function hasDescription(md) {
+  const lines = md.split(/\r?\n/);
+  const titleIdx = lines.findIndex((l) => /^#\s+\S+/.test(l));
+  if (titleIdx === -1) return false;
+  for (let i = titleIdx + 1; i < Math.min(lines.length, titleIdx + 8); i++) {
+    const line = lines[i].trim();
+    if (!line) continue;
+    if (line.startsWith('#')) return false;          // hit next heading first
+    if (line.startsWith('<!--')) continue;           // skip comments
+    if (/^[[!]/.test(line) && /\]\(/.test(line)) continue; // skip badge/link-only lines
+    return true;                                     // found prose
+  }
+  return false;
+}
+
+export function lintReadme(md) {
+  const failures = RULES.filter(([, fn]) => !safe(fn, md)).map(([msg]) => msg);
+  return { ok: failures.length === 0, failures };
+}
+
+function safe(fn, md) { try { return fn(md); } catch { return false; } }
+
+function lint(label, md) {
+  const { ok, failures } = lintReadme(md);
+  if (ok) console.log(`✓ ${label}: README has all required sections`);
+  else { console.error(`✗ ${label}:`); failures.forEach((f) => console.error(`    - ${f}`)); }
+  return ok;
+}
+
+const COMPLETE = `# Acme
+
+A fast CLI for doing the thing.
+
+## Install
+\`\`\`bash
+npm install acme
+\`\`\`
+
+## Usage
+\`\`\`bash
+acme run
+\`\`\`
+
+## License
+MIT
+`;
+
+const INCOMPLETE = `# Acme
+
+Some text but no fenced code block and no license section.
+
+## Install
+Run npm install acme.
+`;
+
+function selftest() {
+  const cases = {
+    valid_complete: COMPLETE,
+    invalid_incomplete: INCOMPLETE,
+  };
+  let allExpected = true;
+  for (const [name, md] of Object.entries(cases)) {
+    const { ok } = lintReadme(md);
+    const shouldPass = name.startsWith('valid');
+    const correct = ok === shouldPass;
+    allExpected &&= correct;
+    console.log(
+      `${correct ? '✓' : '✗'} selftest ${name}: ${ok ? 'pass' : 'fail'} (expected ${shouldPass ? 'pass' : 'fail'})`
+    );
+  }
+  process.exit(allExpected ? 0 : 1);
+}
+
+const arg = process.argv[2];
+if (arg === '--selftest') selftest();
+else if (arg) {
+  let md;
+  try { md = readFileSync(arg, 'utf8'); }
+  catch { console.error(`✗ cannot read file: ${arg}`); process.exit(1); }
+  process.exit(lint(arg, md) ? 0 : 1);
+} else {
+  let buf = '';
+  process.stdin.on('data', (c) => (buf += c));
+  process.stdin.on('end', () => process.exit(lint('stdin', buf) ? 0 : 1));
+}

package/catalog/skills/refactoring-patterns/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: refactoring-patterns
+description: Improve code structure without changing behavior — the discipline of small, named, test-backed moves. Extract function/variable, inline, rename, replace conditional with polymorphism, introduce parameter object, guard clauses. Recognize smells, refactor safely, avoid big-bang rewrites.
+type: skill
+version: 2.0.0
+updated: 2026-06-29
+---
+# Refactoring Patterns
+
+Refactoring is **changing the internal structure of code without changing its observable behavior**. It
+is not "cleanup whenever," and it is not rewriting. It is a disciplined sequence of small, *named*,
+behavior-preserving moves, each verified by tests, each committable on its own. Done right it is nearly
+risk-free; done wrong — without tests, mixed with feature work, or as a big-bang rewrite — it is one of
+the most reliable ways to ship a regression.
+
+This skill is the deep reference for that discipline: the safety net that makes it possible, the named
+moves themselves, the smells that signal where to apply them, and the trade-offs of when *not* to. Heavy
+detail lives in `references/`; copy-paste before/after material in `examples/`; a runnable smell detector
+in `scripts/`.
+
+## The mental model
+
+Two hats, never worn at once (Kent Beck's rule): you are either **adding behavior** (new tests go red,
+then green) *or* **refactoring** (all tests stay green the whole time). Switching hats mid-edit is the
+root cause of most refactoring disasters, because when a test breaks you can no longer tell whether your
+*restructuring* was wrong or your *new feature* was wrong.
+
+| Question | Refactoring answer |
+|---|---|
+| What changes? | structure only — names, shape, location |
+| What stays identical? | observable behavior, the public contract, test results |
+| How do I stay safe? | tests green before, green after, green between every step |
+| How big is a step? | small enough that a broken test points at one change |
+| When do I commit? | after each move that leaves the suite green |
+
+## 1. Tests are the safety net (non-negotiable)
+
+You cannot refactor code you cannot verify. Before touching structure, ensure a **green** test suite
+exercises the behavior you're about to move. If coverage is missing, write **characterization tests**
+first — tests that pin down what the code *currently* does (even if that's arguably wrong), so any
+behavior drift during refactoring surfaces immediately. See `references/safe-workflow.md` for the
+red-green-refactor loop, characterization testing, and the strangler-fig pattern for large systems.
+
+The loop:
+
+1. Run the suite — confirm green.
+2. Apply **one** named refactoring.
+3. Run the suite — confirm still green.
+4. Commit.
+5. Repeat.
+
+If step 3 goes red, you have exactly one small change to undo. That is the entire value proposition.
+
+## 2. Smells: knowing *where* to refactor
+
+Refactoring is demand-driven — you don't refactor everything, you refactor what a **code smell** is
+pointing at. The catalogue in `references/code-smells.md` is the full list; the high-frequency ones:
+
+- **Long method / long function** — does too much; the body has comment-delimited "paragraphs."
+- **Large class / god object** — too many fields and responsibilities; low cohesion.
+- **Feature envy** — a method that reaches into another object's data more than its own.
+- **Primitive obsession** — strings/ints standing in for real concepts (`string currency`, `int cents`).
+- **Shotgun surgery** — one conceptual change forces edits in many scattered places.
+- **Duplicated code** — the same logic in three spots (the rule of three: extract on the third copy).
+
+## 3. The named moves
+
+Each refactoring has a **name** and a **mechanics** (a precise step sequence). Naming them lets a team
+say "extract a function here" and share an exact, low-risk procedure. The full catalogue with mechanics
+is in `references/refactoring-catalog.md`. The core set:
+
+- **Extract Function** — pull a coherent block into its own named function.
+- **Inline Function/Variable** — the inverse, when the indirection earns nothing.
+- **Rename** — the highest-value, lowest-risk move; a precise name deletes a comment.
+- **Extract Variable** — name a sub-expression to explain it.
+- **Replace Conditional with Polymorphism** — swap a type-switch for dispatch on a type.
+- **Introduce Parameter Object** — bundle a clump of args that always travel together.
+- **Replace Magic Literal with Constant**, **Decompose Conditional**, **Replace Nested Conditional with
+  Guard Clauses**, **Move Function/Field**, **Separate Query from Modifier**.
+
+### Before / after: Extract Function + guard clauses
+
+A long function doing validation, calculation, and formatting at once:
+
+```js
+// before — one function, three jobs, deep nesting
+function invoiceLine(item) {
+  if (item) {
+    if (item.qty > 0) {
+      let total = item.qty * item.price;
+      if (item.taxable) { total = total * 1.2; }
+      return `${item.name}: $${total.toFixed(2)}`;
+    }
+  }
+  return "invalid";
+}
+```
+
+```js
+// after — guard clauses flatten nesting; intent-named helpers
+function invoiceLine(item) {
+  if (!isValid(item)) return "invalid";
+  return format(item.name, totalFor(item));
+}
+
+const isValid   = (i) => i && i.qty > 0;
+const totalFor  = (i) => i.taxable ? i.qty * i.price * 1.2 : i.qty * i.price;
+const format    = (name, total) => `${name}: $${total.toFixed(2)}`;
+```
+
+Same inputs, same outputs — tests stay green — but each piece now has one job and a name.
+
+### Before / after: Replace Conditional with Polymorphism
+
+```ts
+// before — the switch will grow with every new type; shotgun surgery waiting to happen
+function area(shape: Shape): number {
+  switch (shape.kind) {
+    case "circle": return Math.PI * shape.r ** 2;
+    case "square": return shape.side ** 2;
+    default: throw new Error("unknown shape");
+  }
+}
+```
+
+```ts
+// after — each type owns its behavior; adding a shape is additive, not invasive
+interface Shape { area(): number; }
+class Circle implements Shape { constructor(private r: number) {} area() { return Math.PI * this.r ** 2; } }
+class Square implements Shape { constructor(private side: number) {} area() { return this.side ** 2; } }
+// new shapes add a class; no existing code is touched (Open/Closed)
+```
+
+See `examples/` for both of these as standalone, runnable files.
+
+## 4. Common pitfalls (failure modes)
+
+- **Refactoring without tests.** The cardinal sin. With no safety net you are *rewriting and hoping*.
+  Write characterization tests first or do not start.
+- **Wearing both hats.** Mixing a refactor with a behavior change in the same commit. When something
+  breaks you can't bisect *which* intent caused it, and reviewers can't see the real change in the diff.
+  Keep refactor commits and feature commits separate.
+- **Big-bang rewrites.** "Let's just rewrite it cleanly" discards hard-won, battle-tested edge-case
+  knowledge and ships with no incremental safety. Prefer the **strangler fig**: grow the new structure
+  around the old, route traffic over piece by piece, delete the old when nothing calls it.
+- **Steps too big.** If a "step" touches 30 files before you re-run tests, a red bar tells you nothing
+  useful. Shrink the step.
+- **Refactoring on a feature branch for weeks.** Long-lived refactor branches rot against `main` and
+  produce merge nightmares. Land small refactors continuously.
+- **Speculative generality** — extracting abstractions "for the future" no caller needs yet. Refactor
+  toward concrete, present demands (YAGNI).
+
+## 5. When NOT to refactor / trade-offs
+
+- **No tests and no time to write them** for code you don't understand — refactoring here is gambling.
+  Add characterization tests first, or leave it alone.
+- **Code you're about to delete** — don't polish a corpse.
+- **Stable code nobody touches and nobody complains about** — clean for clean's sake has no payoff;
+  refactor when you're *already* in the area for a feature or fix (the "campsite rule").
+- **A hard deadline shipping today** — note the debt, ship, refactor next iteration. Be honest that this
+  is borrowing, not free.
+- **Refactor vs. rewrite:** rewrite only when the design is fundamentally wrong for current
+  requirements *and* you can carve off a strangler-fig seam. Otherwise incremental refactoring is almost
+  always cheaper and safer than a rewrite.
+
+## Files in this package
+
+- `references/code-smells.md` — the smell catalogue (long method, large class, feature envy, primitive
+  obsession, shotgun surgery, and more) with the move each one calls for.
+- `references/refactoring-catalog.md` — named refactorings with their step-by-step mechanics.
+- `references/safe-workflow.md` — red-green-refactor, characterization tests, strangler fig, the two hats.
+- `examples/extract-function.before-after.js` — long function → extracted, named helpers.
+- `examples/replace-conditional-with-polymorphism.before-after.ts` — type-switch → dispatch.
+- `scripts/detect-smells.mjs` — runnable Node scanner that flags long functions and deep nesting
+  (`--selftest` for built-in cases).
+
+Pairs with the `error-handling-patterns` skill (refactor toward explicit error handling), the
+`testing-patterns` skill (the safety net), and the `code-reviewer` and `refactor-cleaner` agents.

package/catalog/skills/refactoring-patterns/examples/extract-function.before-after.js

@@ -0,0 +1,57 @@
+// Extract Function (+ guard clauses + extract variable)
+// ------------------------------------------------------
+// A single long function doing validation, calculation, tax, and formatting,
+// refactored into small named pieces. Behavior is identical — the demo at the
+// bottom proves before === after for the same inputs.
+//
+// Run: node extract-function.before-after.js
+
+// ---- BEFORE: one function, several jobs, nested conditionals -------------------
+function invoiceLineBefore(item) {
+  if (item) {
+    if (item.qty > 0) {
+      let total = item.qty * item.price;
+      if (item.taxable) {
+        total = total * 1.2; // what's 1.2? magic number
+      }
+      return item.name + ": $" + total.toFixed(2);
+    }
+  }
+  return "invalid";
+}
+
+// ---- AFTER: guard clause + extracted, intent-named helpers ---------------------
+const TAX_RATE = 0.2; // Replace Magic Literal with Symbolic Constant
+
+const isValidItem = (item) => Boolean(item) && item.qty > 0; // Decompose Conditional
+
+function lineTotal(item) {
+  const subtotal = item.qty * item.price;          // Extract Variable
+  return item.taxable ? subtotal * (1 + TAX_RATE) : subtotal;
+}
+
+const formatLine = (name, total) => `${name}: $${total.toFixed(2)}`;
+
+function invoiceLineAfter(item) {
+  if (!isValidItem(item)) return "invalid";        // guard clause flattens nesting
+  return formatLine(item.name, lineTotal(item));
+}
+
+// ---- Proof the refactoring preserved behavior ---------------------------------
+const cases = [
+  { name: "Widget", qty: 3, price: 10, taxable: true },
+  { name: "Gadget", qty: 2, price: 5, taxable: false },
+  null,
+  { name: "Empty", qty: 0, price: 99, taxable: true },
+];
+
+let allMatch = true;
+for (const c of cases) {
+  const before = invoiceLineBefore(c);
+  const after = invoiceLineAfter(c);
+  const ok = before === after;
+  allMatch = allMatch && ok;
+  console.log(`${ok ? "✓" : "✗"} ${JSON.stringify(c)} -> before:"${before}" after:"${after}"`);
+}
+console.log(allMatch ? "\nAll outputs identical — behavior preserved." : "\nMISMATCH — refactor changed behavior!");
+process.exit(allMatch ? 0 : 1);

package/catalog/skills/refactoring-patterns/examples/replace-conditional-with-polymorphism.before-after.ts

@@ -0,0 +1,63 @@
+// Replace Conditional with Polymorphism
+// -------------------------------------
+// BEFORE: a type-code switch repeated across multiple functions. Every new shape
+// forces edits to area() AND name() AND any future per-type function — the
+// "repeated switch" / shotgun-surgery smell.
+//
+// AFTER: each type owns its behavior behind a common interface. Adding a shape is
+// purely additive (Open/Closed); no existing function is touched.
+//
+// This is illustrative TypeScript. Compile with `tsc` or read as reference.
+
+// ===== BEFORE =================================================================
+type ShapeData =
+  | { kind: "circle"; r: number }
+  | { kind: "square"; side: number }
+  | { kind: "rect"; w: number; h: number };
+
+function areaBefore(s: ShapeData): number {
+  switch (s.kind) {
+    case "circle": return Math.PI * s.r ** 2;
+    case "square": return s.side ** 2;
+    case "rect": return s.w * s.h;
+    default: throw new Error("unknown shape");
+  }
+}
+
+function nameBefore(s: ShapeData): string {
+  switch (s.kind) {           // the SAME switch, duplicated — change one, hunt the rest
+    case "circle": return "Circle";
+    case "square": return "Square";
+    case "rect": return "Rectangle";
+    default: throw new Error("unknown shape");
+  }
+}
+
+// ===== AFTER ==================================================================
+interface Shape {
+  area(): number;
+  name(): string;
+}
+
+class Circle implements Shape {
+  constructor(private readonly r: number) {}
+  area(): number { return Math.PI * this.r ** 2; }
+  name(): string { return "Circle"; }
+}
+
+class Square implements Shape {
+  constructor(private readonly side: number) {}
+  area(): number { return this.side ** 2; }
+  name(): string { return "Square"; }
+}
+
+class Rectangle implements Shape {
+  constructor(private readonly w: number, private readonly h: number) {}
+  area(): number { return this.w * this.h; }
+  name(): string { return "Rectangle"; }
+}
+
+// Adding a Triangle = add one class. areaBefore/nameBefore would each need a new
+// case; here, no existing class changes. That is the payoff.
+
+export { areaBefore, nameBefore, Shape, Circle, Square, Rectangle };

package/catalog/skills/refactoring-patterns/references/code-smells.md

@@ -0,0 +1,92 @@
+# Code Smells — and the move each one calls for
+
+A *smell* is a surface symptom that usually (not always) points at a deeper structural problem. Smells
+tell you **where** to refactor; the named refactoring tells you **how**. Use judgment — a smell is a
+prompt to look, not an automatic mandate to change.
+
+## Bloaters
+
+### Long method / long function
+**Symptom:** the body has comment-delimited "paragraphs," scrolls off-screen, mixes levels of
+abstraction (high-level orchestration next to bit-twiddling).
+**Move:** *Extract Function* on each paragraph; *Replace Temp with Query*; *Decompose Conditional*.
+**Heuristic:** if you feel the urge to write a comment explaining a block, extract that block and let the
+function name be the comment.
+
+### Large class / god object
+**Symptom:** dozens of fields, many unrelated responsibilities, low cohesion (fields used by disjoint
+subsets of methods).
+**Move:** *Extract Class* / *Extract Subclass*; group fields that change together into their own type.
+
+### Primitive obsession
+**Symptom:** `string currency`, `int cents`, `string` for a phone number — primitives standing in for
+domain concepts, with validation/formatting scattered around every use site.
+**Move:** *Replace Primitive with Object* (a `Money`, `PhoneNumber`, `EmailAddress` value type that owns
+its validation and behavior). Kills duplicated validation and impossible states.
+
+### Long parameter list
+**Symptom:** five-plus parameters, or the same clump of args passed together everywhere.
+**Move:** *Introduce Parameter Object* / *Preserve Whole Object*.
+
+### Data clumps
+**Symptom:** the same three or four data items travel together through many signatures
+(`x, y, width, height`).
+**Move:** *Introduce Parameter Object* — they want to be a `Rect`.
+
+## Change-preventers (these make change expensive)
+
+### Shotgun surgery
+**Symptom:** one conceptual change (e.g. "add a new tax rule") forces small edits in many scattered
+files/classes.
+**Move:** *Move Function/Field* to pull the scattered logic into one place; *Inline Class* if a class
+adds no value.
+
+### Divergent change
+**Symptom:** the opposite — one class is changed for many *different* reasons (a new report format *and*
+a new DB column both touch it).
+**Move:** *Extract Class* so each axis of change lives in its own type.
+
+## Couplers
+
+### Feature envy
+**Symptom:** a method spends more time reading another object's fields than its own.
+**Move:** *Move Function* to the class whose data it envies; *Extract Function* then move the part that
+envies.
+
+### Inappropriate intimacy
+**Symptom:** two classes reach deep into each other's private parts.
+**Move:** *Move Function/Field*, *Hide Delegate*, or merge if they're really one concept.
+
+### Message chains
+**Symptom:** `a.getB().getC().getD().doThing()` — the caller is coupled to the whole navigation path.
+**Move:** *Hide Delegate* (ask the first object to do the work).
+
+## Dispensables
+
+### Duplicated code
+**Symptom:** the same (or near-same) logic in multiple places.
+**Move:** *Extract Function* and call it from both. **Rule of three:** duplication is acceptable twice;
+on the third occurrence, extract. Extracting too early (on the second) risks a wrong abstraction that
+couples things that only *coincidentally* looked alike.
+
+### Comments (as deodorant)
+**Symptom:** a comment exists to explain *what* confusing code does.
+**Move:** *Extract Function* / *Rename* so the code self-documents; keep comments for *why*, not *what*.
+
+### Dead code / speculative generality
+**Symptom:** unused params, unreachable branches, abstractions with a single implementation "for the
+future."
+**Move:** delete it (YAGNI). Pairs with the `refactor-cleaner` agent.
+
+## Conditionals
+
+### Complex / nested conditional
+**Symptom:** deep `if/else` pyramids; a `switch` on a type code that recurs in several places.
+**Move:** *Replace Nested Conditional with Guard Clauses*; *Decompose Conditional* (extract the
+condition and each leg into named functions); *Replace Conditional with Polymorphism* when the switch is
+on a type.
+
+### Repeated switch on a type
+**Symptom:** the same `switch (kind)` appears in `area()`, `perimeter()`, `draw()`…
+**Move:** *Replace Conditional with Polymorphism* — each type owns all its behaviors; new types become
+additive (Open/Closed).

package/catalog/skills/refactoring-patterns/references/refactoring-catalog.md

@@ -0,0 +1,78 @@
+# Refactoring Catalog — named moves with mechanics
+
+Each refactoring is a *named* procedure with explicit **mechanics** — a small step sequence designed so
+the suite stays green throughout. Run tests after every numbered step where noted. Most modern IDEs
+automate the safe versions (Rename, Extract Function/Variable, Inline, Move); prefer the automated
+version when available because it preserves references mechanically.
+
+## Extract Function
+**When:** a fragment of a function can be grouped and named for its intent (long method, duplication,
+comment-as-deodorant).
+**Mechanics:**
+1. Create a new function named for *what it does*, not how.
+2. Copy the extracted code into it.
+3. Pass in any local variables it reads as parameters; return any it writes.
+4. Replace the original fragment with a call.
+5. Run tests.
+
+## Inline Function / Inline Variable
+**When:** the body is as clear as the name, or a layer of indirection earns nothing.
+**Mechanics:** verify it isn't polymorphically overridden; replace each call with the body; remove the
+declaration; run tests. (The inverse of Extract — use it to undo a premature extraction.)
+
+## Rename (Variable / Function / Field)
+**When:** a name no longer reveals intent. The highest value-to-risk move there is.
+**Mechanics:** prefer the IDE's rename (updates all references atomically). If manual, change the
+declaration, find every reference, update, run tests. Renaming a published API element requires a
+deprecation step — keep the old name delegating for one release.
+
+## Extract Variable
+**When:** a sub-expression is hard to read or repeated within an expression.
+**Mechanics:** introduce a well-named `const` for the sub-expression; replace occurrences; run tests.
+Makes complex booleans and arithmetic self-explaining.
+
+## Replace Nested Conditional with Guard Clauses
+**When:** deep `if` nesting where some branches are exceptional/early-exit cases.
+**Mechanics:** for each "this isn't the normal path" check, return (or throw) early at the top; the happy
+path then drops out of the nesting. Run tests after each guard.
+
+## Decompose Conditional
+**When:** a complex `if (cond) { ... } else { ... }` where the condition and legs are all hard to read.
+**Mechanics:** *Extract Function* on the condition (name it `isEligible(...)`), and on each leg. The
+conditional becomes `if (isEligible(x)) return discounted(x); return standard(x);`.
+
+## Replace Conditional with Polymorphism
+**When:** the same `switch`/`if`-on-type appears in multiple methods (repeated switch smell).
+**Mechanics:**
+1. Ensure an inheritance/interface structure exists (create it via *Extract Class* / *Replace Type Code
+   with Subclasses* if needed).
+2. Move one `switch` into the superclass/interface as a method.
+3. For each leg, override the method in the matching subclass with that leg's body.
+4. Remove the leg from the superclass; leave the default/abstract.
+5. Run tests after each leg moved. Repeat per method that switched on the same type.
+
+## Introduce Parameter Object
+**When:** a clump of arguments (data clump) recurs across signatures.
+**Mechanics:** create a class/record for the clump; add it as a parameter; one call site at a time, route
+the individual args through the object; remove the originals once all sites are migrated; run tests
+between sites.
+
+## Replace Magic Literal with Symbolic Constant
+**When:** an unexplained literal (`0.2`, `86400`, `"ACTIVE"`) carries meaning.
+**Mechanics:** declare a named constant; replace each occurrence; run tests. Search for the literal value
+elsewhere — duplicated magic numbers often hide.
+
+## Move Function / Move Field
+**When:** feature envy or shotgun surgery — the element lives in the wrong class.
+**Mechanics:** check what it references; create it in the target; adjust references; turn the original
+into a delegating call (or remove if no longer needed); update callers; run tests.
+
+## Separate Query from Modifier
+**When:** a function both returns a value *and* has a side effect (surprising to callers).
+**Mechanics:** create a pure query that returns the value; leave the modifier returning void; update
+callers to call both where they truly need the side effect; run tests.
+
+## Mechanics discipline
+The point of writing mechanics down is that under pressure you follow the *steps*, not your intuition.
+Small steps + green tests after each = you can always revert exactly one move. If a step list feels too
+small, that's the point — speed comes from never having to debug.

package/catalog/skills/refactoring-patterns/references/safe-workflow.md

@@ -0,0 +1,74 @@
+# Safe Refactoring Workflow
+
+Refactoring is only "safe" because of the process around it. The moves themselves are mechanical; the
+discipline is what prevents regressions.
+
+## The two hats (Kent Beck)
+
+At any moment you are wearing exactly one hat:
+
+- **Adding behavior** — you write a new failing test, then make it pass. The structure may get a little
+  worse; that's fine.
+- **Refactoring** — you change structure while **all tests stay green**. You add no tests (except as a
+  safety net before starting) and you change no behavior.
+
+Never wear both at once. The instant a test breaks, the hat you're wearing tells you what kind of mistake
+you made. Mixing them destroys that signal and pollutes the diff so reviewers can't see the real change.
+
+## Red-Green-Refactor
+
+The TDD loop bakes refactoring in as a first-class step:
+
+1. **Red** — write a test for the next behavior; it fails.
+2. **Green** — write the *simplest* code that passes, even if ugly.
+3. **Refactor** — now, with a green bar, clean up the code you just wrote *and* the surrounding code your
+   change touched. Tests stay green.
+
+The refactor step is where design actually happens. Skipping it is how "temporary" green code calcifies
+into permanent debt.
+
+## Characterization tests (the legacy-code entry point)
+
+When you must refactor code that has **no tests** and you're unsure what it does:
+
+1. Write a test that calls the code and asserts *whatever it currently returns* — even if that output
+   looks wrong. You're not asserting correctness; you're **pinning current behavior**.
+2. A fast way to discover the expected value: assert something obviously false, run it, and copy the
+   actual value from the failure message into the assertion.
+3. Build up enough of these to cover the branches you're about to touch.
+4. Now refactor. Any behavior drift breaks a characterization test immediately.
+
+Characterization tests document the *as-is* contract. If you later decide some pinned behavior was a bug,
+that's a **separate, behavior-changing** task (other hat) with its own test update and commit.
+
+## Strangler fig (refactoring at system scale)
+
+Big-bang rewrites fail because they discard embedded edge-case knowledge and offer no incremental safety.
+The strangler fig grows the new structure *around* the old, like the vine that envelops a tree:
+
+1. Put a **seam** (interface/facade/router) in front of the thing you want to replace.
+2. Build the new implementation behind the seam for **one** slice of functionality.
+3. Route that slice's traffic to the new code; keep everything else on the old.
+4. Verify in production (metrics, parity checks); migrate the next slice.
+5. When nothing routes to the old code, delete it.
+
+At every step the system is fully working and releasable. You can stop, pause, or roll back a single
+slice — none of which a rewrite allows.
+
+## Commit hygiene
+
+- **One refactoring move per commit** where practical; at minimum, never mix a refactor with a feature in
+  one commit. A reviewer should be able to read a commit message of `refactor: extract totalFor()` and
+  trust the behavior is unchanged.
+- Land refactors **continuously** onto `main`. Long-lived refactor branches rot against everyone else's
+  work and create merge hell.
+- Keep the suite **fast**. If running tests after every step is painful, you'll stop doing it — and the
+  whole safety net collapses. Invest in test speed first.
+
+## Pre-flight checklist
+
+- [ ] Green test suite covering the behavior I'm about to move (or characterization tests written).
+- [ ] I know which hat I'm wearing right now.
+- [ ] My next step is small enough that a red bar points at one change.
+- [ ] I will run the suite after this step.
+- [ ] My commit contains only refactoring, no behavior change.