ralphctl 0.26.0 → 0.28.0

package/dist/skills/ralphctl-code-review-and-quality/SKILL.md

@@ -7,7 +7,9 @@ license: MIT
 # Code Review and Quality
 
 > Concept from [addyosmani/agent-skills — "Code Review and Quality"](https://github.com/addyosmani/agent-skills),
-> MIT License. Adapted for ralphctl's evaluator role and review flow.
+> MIT License. Adapted for ralphctl's evaluator role and review flow. The smell baseline draws on
+> [mattpocock/skills](https://github.com/mattpocock/skills) and the concrete-case and expected-load rules on
+> [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) (both MIT).
 
 One-shot generation looks fast and is slow. Catching a correctness, architecture, or security problem at the
 seam between two changes is cheap; catching it at the end of a 200-line diff — or after the post-task gate
@@ -57,6 +59,10 @@ Can another engineer understand this code without the author explaining it?
 - Could this be done in fewer lines? (1 000 lines where 100 suffice is a failure.)
 - Are abstractions earning their complexity? Do not generalise until the third use case.
 - Are there dead code artefacts: no-op variables, backwards-compat shims, or `// removed` comments?
+- **Is a new conditional bolted onto an unrelated flow?** That is a design smell, not a nit — push the logic
+  into its own helper, state, or policy instead of tangling an existing path.
+- **Do repeated conditionals on the same shape appear?** They signal a missing model or dispatcher. A
+  "temporary" branch is usually permanent debt.
 
 ### 3. Architecture
 
@@ -67,6 +73,16 @@ Does the change fit the system's design?
 - Is there code duplication that should be shared?
 - Are dependencies flowing in the right direction — no circular dependencies?
 - Is the abstraction level appropriate — not over-engineered, not too coupled?
+- **Does this refactor reduce complexity or just relocate it?** Count the concepts a reader must hold to
+  follow the change. If a "cleaner" version leaves that count unchanged, it is not cleaner — prefer the
+  restructuring that makes whole branches, modes, or layers disappear over one that re-centralises the same
+  logic. Prefer deleting an abstraction to polishing it.
+- **Is feature-specific logic leaking into a shared or general-purpose module?** Keep logic in its owning
+  layer, reuse the existing canonical helper instead of a near-duplicate, and do not normalise architectural
+  drift.
+- **Are type boundaries explicit?** Question gratuitous untyped escape hatches, optional fields, casts, and
+  silent fallbacks that paper over an unclear invariant — making the boundary explicit often makes the
+  surrounding control flow simpler.
 
 ### 4. Security
 
@@ -91,6 +107,47 @@ Does the change introduce performance problems?
 - Any missing pagination on list endpoints?
 - Any large objects created in hot paths?
 
+Judge scale against the expected load, found in the repository (README, deploy configuration): a script one
+person runs is not a service under concurrent traffic. Check-then-write races, work every process repeats,
+collections that only grow, and per-process state that must be shared are findings at the load that
+triggers them — say which load you assumed.
+
+## Structural Remedies
+
+When you flag a structural problem, propose the move — not just the problem. A finding that only says "this
+is complex" leaves the generator or author guessing. Reach for a named restructuring:
+
+- **Replace a chain of conditionals** with a typed model or an explicit dispatcher.
+- **Collapse duplicate branches** into a single clearer flow.
+- **Separate orchestration from business logic** so each reads on its own.
+- **Move feature-specific logic** out of a shared module into the module that owns the concept.
+- **Reuse the canonical helper** instead of a bespoke near-duplicate.
+- **Make a type boundary explicit** so downstream branching disappears.
+- **Delete a pass-through wrapper** that adds indirection without clarifying the API.
+- **Extract a helper, or split a large file** into focused modules.
+
+Prefer the remedy that removes moving pieces over one that spreads the same complexity around.
+
+## Smell Baseline
+
+On top of whatever the project documents, a fixed set of code smells (Fowler, _Refactoring_) applies even
+where a repository documents nothing. Each is a labelled judgement call ("possible Feature Envy") at Minor or
+Nit, never a hard violation. A documented project standard that endorses the pattern overrides the smell, and
+anything tooling already enforces is skipped.
+
+- **Mysterious Name** — the name does not say what it does or holds → rename; no honest name means murky design.
+- **Duplicated Code** — the same logic shape in several hunks or files → extract it once.
+- **Feature Envy** — a function that works on another module's data more than its own → move it there.
+- **Data Clumps** — the same few values always travel together → give them one type.
+- **Primitive Obsession** — a string or number standing in for a domain concept → give the concept a type.
+- **Repeated Switches** — the same branching on the same type in several places → one dispatch both share.
+- **Shotgun Surgery** — one logical change forces scattered edits → gather what changes together.
+- **Divergent Change** — one module edited for several unrelated reasons → split by reason.
+- **Speculative Generality** — hooks, parameters, or abstractions for needs nobody has → delete them.
+- **Message Chains** — callers walking a long chain of navigation → hide the walk behind one call.
+- **Middle Man** — a layer that mostly delegates → call the real target directly.
+- **Refused Bequest** — an implementer ignoring most of what it inherits → compose instead of inheriting.
+
 ## Severity Vocabulary
 
 Label every finding with its severity so the generator or author knows what is required versus optional:
@@ -105,6 +162,12 @@ Label every finding with its severity so the generator or author knows what is r
 Using explicit severity prevents treating all findings as equally urgent — a nit should not consume the
 same budget as a Critical.
 
+**Presumptive structural findings.** Raise each of these as at least Minor and propose the simpler design;
+escalate to Major only when the change actively makes the structure worse: a refactor that relocates
+complexity instead of reducing it; a change that pushes a file past a healthy size with no decomposition;
+feature logic added to a shared module; a near-duplicate of an existing canonical helper; a silent fallback
+that hides an unclear invariant.
+
 ## Review Process
 
 ### Step 1: Understand the Context
@@ -124,6 +187,12 @@ Tests reveal intent and coverage:
 - Are edge cases covered?
 - Would the tests catch a regression if the code changed?
 
+Answer the last question by experiment, not by reading, when your session may edit the working tree (the
+generator): invert one condition the change adds (drop a negation, swap `&&` for `||`), run the focused
+test, then restore the file from a copy. A mutation that stays green is a finding — name the missing test
+case. When your session is read-only (the evaluator), reason through the same inversion and name the test
+case that would be missing as a finding.
+
 ### Step 3: Review the Implementation
 
 Walk through the code with the five axes in mind. For each file changed:
@@ -153,6 +222,11 @@ section names the exact file and shape):
   the severity of each finding) in the evaluator's output as directed by the task prompt — not in a
   separate file or report, and not as a `decision` signal.
 
