skills

Fix a bug from a bug-report. ALWAYS apply this skill when the user asks to fix, patch, resolve, or close a bug, regression, or defect — including hot-fixes and revert-and-re-fix flows. Do not patch the symptom, ship a fix without a regression test that fails before and passes after, or scope-creep into unrelated changes. Skip this skill for authoring the bug-report itself (a separate upstream task), behaviour-preserving refactors, or behaviour-changing rewrites of existing modules.

Review another agent's work hostile-to-plausible-explanations. ALWAYS apply this skill when reviewing a branch, a follow-up revision after a previous review, an existing audit you are deepening, a bug you are root-causing, or a codebase area you are auditing — even if the work looks correct on the surface. Do not approve, merge, or sign off on a worker's pasted output alone — run the project's validation and tests yourself in your own worktree first. Skip this skill for original authoring work — apply it only when something already exists to be reviewed.

Back every claim with verbatim pasted output. ALWAYS apply this skill on any task that writes code, runs validations, runs benchmarks, or makes verifiable claims about behaviour — every claim in `## Self-review` gets its own pasted command output. Do not paraphrase results, summarise with "✅ all passing", or trust upstream pasted output (re-run yourself when reviewing). Skip this skill only for tasks with no verifiable claims (rare for product-development work; surface as a blocker if you suspect this applies).

Author an audit of present state. ALWAYS apply this skill when the user asks for a code audit, architecture review, technical-debt survey, or quality assessment of an existing codebase area — including deepening an existing audit. Do not prescribe new behaviour (that goes in a spec), include vague findings without file:line references, or leave any issue without a "Needed" line. Skip this skill for forward-looking specifications or defect reproduction — audits describe what is, not what should be or what broke.

Author a bug-report. ALWAYS apply this skill when the user reports a bug, observed defect, regression, or unexpected behaviour — including when the symptom is reproducible only intermittently. Do not include the fix in the bug-report, conflate symptom with root cause, or finalise the report without a verbatim reproduction output pasted into it. Skip this skill for fixing the bug (a separate downstream task once the report is in hand) or authoring a present-state audit — a bug-report is a defect record, not a fix and not a survey.

Author a research doc grounded in primary sources. ALWAYS apply this skill when the user asks for research, comparison, evaluation of options, or a recommendation that informs a downstream decision — including UX/market research and library/API/protocol research. Do not present opinion as finding, cite blog posts without finding the primary source, or output "it depends" without saying on what. Skip this skill for forward-looking spec authoring or present-state audit authoring — research is the upstream input to those, not a substitute.

Author a forward-looking spec. ALWAYS apply this skill when the user asks for a spec, requirements doc, design doc, or acceptance criteria for a feature or rewrite — even if they say "just write up what we want". Do not include implementation details, present-state observations, or proceed past a `[CRITICAL]` open question. Skip this skill for present-state observations of existing code, defect records, or research write-ups that inform a future decision — specs are forward-looking contracts, not surveys of what is.

Distil upstream docs accountably. ALWAYS apply this skill when transforming a high-verbosity document (research) into a lower-verbosity one (spec, audit, task), or when finalising a long-running investigation into a durable doc — append a `## Distillation Loss Statement` listing what was dropped and why downstream does not need it. Do not silently drop architectural constraints, API payload shapes, acceptance criteria, identified risks, or `[CRITICAL]` open questions during the distillation. Skip this skill for net-new authoring with no upstream document to distil from.

Diagnose and stabilise a flaky test. ALWAYS apply this skill when the user reports non-deterministic test failures, when CI shows occasional failures of the same test, when a test is quarantined / `.skip`'d for flakiness, or when the user says "passes locally but fails in CI" — even without the word "flaky". Do not re-run until green and declare it fixed, add sleeps or longer timeouts as the fix, swallow the nondeterminism in try/catch, or quarantine as the resolution. Skip this skill for deterministic failures, authoring tests from scratch, or feature work whose tests fail.

Adopt the Auditor persona. ALWAYS apply this skill when authoring an audit of present state (code audit, architecture review, technical-debt survey, quality assessment) — to enforce observation-not-prescription, file:line citations on every finding, severity calibration by impact, and dynamic-invariant verification. Do not blend personas, soften the constraints, or revert to default helpfulness mid-task. Skip this skill for forward-looking spec authoring or defect reproduction.

Adopt the Janitor persona. ALWAYS apply this skill when refactoring code to address audit findings, restructuring without changing behaviour, or methodically deleting orphan/dead code — to enforce behaviour preservation, per-batch architectural validation, documented shim contracts, and grep-before-delete. Do not blend personas, soften the constraints, or revert to default helpfulness mid-task. Skip this skill for behaviour-changing rewrites, API/framework migrations, or feature work.

