ralphctl 0.26.0 → 0.28.0

package/dist/skills/ralphctl-frontend-ui-engineering/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: ralphctl-frontend-ui-engineering
+description: UI engineering discipline for user-facing interfaces — follow the project's design system and tokens instead of a generic look, handle loading, empty, error, and permission states, meet accessibility basics (keyboard access, labels, focus, contrast, never colour alone), and keep components focused with data loading separate from presentation. Use when building or changing screens, components, layouts, or interaction states in any UI stack.
+license: MIT
+---
+
+# Frontend UI Engineering
+
+> Adapted from [addyosmani/agent-skills — "Frontend UI Engineering"](https://github.com/addyosmani/agent-skills)
+> (MIT). Adapted for ralphctl's harness contract.
+
+Build interfaces that look like a design-aware engineer made them for this product: the project's own
+design system, every state handled, usable from a keyboard and a screen reader. The specifics differ by
+stack — a component framework, server-rendered templates, a native toolkit — so learn this project's
+before writing any UI.
+
+## When this applies
+
+- **Execute** — whenever the task builds or changes something a user sees or operates. When reviewing a
+  UI change, use the self-check below as the lens: a missing state or an inaccessible control is a
+  finding, not a nit.
+
+## Discover the UI stack first
+
+Find the component library, the theme or token file (colour, spacing, type, radius), the existing
+components that already solve part of the task, and how the project tests UI (component tests,
+accessibility checks, visual or browser tests). Reuse a house component before writing a new one.
+
+## Components
+
+- **One job per component.** A component that fetches, transforms, and renders is three things.
+- **Composition over configuration.** A growing list of layout and variant flags signals a component
+  that should accept children or slots instead.
+- **Data apart from presentation.** A container loads data and decides which state to show; a
+  presentational piece renders what it is given. The presentational piece is then trivial to test.
+- **The simplest state that works.** Local state first; lift it only when siblings share it; a shared
+  context for read-mostly app-wide values; the URL for shareable view state (filters, pagination); the
+  project's server-data layer for remote data; a global store only for complex client state many places
+  share. Use the mechanisms the project already has.
+
+## Follow the design system
+
+- Use the project's tokens for colour, spacing, type, and radius — never a raw value off the scale.
+- Keep the type hierarchy: heading levels in order, heading styles only on headings.
+- Use realistic content when building, not placeholder text — real lengths reveal wrapping and overflow.
+- Avoid the generic generated look: a default accent palette on everything, decorative gradients,
+  maximal rounding, uniform oversized padding, stock card grids, stacked shadows. Each one ignores the
+  product's real hierarchy; the project's system already decided these.
+
+## Handle every state
+
+Each view that loads or changes data needs, where it applies:
+
+- **Loading** — a placeholder that keeps the layout stable.
+- **Empty** — what this is and the next action, never a blank area.
+- **Error** — what went wrong in plain words and a way to retry.
+- **Partial or not permitted** — what the user can still do.
+- **Success** — feedback that the action happened.
+
+Check long and short content, and the narrowest and widest layouts the product supports.
+
+## Accessibility basics
+
+- Use native interactive elements (buttons, links, inputs) over clickable generic containers. A custom
+  control needs a role, keyboard focus, and the expected key handling.
+- Every control is reachable and operable from the keyboard, in a sensible order.
+- Every input has a label; an icon-only control has an accessible name.
+- Move focus deliberately when content changes — into a dialog when it opens, back when it closes.
+- Text meets WCAG AA contrast (4.5:1 for body text, 3:1 for large text).
+- Never convey state by colour alone; pair it with text or an icon.
+
+## Verification
+
+Extend the project's existing UI tests for the new states and controls. When the project has no way to
+check something in this session (a visual check, a screen-reader pass), say what was not verified in a
+`note` signal when the prompt's output-contract section lists it; otherwise fold it into the required
+signal's own fields.
+
+## Red flags
+
+- Raw colour or spacing values instead of tokens.
+- A view with no loading, empty, or error state.
+- A clickable element that the keyboard cannot reach.
+- Colour as the only indicator of state.
+- A new component that duplicates one the project already has.
+
+## Self-check
+
+- [ ] Uses the project's components and tokens.
+- [ ] Loading, empty, error, permission, and success states are handled where they apply.
+- [ ] Every interactive element works from the keyboard and has an accessible name.
+- [ ] Focus moves correctly when content changes.
+- [ ] Contrast meets AA; no state is conveyed by colour alone.
+- [ ] Works at the narrowest and widest supported layouts.

package/dist/skills/ralphctl-humanizer/SKILL.md

@@ -0,0 +1,137 @@
+---
+name: ralphctl-humanizer
+description: Edit prose so it reads like a specific person wrote it while keeping its meaning intact — remove staged contrasts, restating closers, run-up openers, reflexive lists of three, dash-chained clauses, inflated significance, promotional and stock model vocabulary, decorative bold and headings, and chat leftovers, while keeping every fact and the format the output contract requires. Use when writing or revising human-facing text such as a PR description, requirements prose, or a summary.
+license: MIT
+---
+
+# Humanizer
+
+> Concept from [blader/humanizer](https://github.com/blader/humanizer) (MIT), which builds on Wikipedia's
+> "Signs of AI writing" guide. The pattern catalogue below is written fresh for ralphctl, not copied.
+> Adapted for ralphctl's harness contract.
+
+Generated prose defaults to whatever suits the most readers, so the same safe moves recur in every text.
+Someone writing for a particular reader makes particular choices. This skill strips the defaults and keeps
+the content.
+
+## How this runs here
+
+- Apply it while writing the prose your output signal carries. The signal gets only the final text — no
+  draft, no list of patterns found, no commentary about the edit.
+- The prompt's output contract wins: keep its required headings, sections, field formats, and literal
+  values. Leave code, commands, paths, identifiers, and link targets exactly as they are.
+- Add nothing. No fact, name, number, date, or claim that is not in your source material. If a sentence
+  only works with a detail you don't have, simplify the sentence instead.
+
+## When this applies
+
+- **Create PR** — the title and the description body.
+- **Refine** — the prose around the requirements. Plain wording never costs a criterion its precision; a
+  testable predicate stays testable.
+
+## Method
+
+1. **Spot the patterns.** Go through the full draft and mark each pattern listed below. They also show up
+   across sentences and paragraphs: a contrast spread over two sentences counts, and so does every section
+   ending on an identical wrap-up line.
+2. **Rewrite each point plainly.** State it directly. When a paragraph is awkward, restructure it from its
+   central point instead of patching phrases. Let sentence length vary.
+3. **Check the result.** Nothing added, nothing lost. Then look once more for the tells that survive a
+   rewrite most often: contrasts, closers, threes, dashes, and bold labels.
+
+## Patterns, strongest first
+
+### Staging instead of saying
+
+1. **Contrast with a claim nobody made.** "This isn't just X — it's Y", "rather than X", a "No, it's
+   not…" sentence followed by the real point, a trailing "— no X needed". The negative half inflates the
+   positive one. A contrast earns its place if it fixes a misconception your reader really has, or if each
+   side tells them something.
+2. **Closers that restate.** A last short line repeating the paragraph ("That's the whole point."), a
+   string of fragments for drama, emphasis by capitals or dotted words. Cut it unless it adds a fact.
+3. **Borrowed depth.** "At its heart", "the real question is", "X is the currency of Y". Drop the
+   aphorism and state the concrete point.
+4. **Run-ups.** Announcing what comes next ("Here's the thing", "Let's walk through it", "Quick note").
+   Start with the content.
+5. **Answering no one.** "To be clear", "This doesn't mean", "You might think". Remove the defence unless
+   the objection is real in context.
+
+### Rhythm by habit
+
+6. **Reflexive threes.** Three items because three sounds complete. Keep three only when there are three
+   distinct things.
+7. **Repeated openings.** Consecutive sentences that open with the same word or phrase. Merge them or
+   vary the subject.
+8. **Dashes as default glue.** Reach for ordinary punctuation first (full stop, comma, colon, brackets) and
+   use a dash only when none of those works. Never touch a dash that belongs to code, a command, a path, or
+   a URL.
+9. **Piled hedges.** "Could potentially perhaps". Keep one qualifier where the doubt is real.
+
+### Inflation
+
+10. **Stock model vocabulary.** Words that turn up far more in generated text than in people's: delve,
+    seamless, leverage and harness (as figurative verbs), robust (when not technical), crucial, pivotal,
+    myriad, realm, tapestry, landscape (abstract), foster, elevate, empower, unlock, streamline,
+    showcase, underscore, testament, meticulous, game-changing, cutting-edge. Use the plain word. One on
+    its own is weak evidence; a cluster is strong.
+11. **Inflated significance.** "Marks a turning point", "paves the way", "raises the bar", a closing
+    paragraph about what the future holds. Stop once the concrete facts run out.
+12. **Editorialising -ing tails.** "…, highlighting its importance", "…, ensuring a smooth experience".
+    Keep the fact; drop the tail unless the source supports it.
+13. **Promotional tone.** "Powerful", "effortless", "best-in-class", "beautifully". Say what the thing does.
+14. **Vague authority.** "Experts agree", "widely regarded". Name the source or drop the claim.
+15. **Dodging plain verbs.** "Serves as", "functions as", "boasts". Use is and has.
+16. **Vague links.** "Associated with", "tied to". Name the actual relation, or keep the vague wording
+    when the source gives nothing more.
+
+### Formatting by habit
+
+17. **Bold everywhere.** Bold on ordinary words, or a bolded label plus colon at the start of every
+    bullet. Remove the bold, and when the labels say nothing, rewrite the list as sentences.
+18. **Decorated headings.** Title Case, emoji, arrows, a rule between every section. Use sentence case and
+    plain headings, unless the contract prescribes the heading text.
+
+### Leftovers
+
+19. **Chat residue.** "I hope this helps", "Great question", "Happy to adjust this", offers to do
+    more. Remove the wrapper, keep the content.
+20. **Writing about the text.** "Below is a summary of", "this description was generated from",
+    narrating how the text was assembled. Describing what a change replaces is fine in a PR description —
+    that is its subject.
+21. **Knowledge-limit filler.** Conceding that information is missing, then papering over the hole with
+    something that merely sounds right. Say plainly what is unknown, or delete the sentence.
+
+### Wrong reader
+
+22. **Telling the reader what they already know.** A reviewer already has the ticket and the diff. Open with
+    the decision and include only the argument that could change their mind about it.
+
+## Before and after
+
+Before:
+
+> This PR doesn't just fix the retry loop — it fundamentally transforms how we handle 503 responses,
+> ensuring a robust, seamless experience. Retries now stop at the configured limit.
+
+After:
+
+> Retries on a 503 response now stop at the configured limit instead of looping.
+
+Before:
+
+> **Performance:** Performance has been improved. **Reliability:** Reliability has been enhanced.
+
+After: cut both lines. Neither says what changed; name the concrete changes from the diff instead.
+
+## When not to act
+
+Don't rewrite a flagged phrase when it sits in a quotation, a name or title, or a passage about the phrase
+itself. A single tell is weak evidence; act on clusters. Keep what carries a writer's voice — an unusual
+specific detail, mixed feelings, a genuine aside.
+
+## Self-check
+
+- [ ] Every fact, number, and name from the source survives; nothing new was added.
+- [ ] The contract's required structure and literal values are untouched.
+- [ ] No staged contrast, restating closer, or run-up remains.
+- [ ] Code, commands, and paths are unchanged.

package/dist/skills/ralphctl-idea-refinement/SKILL.md

@@ -17,6 +17,8 @@ worth building — through structured divergent and convergent thinking, not a t
 - **Ideate** — the primary home: turning a raw prompt or hunch into evaluated, distinct directions.
 - **Refine** — when the input requirement is really an unshaped idea: run a compressed version of the phases below before writing acceptance criteria.
 
+**Not for:** a direction that is already chosen and now needs sharp requirements — that is ralphctl-spec-driven-development when installed.
+
 ## Philosophy
 
 - Simplicity is the ultimate sophistication. Push toward the simplest version that still solves the real problem.

package/dist/skills/ralphctl-iterative-review/SKILL.md

@@ -8,7 +8,8 @@ description: Cross-phase skill — treat AI output as a controlled feedback loop
 > Concept
 >
 > from [SPDD (Zhang & Xia, martinfowler.com) — "Iterative Review"](https://martinfowler.com/articles/structured-prompt-driven/iterative-review.html).
-> Adapted for ralphctl's three phases.
+> Adapted for ralphctl's three phases. Risk-first slicing draws on
+> [addyosmani/agent-skills — "Incremental Implementation"](https://github.com/addyosmani/agent-skills) (MIT).
 
 One-shot generation looks fast and is slow. The cheap review you skipped at iteration N becomes the expensive
 unwind at iteration N+5, when a regression that lived undetected through five steps surfaces only at the
@@ -32,11 +33,16 @@ deployed form — but the same posture also belongs **inside** each phase's work
 
 1. **Run the cheapest check first, often.** Lint, typecheck, narrow test runs — not the full suite — after
    each meaningful change. The point is to catch the regression at the seam, not to certify completion.
-2. **Re-read your own output once before submitting.** Whether it is criteria, tasks, or a diff, the second
+2. **Slice risk-first, and stay buildable between slices.** When the work has several parts, take the
+   least certain one first — the unproven integration, the unfamiliar API — so a dead end surfaces before
+   anything is built on it; a plan orders its tasks the same way. When your session can run commands,
+   confirm after each slice that the project still builds and its existing checks still pass, so the next
+   slice never starts on a broken tree.
+3. **Re-read your own output once before submitting.** Whether it is criteria, tasks, or a diff, the second
    read catches what the first one missed. Cheap.
-3. **Treat the check gate as a loop, not a finish line.** A failing gate is feedback, not a verdict. Apply
+4. **Treat the check gate as a loop, not a finish line.** A failing gate is feedback, not a verdict. Apply
    the fix and re-run; do not signal completion against a red gate.
-4. **When a fix attempt repeats the same failure, escalate rather than retry.** Two iterations of the same
+5. **When a fix attempt repeats the same failure, escalate rather than retry.** Two iterations of the same
    error is a plateau — the next fix is a guess. Surface the blocker rather than burning the budget on a
    third attempt: write a `note` signal in `signals.json` when the prompt's output-contract section lists
    it as an accepted kind; when it does not, use whichever blocked or narrative signal the contract does

package/dist/skills/ralphctl-observability-and-instrumentation/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: ralphctl-observability-and-instrumentation
+description: Instrument code so its production behaviour can be diagnosed from the outside — start from the questions an operator will ask, then emit structured events with stable names, a correlation id, and an entry-point field, bounded-cardinality metrics with latency percentiles, traces across async boundaries, and symptom-based alerts, never secrets or personal data. Use when adding I/O, retries, queues, background jobs, external integrations, or endpoints, or when a reported problem could not be diagnosed from existing telemetry.
+license: MIT
+---
+
+# Observability and Instrumentation
+
+> Adapted from [addyosmani/agent-skills — "Observability and Instrumentation"](https://github.com/addyosmani/agent-skills)
+> (MIT). Adapted for ralphctl's harness contract.
+
+Code you cannot observe is code you cannot operate. Instrumentation is written with the feature, the way
+tests are — when it ships without telemetry, the first reported bug becomes archaeology instead of a
+query.
+
+**Not for:** diagnosing a failure happening now (ralphctl-debugging-and-error-recovery when installed),
+or optimising measured slowness (ralphctl-performance-optimization when installed).
+
+## When this applies
+
+- **Plan** — for tasks that add I/O, retries, queues, jobs, or integrations, put the telemetry in the
+  task's steps and add a verification criterion that the failure path is observable. Name the operator
+  questions it must answer.
+- **Execute** — instrument as you build, with the logging, metrics, and tracing libraries the project
+  already uses. Adding a new telemetry stack is a decision for the task to make, not a side effect.
+
+## 1. Define "working" first
+
+Telemetry without a question is noise. Before instrumenting, write down two to four questions an operator
+will ask about this feature — what fraction succeeds first time, why permanent failures fail, whether a
+dependency is slower than usual. Every signal you add must help answer one of them.
+
+## 2. Pick the signal per question
+
+| Signal         | Answers                                  | Cost                          |
+| -------------- | ---------------------------------------- | ----------------------------- |
+| Structured log | What happened in this specific case?     | Per event; grows with traffic |
+| Metric         | How often, how fast, in aggregate?       | Fixed per series; cheap       |
+| Trace          | Where did the time go across components? | Per request; usually sampled  |
+
+Metrics tell you _that_ something is wrong, traces tell you _where_, logs tell you _why_.
+
+## 3. Structured logging
+
+- **Events, not prose.** A stable event name plus machine-readable fields — never a sentence built by
+  string interpolation that nobody can query.
+- **Levels used consistently** — error: an invariant broke and someone may need to act; warn: degraded
+  but handled (a retry succeeded, a fallback ran); info: a significant business event; debug: diagnostic
+  detail, off in production by default.
+- **A correlation id on everything.** Accept or create one at the system boundary and attach it to every
+  log line, span, and outbound call, so one request can be reconstructed from interleaved output.
+- **Name the entry point** when several entry points (a scheduler, a replay endpoint, a manual run) feed
+  one log. Set it where the run starts and propagate it with the correlation id across the same
+  boundaries — queue metadata, headers — rather than re-deriving it downstream.
+- **Never log secrets, tokens, passwords, or full personal data.** Log an allowlist of fields, never a
+  whole request body.
+
+## 4. Metrics
+
+Instrument rate, errors, and duration for every request-driven endpoint and every external dependency;
+utilisation, saturation, and errors for resources such as pools and queues. Labels come from small fixed
+sets (route template, status class, dependency name) — never user ids, raw URLs, or message text, which
+explode the number of series and belong in logs and traces. Record latency as a histogram and read
+percentiles; an average hides the slowest users.
+
+## 5. Tracing
+
+Prefer a vendor-neutral standard such as OpenTelemetry when choosing, and the project's existing setup
+when there is one. Use auto-instrumentation where the stack offers it; add manual spans only around
+meaningful units of work, with the attributes an operator will filter by. Propagate context across every
+async boundary or the trace dies at the gap.
+
+## 6. Alerting
+
+Alert on symptoms users feel (error rate, latency, queue age), not causes (CPU, one restart). Every alert
+is actionable, has a threshold and duration justified by an objective or by history, and uses one of two
+severities: act now, or act this week. When the project keeps runbooks, link each new alert to one; do
+not create a runbook location the task did not ask for.
+
+## 7. Verify the telemetry itself
+
+Instrumentation is code and can be wrong. Exercise the failure path in a test and assert the emitted
+event and its fields — the project's logger or metrics library usually offers a capture or in-memory
+sink. Checks that need a live environment (a dashboard, a tracing UI, firing an alert) cannot happen in
+this session: list them as unverified in a `note` signal when the prompt's output-contract section lists
+it; otherwise fold them into the required signal's own fields.
+
+## Red flags
+
+- A change adding retries, queues, or external calls with no new telemetry.
+- Log lines built by interpolation instead of structured fields.
+- No correlation id, or one shared log fed by several entry points with nothing naming which.
+- Metric labels carrying user ids, raw URLs, or error text.
+- Latency tracked only as an average.
+- Secrets, tokens, or whole request bodies in log output.
+
+## Self-check
+
+- [ ] The operator questions are named, and each signal maps to one.
+- [ ] Log output is structured, with stable event names and a correlation id.
+- [ ] No secret or unredacted personal data reaches any log line.
+- [ ] New endpoints and dependencies have rate, error, and duration metrics with bounded labels.
+- [ ] Latency is a histogram with queryable percentiles.
+- [ ] The failure path's telemetry is asserted in a test, or listed as unverified.

package/dist/skills/ralphctl-performance-optimization/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: ralphctl-performance-optimization
+description: Measure-first performance discipline — take a baseline with the project's own tooling, find the actual bottleneck, change one thing, re-measure the same way, and keep the change only when it beats run-to-run noise with the tests still green. Use when a task states a performance target, reports slowness or a regression, or touches a hot path, query, cache, or connection pool; not for speculative optimisation without evidence of a problem.
+license: MIT
+---
+
+# Performance Optimization
+
+> Adapted from [addyosmani/agent-skills — "Performance Optimization"](https://github.com/addyosmani/agent-skills)
+> (MIT). Adapted for ralphctl's harness contract.
+
+Performance work without measurement is guessing, and guessing adds complexity that costs more than the
+speed it buys. Measure, find the real bottleneck, fix that one thing, measure again — and keep only what
+the numbers justify.
+
+**When not to use:** there is no evidence of a problem. Optimising on a hunch is how neutral complexity
+lands.
+
+## When this applies
+
+- **Execute** — when the task carries a performance target or a slowness report, or the change touches a
+  hot path. The generator measures with the project's tooling; when reviewing, a performance claim with no
+  before-and-after numbers behind it is a finding, and so is an "optimisation" that changed behaviour.
+
+## The workflow
+
+```
+MEASURE → IDENTIFY → FIX ONE THING → RE-MEASURE (keep or undo) → GUARD
+```
+
+### 1. Measure
+
+Use what the repository already has — a benchmark target, a profiler, a timing harness, a query-plan
+command, a load script — found in its manifest, scripts, or CI configuration. Fix the budget before you
+start: the same command, the same input, the same conditions (warm or cold cache, sample count). Record
+the baseline numbers.
+
+### 2. Identify
+
+Let the symptom pick what to measure first:
+
+- **Startup or first load is slow** — payload or bundle size, blocking work at start, slow first
+  response.
+- **Interaction feels sluggish** — long synchronous work on the main thread or event loop, redundant
+  re-rendering or recomputation.
+- **One operation is slow** — profile it; read the query plan of each query it runs.
+- **Everything slows at once** — connection or thread pool exhaustion, memory pressure, CPU saturation.
+- **Slowness is intermittent** — lock contention, garbage-collection pauses, a slow external dependency.
+- **Memory keeps growing** — leaked references, unbounded caches or lists, retained payloads.
+
+### 3. Fix one thing
+
+Fix only the bottleneck step 2 identified. The usual suspects:
+
+- **Query per row (N+1).** Fetch the relation in the same query or one batched query, not in the loop.
+- **Unbounded fetching.** Every list read has a limit and a stable order.
+- **A query that ignores its index.** "Add an index" is the guess; the query plan before and after is the
+  measurement. A stale row estimate wants refreshed statistics, not a new index. Index for the query's
+  shape — equality columns first, then the range or sort column. An index that did not change the plan
+  is an undo, and every index taxes every write.
+- **Pool exhaustion.** Every operation slows together and time goes to waiting for a connection. A bigger
+  pool only moves the queue somewhere harder to see — find what holds connections, and size pools so the
+  total across all processes stays under the server's limit.
+- **Missing or wrong caching.** Cache only what is expensive to produce and read far more often than it
+  changes. Every input that changes the result belongs in the key (tenant, locale, permissions, flags) —
+  a key that omits the viewer serves one user's data to another. Pick one invalidation strategy and state
+  the acceptable staleness. Protect hot keys against a stampede (serve stale while one request
+  recomputes, or coalesce concurrent misses). Never cache what must be fresh.
+- **Repeated work in a hot loop.** Hoist the invariant; memoise only what the profile shows is costly.
+
+### 4. Re-measure: keep or undo
+
+A fix is a hypothesis until re-measured — the same way as the baseline. Change one thing at a time so the
+number is attributable, and repeat the measurement to compare the delta against run-to-run variance.
+
+| Result against the baseline   | Action                                   |
+| ----------------------------- | ---------------------------------------- |
+| Beyond the noise, tests green | Keep it.                                 |
+| Within the noise              | Undo it. Neutral is not a keep.          |
+| Worse                         | Undo it.                                 |
+| Faster, but a test went red   | Undo it — a regression dressed as a win. |
+
+Correctness gates the metric: an "optimisation" that wins by skipping work the product needed (a
+validation, a fresh read, an awaited step) is a regression.
+
+**Record every attempt, kept and undone alike.** An undone attempt leaves no trace in the diff, which is
+how the same dead idea gets tried again. Record idea, baseline and result, verdict, and why in a `note`
+signal when the prompt's output-contract section lists it; otherwise fold it into the required signal's
+own fields.
+
+### 5. Guard
+
+Protect the metric that justified the work. When the project already has a benchmark, performance test,
+or budget, extend it to cover this path. Do not invent a new gate or pipeline step the task did not ask
+for — name the missing guard in the same signal guidance as above instead.
+
+## Common rationalisations
+
+| Rationalisation                            | Reality                                                                             |
+| ------------------------------------------ | ----------------------------------------------------------------------------------- |
+| "This optimisation is obvious"             | If you did not measure, you do not know. Re-measuring an obvious win is cheap.      |
+| "The query is slow, add an index"          | Read the plan first. The index may exist and be unusable; every index taxes writes. |
+| "Just cache it"                            | Caching a cheap call buys a staleness bug and nothing else.                         |
+| "Raise the pool size"                      | It relocates the queue. Find what holds the connections.                            |
+| "It didn't help much, but it doesn't hurt" | Neutral changes are maintained forever and bought nothing. Undo them.               |
+| "We already wrote it, may as well keep it" | Sunk cost. The measurement does not care how long the change took.                  |
+
+## Red flags
+
+- An optimisation with no profiling data or baseline behind it.
+- Several optimisations measured as one number.
+- An index added without a query plan before and after.
+- A cache key that omits an input the result depends on, or a cache with no stated staleness.
+- A pool size raised in response to exhaustion without finding the holder.
+- A "win" that needed a test changed, skipped, or deleted.
+
+## Self-check
+
+- [ ] Before-and-after numbers exist, taken the same way.
+- [ ] The improvement exceeds run-to-run variance.
+- [ ] Changes that did not beat the baseline were undone.
+- [ ] Every attempt is recorded, including the undone ones.
+- [ ] The existing tests still pass — behaviour did not change.

package/dist/skills/ralphctl-ponytail/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: ralphctl-ponytail
-description: Anti-over-engineering ladder for choosing HOW to implement something — before writing custom code, climb the rungs in order and stop at the first that holds. Does this need to exist at all (YAGNI) → already in the codebase → standard library → native platform feature → already-installed dependency → one line → minimum code that works. Use when picking an implementation approach or evaluating a new dependency; for keeping the footprint of an already-chosen approach small, defer to the ralphctl-surgical-simplicity skill when installed.
+description: Anti-over-engineering ladder for choosing HOW to implement something — the smallest change that fully solves the task. Before writing custom code, climb the rungs in order and stop at the first that holds. Does this need to exist at all (YAGNI) → already in the codebase → standard library or platform feature → already-installed dependency → one line → minimum code that works. Use when picking an implementation approach or evaluating a new dependency; for keeping the footprint of an already-chosen approach small, defer to the ralphctl-surgical-simplicity skill when installed.
 license: MIT
 ---
 
@@ -11,7 +11,7 @@ license: MIT
 
 Be a lazy senior developer. Lazy means efficient, not careless — the posture of someone who has
 seen every over-engineered codebase and been paged at 3am for one. The best code is the code
-never written.
+never written: solve the whole problem with the least new code.
 
 ## When this applies
 
@@ -22,22 +22,27 @@ never written.
 - **Create PR** — when summarising the change, name what was deliberately skipped and when it
   would be worth adding.
 
+## Before you write
+
+Read the task and the code it touches. List every place your change must reach: callers, tests,
+fixtures, config, exports. Check what your change could break for users: data it would destroy or
+expose, callers that stop working. That is scope. Extra features are not.
+
 ## The ladder
 
-Stop at the first rung that holds:
+Stop at the first rung that fully works:
 
-1. **Does this need to exist at all?** Speculative need = skip it, say so in one line. (YAGNI)
-2. **Already in this codebase?** A helper, util, type, or pattern that already lives here → reuse it. Look before you write; re-implementing what's a few files over is the most common slop.
-3. **Standard library does it?** Use it.
-4. **Native platform feature covers it?** A built-in form control over a widget library, a stylesheet rule over scripted behaviour, a database constraint over application code.
-5. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
-6. **Can it be one line?** One line.
-7. **Only then:** the minimum code that works.
+1. **Does this need to exist at all?** Skip features, options, and flexibility nobody asked for, and say so in one line. (YAGNI) A vague request gets the smallest version that does the core job.
+2. **Already in this codebase?** A helper, util, type, component, or pattern that already lives here → reuse it, the way the surrounding code does. Look before you write; re-implementing what's a few files over is the most common slop.
+3. **Standard library or a native platform feature covers it?** Use it — a built-in form control over a widget library, a stylesheet rule over scripted behaviour, a database constraint over application code — unless the project has its own: a house component beats a native widget.
+4. **Already-installed dependency solves it?** Use it. Never add a new one for what a few lines can do.
+5. **Can it be one line a reader gets at a glance?** One line.
+6. **Only then:** the minimum code that works.
 
 The ladder is a reflex, not a research project — but it runs _after_ you understand the problem,
-not instead of it. Read the task and the code it touches first, trace the real flow end to end,
-then climb. Two rungs work → take the higher one and move on. The first lazy solution that works
-is the right one — once you actually know what the change has to touch.
+not instead of it. Trace the real flow end to end, then climb. Two rungs work → take the higher
+one and move on. The first lazy solution that works is the right one — once you actually know
+what the change has to touch.
 
 **Bug fix = root cause, not symptom.** A report names a symptom. Before you edit, find every
 caller of the function you're about to touch. The lazy fix IS the root-cause fix: one guard in
@@ -47,26 +52,30 @@ through.
 
 ## Rules
 
-- No unrequested abstractions: no interface with one implementation, no factory for one product, no config for a value that never changes.
+- Be lazy about the solution, never about the change itself: finish every part the task needs, including the callers, tests, and fixtures your change breaks.
+- No unrequested abstractions: no interface with one implementation, no factory for one product, no wrapper or type conversion nobody asked for, no config for a value that never changes. Keep values in the form the platform already gives you.
 - No boilerplate, no scaffolding "for later" — later can scaffold for itself.
+- Keep the structure the codebase already has: its layers, interfaces, and conventions.
 - Deletion over addition. Boring over clever — clever is what someone decodes at 3am.
-- Fewest files possible. Shortest working diff wins — but only once you understand the problem. The smallest change in the wrong place isn't lazy, it's a second bug.
+- Fewest files possible. Shortest working diff wins — but only once you know everything it must touch. The smallest change in the wrong place isn't lazy, it's a second bug. A one-liner that needs decoding is not short.
+- Code you move or merge keeps its error handling and validation.
+- Comment only the why the code cannot show, in one line.
 - Complex request? Ship the lazy version and question the rest: "Did X; Y covers it. Need full X? Say
   so." Write it as a `note` signal in `signals.json` when the prompt's output-contract section lists it,
   otherwise fold the question into the required signal's own fields. Never stall on an answer you can
   default.
-- Two standard-library options, same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
-- Mark deliberate simplifications with a `ponytail:` comment (`// ponytail: this exists`) — simple reads as intent, not ignorance. Shortcut with a known ceiling (global lock, O(n²) scan, naive heuristic)? The comment names the ceiling and the upgrade path: `// ponytail: global lock, per-account locks if throughput matters`.
+- Two options of the same size? Take the one that's correct on edge cases. Lazy means writing less code, not picking the flimsier algorithm.
+- A shortcut with a known limit (global lock, O(n²) scan, naive heuristic) gets a code comment naming the limit and the upgrade path, in this form: `// shortcut: global lock, per-account locks if throughput matters`.
 
 ## Output
 
-Code first. Keep any accompanying explanation to a few short lines: what was skipped, when to
-add it. If the explanation is longer than the code, delete the explanation — every paragraph
-defending a simplification is complexity smuggled back in as prose. Explanation the task
-explicitly asked for (a report, a walkthrough, per-step notes) is not debt — give it in full;
-the rule is only against unrequested prose. Deliberate skips worth remembering: skipped X, add
-when Y — as a `note` signal in `signals.json` when the prompt's output-contract section lists
-it, otherwise inside the required signal's own fields.
+Code first. Keep any accompanying explanation to one or two short lines: what you skipped or did
+not check, and any risk a reviewer must know. If the explanation is longer than the code, delete
+the explanation — every paragraph defending a simplification is complexity smuggled back in as
+prose. Explanation the task explicitly asked for (a report, a walkthrough, per-step notes) is not
+debt — give it in full; the rule is only against unrequested prose. Deliberate skips and unchecked
+risks worth remembering: skipped X, add when Y — as a `note` signal in `signals.json` when the
+prompt's output-contract section lists it, otherwise inside the required signal's own fields.
 
 ## When NOT to be lazy
 
@@ -82,9 +91,10 @@ up as efficiency and ships a confident wrong fix. Read fully, then be lazy.
 Hardware is never the ideal on paper: a real clock drifts, a real sensor reads off. Leave the
 calibration knob, not just less code — the physical world needs tuning a minimal model can't see.
 
-Lazy code without its check is unfinished. Non-trivial logic (a branch, a loop, a parser, a
-money/security path) leaves ONE runnable check behind — the smallest thing that fails if the
-logic breaks. No frameworks, no fixtures, no per-function suites unless asked. Trivial
-one-liners need no test — YAGNI applies to tests too.
+Lazy code without its check is unfinished. New non-trivial logic (a branch, a loop, a parser, a
+money/security path, or a whole new script or app) leaves ONE runnable check behind — one small
+test or an assert-based self-check, the smallest thing that fails if the logic breaks. No
+frameworks, no fixtures, no per-function suites unless asked. Trivial one-liners need no test —
+YAGNI applies to tests too.
 
 The shortest path to done is the right path.