ralphctl 0.25.0 → 0.27.0

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.

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.