Adopt the Skeptic persona. ALWAYS apply this skill when reviewing another agent's branch, deepening an existing audit, root-causing a bug, or fixing one — to enforce hostile-to-plausible-explanations review (run validation yourself, cite file:line, mistrust confident-sounding language). Do not blend personas, soften the constraints, or revert to default helpfulness mid-task. Skip this skill for original authoring work that has nothing yet to review.

Author or update user-facing documentation. ALWAYS apply this skill when the user asks for a README, how-to, tutorial, reference doc, public API doc, or contributor guide — anything a human (not an agent) reads to learn or look up. Do not mix Diátaxis frames in a single doc, hedge with "should/might/could", or include code examples you have not actually run. Skip this skill for agent-facing material (skill bodies, task templates, internal flow docs) — those follow different conventions and live elsewhere.

Implement a feature from a spec. ALWAYS apply this skill when the user asks to implement, build, or add a feature, when a spec doc is referenced, or when an acceptance criterion is named — even if the user does not name the spec explicitly. Do not start writing feature code directly without first surveying patterns, mapping criteria to steps, and halting on ambiguity. Skip this skill for bug-fix work against an existing implementation, behaviour-preserving refactors, or behaviour-changing rewrites of existing modules.

Migrate an API or upgrade a framework / language / library version across the codebase. ALWAYS apply this skill when the user asks to upgrade, migrate, port, or transition between API versions, framework majors, or language versions — including breaking-change adoption and codemod-driven sweeps. Do not change unrelated behaviour, skip wave-by-wave validation, or remove a shim without verifiable callsite coverage proof. Skip this skill for behaviour-preserving refactors of internals at a single API version, or implementing net-new features against a fresh spec at the new API version.

Optimise a measured bottleneck under a target. ALWAYS apply this skill when the user asks to optimise, profile, speed up, reduce latency / memory / CPU, or hit a perf target — under a stated metric and measurement condition. Do not change code without first establishing a baseline, compare benchmarks under different conditions, or skip the test suite because "it's just a perf change". Skip this skill for correctness fixes against a defect or net-new feature work against a spec — performance work is targeted optimisation, not opportunistic.

Restructure code to address audit findings without changing surface behaviour. ALWAYS apply this skill when the user asks to refactor, restructure, clean up, extract, or address an audit's "Needed" items — only when behaviour is preserved. Do not change observable behaviour, batch unrelated structural changes together, or remove a shim without proving call-site coverage. Skip this skill for behaviour-changing rewrites of existing modules, API/framework migrations, or net-new feature implementation against a fresh spec.

Re-implement a module with explicit behaviour changes. ALWAYS apply this skill when the user asks to rewrite a module with new behaviour, replace an implementation, or re-do something that was wrong — when behaviour will change deliberately. Do not start before the behaviour delta is explicit and recorded, preserve unintended differences, or proceed past an unplanned behaviour change without halting and updating the spec. Skip this skill for behaviour-preserving cleanup of existing modules, API/framework migrations, or net-new feature implementation against a fresh spec.

Add or improve test coverage. ALWAYS apply this skill when the user asks to add tests, increase coverage, write a regression test, or improve an existing test suite — including for a feature, fix, or audit "Needed" item. Do not test implementation details, skip the assertion-flip proof, or modify production code to make a test pass without spec authorisation. Skip this skill if the task is implementing or fixing code itself — tests are part of those deliverables, not a separate phase.

Adopt the Architect persona. ALWAYS apply this skill when authoring a spec, requirements doc, or design doc — to lock in structural rigour (alternatives-considered discipline, halt on `[CRITICAL]`, every requirement testable, no implementation details). Do not blend personas, soften the constraints, or revert to default helpfulness mid-task. Skip this skill for implementation work, audits, research, or bug-reports.

Adopt the Migrator persona. ALWAYS apply this skill when migrating an API, upgrading a framework / language / library version, or porting a codebase between API versions across many files — to enforce wave-by-wave validation, documented shim contracts with removal criteria, and callsite coverage proof. Do not blend personas, soften the constraints, or revert to default helpfulness mid-task. Skip this skill for behaviour-preserving refactor-only work at a single API version, or for feature work at a single API version.

Adopt the Performance Surgeon persona. ALWAYS apply this skill when optimising a measured bottleneck under a target (latency, memory, CPU, throughput) — to enforce measure-first discipline, same-protocol benchmarking, full-test-suite verification after every change, and document-the-conditions discipline. Do not blend personas, soften the constraints, or revert to default helpfulness mid-task. Skip this skill for correctness fixes or feature work that does not target a perf metric.

Adopt the Surveyor persona. ALWAYS apply this skill when authoring UX, market, or competitive research — to enforce concrete-examples discipline, observed-vs-claimed distinction, and a three-cited-references floor for any "common practice" claim. Do not blend personas, soften the constraints, or revert to default helpfulness mid-task. Skip this skill for technical research (libraries, APIs, algorithms, standards, peer-reviewed sources), or for non-research authoring.