skill-best-practices

Use when a change is written and "looks done" but has not had a hostile second pass before merge — especially diffs touching auth, money, migrations, concurrency, or anything the author is quietly unsure about. Spawns a fresh-eyes reviewer subagent that sees ONLY the diff and the spec, collects findings, drives fixes, and re-dispatches until findings degrade to nitpicks. Reach for this instead of self-reviewing; the author is the worst reviewer of their own diff.

Use when a PR is open and green-but-blocked, or red on CI for reasons that smell like flake — a timed-out test runner, a transient network 500 in a setup step, a check that passed locally but failed in CI. Reach for this whenever someone says "this PR keeps failing CI but the test is flaky", "can you babysit this PR to merge", "it's just a flaky check, retry it", or wants a PR shepherded through retries, conflict resolution, and auto-merge without sitting on it manually. Prefer this over hand-clicking "Re-run failed jobs" in the GitHub UI, which gives up no signal on flaky-vs-real and forgets to enable auto-merge.

Use when writing or reviewing code that meters API token usage, bills accounts, issues invoices, applies credit grants, or computes balances with the internal `billing` library — especially around retries, mid-cycle plan changes, cache-read vs cache-write token pricing, or any place where double-billing or rounding drift would be a problem.

Use when an API-credits checkout or paid-plan upgrade needs to be proven end-to-end against Stripe test mode — confirming a card charge actually creates the invoice and subscription in the right state, reproducing a "I paid but my credits didn't show up" report, checking that a declined or 3DS card fails the way the UI claims, or wiring a billing smoke test into CI so a checkout regression is caught before a customer's money is.

Use when a specific fix that's already on main needs to land on a production/release branch without dragging along everything else — a hotfix to backport, a "cherry-pick this commit onto release-2.4", a "we need just that one PR on prod" request. Reach for this whenever someone wants to port one or a few commits to a release branch and open a PR for it, especially before doing it by hand in their main checkout, which pollutes their working tree and routinely leaves conflict markers committed or loses the original commit's provenance.

Use when writing or editing code in this org's Python or JS/TS, especially before committing or opening a PR — and proactively the moment a diff adds an import, an except/catch, or any logging. Enforces the style rules Claude gets wrong by default: import grouping, error-wrapping (no bare except / empty catch), no leftover debug prints, explicit over clever. Runs scripts/check_style.sh (ruff, mypy --strict, eslint + grep guards) which exits nonzero so it drops into a pre-commit hook or CI.

Use when someone wants to compare two cohorts' retention or conversion, asks whether a difference between segments is "real" or "significant", wants retention curves for an A/B group or a launch vs control, or says one cohort "looks better" and needs the delta flagged with a p-value. Reach for this whenever the question is two-group comparison plus significance — and especially before eyeballing two percentages and declaring a winner, which ignores sample size and observation-window mismatch.

Use when a cloud bill already spiked and nobody knows why — storage or egress jumped, a specific bucket's cost ballooned, a cost-anomaly alert fired, or finance is asking "what changed this week?" Queries the billing export by service/bucket/region, diffs the suspect window against a prior baseline, and ranks the top movers. Insists on accounting for the 24-48h billing lag before declaring a trend, and points the investigation at the usual culprit: cross-region egress. Not for cost forecasting/estimation, general spend optimization, pricing questions, budget-alert setup, or latency "expense" — only for diagnosing an unexpected spike that already happened.

Use when creating a new internal app or tool — an admin dashboard, an ops console, a back-office service — that needs the org's auth, structured logging, and deploy config wired correctly from the start. Triggers on "new internal app", "spin up a dashboard", "create a back-office tool", "scaffold an internal service", or any greenfield app that real employees will log into. Pre-wires default-deny auth, PII-scrubbing logs, and an env-pinned deploy so the security and observability basics aren't an afterthought.

Use when the user wants to file, create, or open a Linear ticket / issue — "make a Linear ticket for this bug", "file an issue to track X", "open a ticket and ping a reviewer", or when turning a bug report, TODO, or Slack thread into a tracked ticket. Especially use it to avoid Linear API rejections from bad priority/status/team enum values or missing required fields, and to run the post-creation steps (ping reviewer, link in Slack) so the ticket doesn't get filed and forgotten.

Use when someone wants to add, upgrade, or vendor a third-party package and the org requires approval first — or when a PR adds a dependency that has not been license- and CVE-checked. Runs the request through the approval workflow: license compatibility, known-CVE scan (including transitive deps), sign-off, then a properly regenerated lockfile. Blocks copyleft licenses in proprietary services and refuses hand-edited lockfiles.

Use when shipping a change to the inference gateway and it needs to go out safely — build, smoke test, then ramp real traffic in stages while watching error rate and p99 against a baseline, rolling back automatically on regression. Reach for this whenever someone says "deploy the inference gateway", "roll out the new gateway build", "canary the gateway change", "ship this with a gradual rollout", or wants a traffic-shifted release with automatic rollback rather than flipping 100% of traffic at once. Prefer this over a manual `kubectl set image` / full-cut deploy, which gives no canary signal and no automatic rollback when latency or errors regress.

Use whenever building, restyling, or reviewing any in-house web UI — a new screen, a component, a marketing page, a dashboard, an empty state, anything with visual surface. Reach for this the moment you are about to pick a font, color, spacing value, shadow, or radius, so the output uses the house design system instead of generic defaults. Especially load this if the work is drifting toward the templated "AI-generated app" look (Inter + a purple/indigo gradient + heavy drop shadows + `#fff` on `#f9fafb`) — this skill exists to push that off the table and replace it with concrete house tokens.