+**Lead with what matters.** Order findings by leverage: correctness and security first, then structural
+regressions and missed simplifications, then everything else. Do not bury a real issue under cosmetic nits —
+a few high-conviction findings beat a long list. If you have one structural problem and ten nits, the
+structural problem _is_ the review.
+
 Do not write a standalone review report to a file. The harness's signal pipeline and the evaluator's
 structured output are the authoritative record.
 
@@ -178,6 +252,11 @@ Small, focused changes are easier to review, faster to evaluate, and safer to fo
 ~1000 lines changed  → Too large. Split it.
 ```
 
+**Watch file size, not just diff size.** A small diff can still push a file past a healthy boundary —
+around 1 000 _total_ lines in a single file (distinct from the ~1 000 _changed_-lines threshold above) is a
+common inspection signal, not a hard cap. When a change materially grows an already-large file, ask whether
+to extract helpers, subcomponents, or modules _first_, before piling more on. Decompose, then add.
+
 **What counts as "one change":** A single self-contained modification that addresses one thing, includes
 related tests, and keeps the system functional after submission.
 
@@ -208,11 +287,30 @@ Before adding any dependency:
 
 Prefer the standard library and existing utilities over new dependencies. Every dependency is a liability.
 
+**Upgrading an existing dependency** is a code change like any other, and the riskiest upgrades are bulk
+"bump deps" changes. Review them with the same discipline:
+
+- **Read the changelog, not just the version number.** Semver is a promise the maintainer may not have
+  kept — a "patch" can carry a behavioural change. For a major bump, read the migration notes and find what
+  breaks.
+- **One dependency per change** (or a small related group). When a bulk bump breaks the build, you lose which
+  package did it; a single-package change makes the cause obvious and the revert clean.
+- **Let the tests decide.** The upgrade is verified by a green check before _and_ after, not by "it
+  installed." If coverage around the dependency's behaviour is thin, that gap is the real finding — add a
+  test first.
+- **Mind the transitive graph.** Review the lockfile diff, not just the dependency manifest; a single direct
+  bump can pull in dozens of indirect changes.
+- **Keep the lockfile honest.** Keep it in the change, review its diff, and never hand-edit it — the lockfile
+  is what actually pins what ships.
+
 ## Honesty in Review
 
 Whether reviewing code you wrote, code a generator produced, or a human's change:
 
 - Do not rubber-stamp. "Looks fine" without evidence of review helps no one.
+- Back every correctness, security, or scale finding with a concrete case — this input or situation leads to
+  this wrong result — and re-read the lines to confirm it: the caller exists, the value can really be empty,
+  the code really is unused. No case, no finding. Structural findings follow the presumptive rules above.
 - Do not soften real issues. "This might be a minor concern" when it is a bug that will hit production is
   misleading.
 - Quantify problems when possible. "This N+1 query will add ~50 ms per item in the list" is better than
@@ -224,13 +322,17 @@ Whether reviewing code you wrote, code a generator produced, or a human's change
 
 ## Common Rationalisations
 
-| Rationalisation                       | Reality                                                                                                                    |
-| ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| "It works, that's good enough"        | Working code that is unreadable, insecure, or architecturally wrong creates debt that compounds.                           |
-| "I wrote it, so I know it is correct" | Authors are blind to their own assumptions.                                                                                |
-| "We will clean it up later"           | Later rarely comes. The review is the quality gate — use it.                                                               |
-| "AI-generated code is probably fine"  | AI code needs more scrutiny, not less. It is confident and plausible, even when wrong.                                     |
-| "The tests pass, so it is good"       | Tests are necessary but not sufficient. They do not catch architecture problems, security issues, or readability concerns. |
+| Rationalisation                            | Reality                                                                                                                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| "It works, that's good enough"             | Working code that is unreadable, insecure, or architecturally wrong creates debt that compounds.                                                                                |
+| "I wrote it, so I know it is correct"      | Authors are blind to their own assumptions.                                                                                                                                     |
+| "We will clean it up later"                | Later rarely comes. The review is the quality gate — use it.                                                                                                                    |
+| "AI-generated code is probably fine"       | AI code needs more scrutiny, not less. It is confident and plausible, even when wrong.                                                                                          |
+| "The tests pass, so it is good"            | Tests are necessary but not sufficient. They do not catch architecture problems, security issues, or readability concerns.                                                      |
+| "The refactor makes it cleaner"            | Relocating complexity is not reducing it. If the reader still holds the same number of concepts, the structure did not improve — look for the version where branches disappear. |
+| "It is only a small addition to this file" | Small diffs still push files past a healthy size and bolt branches onto unrelated flows. Judge the resulting structure, not the diff size.                                      |
+| "It is just a version bump"                | A bump is a behaviour change you did not write. Read the changelog; semver does not guarantee no breakage.                                                                      |
+| "Upgrade everything at once to save time"  | A bulk bump that breaks the build hides which package did it. One dependency per change keeps the cause and the revert clean.                                                   |
 
 ## Review Checklist
 
@@ -243,6 +345,9 @@ Before signalling completion or a passing evaluator verdict, run through:
 - [ ] Names are clear and consistent with project conventions.
 - [ ] No unnecessary complexity.
 - [ ] Follows existing architectural patterns.
+- [ ] Refactors reduce complexity rather than relocate it.
+- [ ] No feature logic in shared modules; touched files stay within a healthy size.
+- [ ] Dependency upgrades (if any) were checked against their changelog and the lockfile diff.
 - [ ] No secrets in code; input validated at boundaries.
 - [ ] No N+1 patterns or unbounded operations.
 - [ ] Findings surfaced per Step 4's signal guidance, with severity labels intact.
@@ -255,3 +360,9 @@ Before signalling completion or a passing evaluator verdict, run through:
 - No regression tests alongside a bug fix.
 - Review comments without severity labels — makes it unclear what is required versus optional.
 - Accepting "I will fix it later" — it rarely happens.
+- A refactor that moves code around without reducing the number of concepts a reader must hold.
+- A change that grows an already-large file instead of decomposing it.
+- New conditionals scattered into unrelated code paths (a missing abstraction).
+- A bespoke helper that duplicates an existing canonical one, or feature logic placed in a shared module.
+- A bulk dependency bump with no changelog review and no per-package isolation.
+- A lockfile change that is hand-edited or accepted without reviewing its diff.

package/dist/skills/ralphctl-code-simplification/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: ralphctl-code-simplification
+description: Behaviour-preserving simplification of existing code — understand why the code exists before changing it, then reduce nesting, unclear names, duplication, dead code, and needless indirection one step at a time with the existing tests unchanged and green after each. Use when a task asks to refactor or clean up working code, or when code you just made work is heavier than it needs to be; for keeping a new change small from the start, see ralphctl-surgical-simplicity and ralphctl-ponytail when installed.
+license: MIT
+---
+
+# Code Simplification
+
+> Adapted from [addyosmani/agent-skills — "Code Simplification"](https://github.com/addyosmani/agent-skills)
+> (MIT). Adapted for ralphctl's harness contract.
+
+Simplify by reducing complexity while preserving behaviour exactly. The goal is not fewer lines — it is
+code a new reader understands faster than the original. Every simplification passes one test: would
+someone new to this code follow the result more easily?
+
+## When this applies
+
+- **Execute** — when the task asks for a refactor or cleanup, and after a change works, on the code that
+  change touched. Simplification outside the task's scope is a finding to surface, not an edit to make —
+  record it in a `note` signal when the prompt's output-contract section lists it; otherwise fold it into
+  the required signal's own fields.
+
+**When not to use:** the code is already clear; you do not yet understand what it does; the simpler form
+is measurably slower on a hot path; the module is about to be replaced.
+
+## Principles
+
+1. **Preserve behaviour exactly.** Same outputs for every input, same errors, same side effects and their
+   order. The existing tests pass without modification. If you are not sure a change preserves
+   behaviour, do not make it.
+2. **Follow the project's conventions.** Read the project's context file when present and the
+   neighbouring code; simplification that breaks local consistency is churn.
+3. **Clarity over cleverness.** A chain of nested conditional expressions becomes early returns or a
+   lookup; a dense chained transform with inline logic becomes a named intermediate step.
+4. **Keep the balance.** Do not inline a helper that gives a concept its name, merge unrelated logic into
+   one function, or remove an abstraction that exists for testability. Line count is not the measure.
+5. **Scope to what changed.** Default to the code the task touched.
+
+## The process
+
+### 1. Understand before touching (Chesterton's fence)
+
+Before changing or removing anything, know why it exists: its responsibility, its callers and callees,
+its edge cases and error paths, the tests that pin its behaviour, and why it might have been written this
+way (a performance constraint, a platform quirk, history visible in `git log` or `git blame`). If you
+cannot answer these, read more first.
+
+### 2. Find concrete opportunities
+
+| Pattern                              | Simplification                                        |
+| ------------------------------------ | ----------------------------------------------------- |
+| Nesting three or more levels deep    | Guard clauses or an extracted, well-named condition   |
+| A long function doing several jobs   | Split by job, never by line count                     |
+| Boolean flag parameters              | Separate functions, or a named options value          |
+| The same condition in several places | One named predicate                                   |
+| Generic or misleading names          | Names that describe the content or the real behaviour |
+| A comment explaining _what_          | Delete it; keep comments that explain _why_           |
+| Duplicated logic                     | One shared function                                   |
+| Dead code                            | Remove it, after confirming nothing reaches it        |
+| A wrapper that only forwards         | Call the underlying function directly                 |
+| An abstraction with one variant      | The direct approach                                   |
+
+### 3. Apply one change at a time
+
+Make one simplification, run the focused tests, and continue only when they are green; when they fail,
+undo that step and reconsider. Never batch several simplifications into one untested change — when
+something breaks, you need to know which one did it. Keep refactoring and behaviour change apart: a
+refactor task adds no behaviour, and a feature task does not absorb a broad refactor. For a change
+touching many sites, prefer a mechanical transform (a structured search-and-replace or a codemod the
+project already uses) over hand edits.
+
+### 4. Judge the whole
+
+Compare before and after: is the result genuinely easier to follow, consistent with the codebase, and a
+clean reviewable diff? If not, undo it. Not every attempt succeeds.
+
+## Common rationalisations
+
+| Rationalisation                          | Reality                                                                           |
+| ---------------------------------------- | --------------------------------------------------------------------------------- |
+| "Fewer lines is always simpler"          | A one-line nested conditional is not simpler than five readable lines.            |
+| "I'll quickly tidy this unrelated code"  | Unscoped cleanup inflates the diff and risks regressions you did not intend.      |
+| "This abstraction might be useful later" | Speculative abstractions are complexity without value. Remove it; re-add on need. |
+| "The tests needed a small tweak"         | A simplification that needs test changes probably changed behaviour.              |
+
+## Red flags
+
+- Tests modified to make a "simplification" pass.
+- A "simplified" version that is longer or harder to follow.
+- Renames that follow your preference rather than the project's conventions.
+- Error handling removed because it "looked noisy".
+- Simplifying code you do not fully understand.
+
+## Self-check
+
+- [ ] The existing tests pass without modification.
+- [ ] No error handling was removed or weakened.
+- [ ] The result follows the project's conventions.
+- [ ] No dead code was left behind (unused imports, unreachable branches).
+- [ ] The diff stays inside the task's scope.

package/dist/skills/ralphctl-codebase-design/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ralphctl-codebase-design
+description: Shared vocabulary and tests for module design — deep modules (much behaviour behind a small interface), seams placed where behaviour actually varies, the deletion test for pass-through layers, and the interface as the test surface. Use when planning module boundaries, deciding where a seam or abstraction belongs, judging whether a layer earns its keep, or making code easier to test through its interface.
+license: MIT
+---
+
+# Codebase Design
+
+> Adapted from [mattpocock/skills — "Codebase Design"](https://github.com/mattpocock/skills) (MIT).
+> Adapted for ralphctl's harness contract.
+
+Design **deep modules**: a lot of behaviour behind a small interface, placed at a clean seam, testable
+through that interface. The aim is leverage for callers, locality for maintainers, and testability for
+everyone. Reason with the vocabulary below; in code and in signals, keep the project's own terms when it
+has established ones.
+
+## When this applies
+
+- **Plan** — when splitting work, prefer tasks that deepen one module behind a small interface over tasks
+  that spread one concept across several shallow ones. When a task introduces a seam, name it in the
+  steps along with what varies across it.
+- **Execute** — whenever you add a module, an interface, or an abstraction. When reviewing, apply the
+  deletion test and the one-adapter rule below to every new layer.
+
+## Vocabulary
+
+- **Module** — anything with an interface and an implementation, at any scale: a function, a type, a
+  package, a slice spanning several layers.
+- **Interface** — everything a caller must know to use the module correctly: the type signature, plus its
+  invariants, ordering constraints, error modes, required configuration, and performance characteristics.
+- **Implementation** — the code inside the module.
+- **Depth** — leverage at the interface: how much behaviour a caller or test can exercise per unit of
+  interface it has to learn. **Deep** when much sits behind little; **shallow** when the interface is
+  nearly as complex as what it hides.
+- **Seam** (Michael Feathers) — a place where behaviour can be altered without editing in that place; the
+  location where a module's interface lives. Where to put the seam is its own decision.
+- **Adapter** — a concrete thing that satisfies an interface at a seam. It names a role, not a size.
+- **Leverage** — what callers gain from depth: more capability per thing they learn.
+- **Locality** — what maintainers gain from depth: change, bugs, and knowledge concentrated in one place.
+  Fix once, fixed everywhere.
+
+## Principles
+
+- **Depth is a property of the interface.** A deep module can be built from small, swappable internal
+  parts; they are just not part of its interface. It may have internal seams for its own tests as well as
+  the external seam callers use.
+- **The deletion test.** Imagine deleting the module. If complexity vanishes, it was a pass-through. If
+  the complexity reappears across many callers, it was earning its keep.
+- **The interface is the test surface.** Callers and tests cross the same seam. Needing to test past the
+  interface means the module is the wrong shape.
+- **One adapter is a hypothetical seam; two adapters is a real one.** Introduce a seam only where
+  something actually varies across it — a second implementation, or a test fake standing in for slow or
+  non-deterministic infrastructure.
+
+When designing an interface, ask: can it have fewer operations, simpler parameters, more hidden inside?
+Before committing to one shape, sketch two or three genuinely different interfaces for the same job and
+compare them on depth, locality, and where the seam falls.
+
+## Designing for testability
+
+- **Accept dependencies instead of creating them.** A function that receives its payment gateway or
+  clock can be tested with a fake; one that constructs the real thing internally cannot.
+- **Return results instead of producing side effects.** Computing a discount and returning it is testable
+  by assertion; mutating a shared total in place is testable only by inspection.
+- **Keep the surface small.** Fewer operations mean fewer tests; fewer parameters mean simpler setup.
+
+## Rejected framings
+
+- **Depth as a ratio of implementation lines to interface lines** — it rewards padding the implementation.
+  Depth here means leverage.
+- **"Interface" as only a language keyword or a list of public methods** — too narrow; every fact a caller
+  must know is part of it.
+- **"Boundary"** for a seam — overloaded with domain-driven design's bounded context. Say seam or
+  interface.
+
+## Red flags
+
+- A module whose interface mirrors its implementation one-to-one.
+- A wrapper that only forwards calls.
+- An interface with exactly one implementation and no test fake — a seam nothing varies across.
+- A test that reaches past the interface into internals.
+- One concept spread across several shallow modules that must always change together.

package/dist/skills/ralphctl-debugging-and-error-recovery/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: ralphctl-debugging-and-error-recovery
-description: Systematic root-cause debugging. Use when tests fail, builds break, or behaviour does not match expectations. Follow stop-the-line → reproduce → localize → reduce → root-cause → guard-with-regression-test → verify, not guessing; the reproduction and regression steps follow the same red-green discipline as ralphctl-test-driven-development.
+description: Systematic root-cause debugging. Use when tests fail, builds break, something that worked before broke, or behaviour does not match expectations — when you need to figure out what broke and why. Follow stop-the-line → reproduce → localize → reduce → root-cause → guard-with-regression-test → verify, not guessing; the reproduction and regression steps follow the same red-green discipline as ralphctl-test-driven-development.
 license: MIT
 ---
 
 # Debugging and Error Recovery
 
-> Adapted from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT).
-> Adapted for ralphctl's harness contract.
+> Adapted from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT), with the
+> feedback-loop, ranked-hypothesis, and tagged-log practices drawn from
+> [mattpocock/skills](https://github.com/mattpocock/skills) (MIT). Adapted for ralphctl's harness contract.
 
 Systematic debugging with structured triage. When something breaks, stop adding features, preserve
 evidence, and follow a structured process to find and fix the root cause. Guessing wastes time. The
@@ -32,7 +33,7 @@ When anything unexpected happens:
 6. **Resume** only after the fix is verified with the project's narrow check gate.
 
 Do not push past a failing test or broken build to work on the next feature. Errors compound — a
-bug at Step 3 that goes unfixed makes Steps 4–10 wrong.
+bug at Step 3 that goes unfixed makes Steps 4–6 wrong.
 
 ## The Triage Checklist
 
@@ -42,6 +43,15 @@ Work through these steps in order. Do not skip steps.
 
 Make the failure happen reliably. If you cannot reproduce it, you cannot fix it with confidence.
 
+**Build a tight, red-capable loop before forming any theory.** When your session can run commands, the
+first deliverable is one command you have already run that drives the real code path and asserts the
+exact reported symptom — a failing test at the seam that reaches the bug, a script with a fixture input, a
+captured payload replayed through the code, the same input run through the old and new versions. Tight
+means fast (seconds) and deterministic, or for a flaky bug a pinned, high reproduction rate. Reading code
+to build a theory before that command exists is the failure this step prevents. When no loop can be built
+in this session, list what you tried and what would make it possible rather than guessing — in a `note`
+signal when the prompt's output-contract section lists it, otherwise in the required signal's own fields.
+
 When a bug is non-reproducible, work through these branches:
 
 - **Timing-dependent** — add timestamps to logs near the suspected area; try with artificial delays to widen race windows; run under load or concurrency to increase collision probability.
@@ -79,7 +89,12 @@ Create the minimal failing case:
 
 A minimal reproduction makes the root cause obvious and prevents fixing symptoms instead of causes.
 
-### Step 4: Fix the Root Cause
+### Step 4: Hypothesise, then Fix the Root Cause
+
+Before testing any explanation, write down three to five ranked hypotheses — a single one anchors on the
+first plausible idea. Each must be falsifiable: "if X is the cause, changing Y makes the symptom disappear".
+A hypothesis with no prediction is a hunch; sharpen it or drop it. Test them in rank order against the
+loop, changing one variable at a time.
 
 Fix the underlying issue, not the symptom.
 
@@ -149,6 +164,9 @@ when the prompt's output-contract section lists it, otherwise in the required si
 
 Add logging only when it helps. Remove it when done.
 
+- **Tag temporary logs** with one unique prefix (for example `[DEBUG-a4f2]`), so removal is a single
+  search. Untagged temporary logs survive into the diff; search for the prefix and remove every hit
+  before you signal the work complete.
 - **When to add** — you cannot localize the failure to a specific line; the issue is intermittent; the fix involves multiple interacting components.
 - **When to remove** — the bug is fixed and a regression test guards against recurrence; the log is only useful during development.
 - **Permanent instrumentation (keep)** — error boundaries with error reporting; API error logging with request context; performance metrics at key user flows.

package/dist/skills/ralphctl-deprecation-and-migration/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: ralphctl-deprecation-and-migration
+description: Discipline for removing or replacing code, interfaces, stored data shapes, and dependencies safely — confirm the replacement covers every consumer, migrate consumers incrementally behind an adapter or switch, change persisted data in additive expand-then-contract phases with a tested way back, and remove the old path only once nothing uses it. Use when retiring an API, module, feature, flag, or dependency, renaming or dropping a stored field, or moving callers from one implementation to another.
+license: MIT
+---
+
+# Deprecation and Migration
+
+> Adapted from [addyosmani/agent-skills — "Deprecation and Migration"](https://github.com/addyosmani/agent-skills)
+> (MIT). Adapted for ralphctl's harness contract.
+
+Code is a liability, not an asset: every line needs tests, upgrades, and attention from anyone working
+nearby. Deprecation removes code that no longer earns its keep; migration moves its consumers safely to
+what replaces it. Most teams are good at adding things and bad at removing them — this skill is the
+removal half.
+
+## When this applies
+
+- **Plan** — sequence the work so each step ships on its own: the replacement first, consumers next,
+  removal last and alone. Give the removal task the verification criterion "no remaining consumers", and
+  keep each data-shape phase below a separate task.
+- **Execute** — implement one phase per task. Do not fold an additive step and its destructive follow-up
+  into one change, and do not remove anything a consumer still reaches.
+
+## Before removing anything
+
+Hyrum's law makes removal hard: consumers depend on behaviour the replacement may not reproduce —
+ordering, defaults, error text, side effects. Answer first:
+
+1. Does the old thing still provide something nothing else does? If so, keep it.
+2. Who consumes it? Search code, configuration, scripts, docs, and tests, including dynamic lookups by
+   name. Consumers outside this repository may exist — say so rather than assume none.
+3. Does a replacement exist and cover every critical use? If not, build that first.
+4. What does each consumer's move cost, against the ongoing cost of keeping both?
+
+## The process
+
+1. **Replacement first.** It covers the critical cases and is proven, not just "theoretically better".
+2. **Mark the old path deprecated** with the project's own mechanism — a deprecation annotation, a
+   runtime warning, a changelog entry — when it has one. Do not invent a new notice file.
+3. **Migrate incrementally.** One consumer or area per change: find its touchpoints, switch it, confirm
+   behaviour matches with its tests, remove its reference to the old path. Whoever retires a thing
+   migrates its consumers or ships a compatible shim — never leave them to discover the break.
+4. **Remove only at zero.** Once no consumer remains: the code, its tests, docs, configuration, and the
+   deprecation markers themselves.
+
+## Migration patterns
+
+- **Strangler** — run old and new side by side and route a growing share to the new path; remove the old
+  one when its share is zero.
+- **Adapter** — keep the old interface as a thin layer over the new implementation, so consumers keep
+  working while the backend moves.
+- **Switch per consumer** — cut consumers over one at a time with the project's existing flag or
+  configuration mechanism.
+
+## Persisted data: expand, then contract
+
+A stored shape is the riskiest thing to change — reverting the code does not revert the data, and during a
+rollout old and new code run against the same store. Never change a stored shape in place:
+
+```
+EXPAND            →  MIGRATE                         →  CONTRACT
+add the new shape    write both, backfill old records,  stop writing the old shape,
+beside the old one   then switch reads to the new one   then drop it in a later change
+```
+
+- Additive first, destructive last and alone. Adds are safe in any release; drops and renames ship on
+  their own, after nothing reads the old shape.
+- Every migration has a tested way back — a down migration, or readers that tolerate both shapes.
+- A migration is safe to re-run and safe to interrupt; stamp what has been migrated.
+- Backfill in batches, off the hot path, so it does not lock or starve the store.
+- The same rules hold for files on disk: version the format, and keep readers tolerant of the old shape.
+
+## Zombie code
+
+Code nobody owns but something still depends on — no maintainer, failing tests nobody fixes, outdated
+dependencies. Either give it an owner and maintain it, or deprecate it with a concrete migration. It
+cannot stay in limbo.
+
+## Common rationalisations
+
+| Rationalisation                                   | Reality                                                                                   |
+| ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| "It still works, why remove it?"                  | Unmaintained working code accumulates risk and complexity silently.                       |
+| "Someone might need it later"                     | It can be rebuilt if needed. Keeping it "just in case" costs more.                        |
+| "Consumers will migrate on their own"             | They will not. Migrate them, or ship a shim that needs no migration.                      |
+| "Just rename the field, it's one line"            | During rollout, old and new code run together and one of them reads a field that is gone. |
+| "Add the new field and drop the old one together" | That couples a safe add to a destructive drop. Drops ship alone, later.                   |
+| "We'll write the way back if we need it"          | A migration with no way back is a release you cannot undo.                                |
+
+## Red flags
+
+- A deprecation with no working replacement.
+- Removal without a search for remaining consumers.
+- New features added to the deprecated path.
+- A stored field renamed or dropped in place.
+- A schema change and the code that depends on it shipped as one step.
+- A migration with no way back, or a backfill that locks the store.
+
+## Self-check
+
+- [ ] The replacement covers every critical use of the old path.
+- [ ] Every known consumer is migrated; unknown external consumers are named as a risk.
+- [ ] Persisted-shape changes are phased: expand, migrate, contract.
+- [ ] Each migration has a tested way back and is safe to re-run.
+- [ ] Removal deletes the code, its tests, docs, configuration, and deprecation markers.