Use when someone asks which events to join to see a funnel like signup → activation → paid, where the canonical user_id lives, how to count conversions between two product events, or why their event counts look inflated or don't match between steps. Reach for this whenever a question involves the raw event stream, joining events to users, deduping events, or measuring step-to-step conversion — especially before hand-writing SQL against the event tables, which almost always gets the user_id join wrong.

Use when GPU pods or PVCs linger with no owner reference and accelerator spend keeps climbing, when a finished training run left volumes behind, or when someone asks to "reclaim idle GPUs" or "clean up orphaned GPU nodes." Finds true orphans (no owner ref AND no recent activity), posts them to Slack for a soak period, and only after explicit human confirmation performs a guarded, cascading cleanup. Pushes back on deleting anything merely idle.

Use when someone needs the right Grafana dashboard for a symptom — high latency, error-rate spike, saturated nodes, queue backlog, a cost/egress jump — or asks for a dashboard link, a datasource UID, or which cluster/region variables to set. Reach for this whenever building a Grafana URL or picking a panel, because the datasource UIDs and org/cluster values are not guessable and a link built with the wrong one silently shows an empty or wrong-org dashboard. Not for building/designing dashboards in code, configuring a new datasource or alert rule, writing PromQL, debugging the Grafana instance, or Grafana pricing — this only finds the right existing dashboard.

Use when the inference API is paging — a p99 latency spike, a 429 surge, an elevated 5xx rate, a model returning gibberish, or a "the API is slow" Slack thread. Maps each symptom to the exact tools and query patterns that isolate the cause across metrics, logs, and traces, then emits a structured incident report. Reach for this the moment a dashboard or alert points at the highest-traffic inference API; do not hand-roll ad hoc queries.

Use whenever a task touches the internal platform via the `axle` CLI — deploying a service, reading or rotating secrets, tailing logs, running one-off commands or migrations in an environment, or inspecting env config. Reach for this any time you are about to run `axle ...`, or when a command "worked locally" but hung, targeted the wrong environment, or silently hit prod instead of staging. Especially load this before anything destructive (`axle deploy`, `axle db migrate`, `axle secrets set`, `axle exec`) or anything run from CI / a non-interactive shell.

Use when you have one request ID and need its whole story — a customer escalation citing a request_id, a trace that dead-ends, or a "what happened to this specific request" question during an incident. Fans out to every system that touched the request (gateway, model server, billing, traces), merges by request_id, and prints one timeline sorted by timestamp. Reach for this instead of grepping each log store by hand.

Use when standing up a brand-new inference microservice — a model-serving endpoint, a GPU-backed scoring API, a new FastAPI + Temporal worker — and it must match the org's production conventions out of the gate. Triggers on "new inference service", "spin up a serving endpoint", "scaffold a model API", or any greenfield service that will run on the GPU fleet and needs health probes, auth, structured logging, and graceful Temporal shutdown wired correctly before the first commit.

Use when authoring a database schema migration — adding or altering a column, creating an index, renaming a table, backfilling data — especially against a large production table where a careless DDL statement takes a lock and stalls every query behind it. Triggers on "write a migration", "add a column", "create an index", "alter the schema", "backfill", or any change to the database that has to ship safely and be reversible. Pulls in the org's migration template and the lock/backfill gotchas before the first line of SQL.

Use the moment a page fires and you are the oncall — an alert ID lands in PagerDuty, a "who's oncall, this just paged" Slack ping, or you wake up to a firing alert and need to triage before you understand it. Fetches the alert by ID, runs the standard first-five-minutes checks (is it flapping, did a deploy just land, is this cause or symptom), and emits a structured finding you can paste into the incident channel. Run this before manual digging.

Use when an end-to-end signup, email-verification, or onboarding flow needs to be exercised in a real browser — verifying a new sign-up still works after a frontend/auth change, reproducing a "user stuck on onboarding" bug, checking the verification email actually arrives and its link lands the user in the right place, or wiring a smoke test for the account funnel into CI.

Use when the user needs to write, generate, or post a daily standup update — pulling together what they did since yesterday from Linear tickets, GitHub PRs/commits, and the prior standup, especially when they say "do my standup", "what did I do yesterday", "draft my standup for

Use when deciding what or how to test, or reviewing test quality — adding tests for new logic, judging whether a change needs coverage, or critiquing a test that mocks heavily, reads the clock, hits the network, or asserts on internals. Steers toward testing behavior over implementation, one concept per test, deterministic runs, and covering error paths — not just the happy path. Runs scripts/check_test_hygiene.sh to flag flaky/brittle/falsely-green smells; exits nonzero for a pre-commit hook or CI. Not for running the suite, debugging a failing test, test-tooling/fixture setup, speeding up CI, or red-green TDD (use the TDD skill to write a failing test first).

Use when an interactive command-line tool needs to be tested as a real user would drive it — a CLI that only behaves correctly with a real TTY (prompts, password masking, spinners, full-screen TUIs, paging), reproducing a "the prompt hangs / the wizard skips a step" bug, or asserting on what an internal CLI actually prints to the terminal rather than what a piped/non-interactive invocation does. Reach for this whenever piping stdin "works" but the interactive path is what's broken.

Use when the user wants a weekly recap, "what shipped this week", a team digest, or an "in case you missed it" roundup — merged PRs + closed tickets + deploys formatted into one update for Slack or a changelog. Especially use it when a recap is recurring and should cover only the window since the last recap (no overlap, no gaps), and when the raw lists are noisy with bot PRs and duplicate PR/ticket pairs that need collapsing.