What your Claude Code and Codex sessions were for

---
name: pr-first-pass-risk-review
description: "Runs a fast, risk-focused first-pass review of a teammate's pull request, covering metadata, the diff, high-risk changed code, test coverage, and a prioritized findings report."
---

<!-- Draft generated by friskme from 6 sessions of "Reviewing pull requests" on 2026-11-12. Review and edit before installing to ~/.claude/skills/pr-first-pass-risk-review/SKILL.md. -->

# pr-first-pass-risk-review

Runs a fast, risk-focused first-pass review of a teammate's pull request, covering metadata, the diff, high-risk changed code, test coverage, and a prioritized findings report.

## When to use

Use when the user asks for a first-pass, risk-focused, or focused (e.g., error handling or tests) review of a pull request by number or link, with or without asking for review comments. Do not use for authoring or fixing the PR.

## Steps

1. Fetch the PR once: title, description, base and head refs, author, linked issue, changed-file list, and the full diff. Use a single batched call where the available tool allows it instead of several metadata calls.
2. Triage changed files by risk before reading code. Rank higher: authentication and authorization, money or amount handling, persistence and migrations, external API calls, webhooks, config and secrets handling, and error-handling paths. Rank lower: docs, snapshots, generated files, and pure formatting.
3. Read the high-risk changed files in one pass, and open only the direct callers, types, or tests needed to confirm behavior. Do not re-read a file you already have in context.
4. Check each high-risk change for common defects: currency or unit mistakes (rounding, cents vs. units), non-idempotent retries, unhandled promise rejections or thrown exceptions, swallowed or over-broad catches, missing input validation at trust boundaries, missing authz checks, sensitive data in logs, race conditions, and breaking changes to public APIs or schemas.
5. Check test coverage for the changed behavior. Flag missing tests for error paths and edge cases. If the user named a focus area such as error handling or tests, examine that area first and in depth.
6. Record each finding with file, line reference, severity (blocking, should-fix, or nit), and a one-line reason. Drop speculative findings you cannot tie to a specific line of the diff.
7. If the user asked for review comments, submit all of them together as one batched review rather than one call per comment, and keep only findings that are real risks. If comments were not requested, present the drafts in the reply and do not post them.
8. Finish with a short summary: an overall verdict, the top risks, and what you did not verify (for example, tests you did not run or runtime behavior you could not check).

## Notes

Sessions showed the same loop repeated: two metadata calls, two single-file reads, then three separate review or comment calls, roughly seven tool calls each time. Batch the metadata and diff fetch at the start and submit comments in one review at the end to cut round-trips. Reads were also split across file-read and shell-based file tools depending on the session; choose the one already connected and use it consistently. Do not claim tests pass unless they were run. Do not post comments on someone else's PR unless the user asked for them. Avoid copying PR numbers, repo names, or paths into the skill; use the current PR's details only in the reply.

---
name: write-or-update-docs-pages
description: "Writes new getting-started docs pages or updates existing guide sections (such as auth or config guides) in a docs site by matching sibling page conventions, verifying names in the codebase, and running one docs build check."
---

<!-- Draft generated by friskme from 4 sessions of "Writing and updating docs" on 2026-11-12. Review and edit before installing to ~/.claude/skills/write-or-update-docs-pages/SKILL.md. -->

# write-or-update-docs-pages

Writes new getting-started docs pages or updates existing guide sections (such as auth or config guides) in a docs site by matching sibling page conventions, verifying names in the codebase, and running one docs build check.

## When to use

Use when asked to write a getting-started page for a feature or to update a configuration or auth guide for a changed format. Use it for markdown docs work in a docs-site repository.

## Steps

1. Read the closest existing page first: a sibling getting-started page for new pages, or the guide being updated for edits. Note its frontmatter, heading levels, code-fence style, and section order so the new content matches.
2. Grep the codebase for the feature's exact identifiers (config keys, env var names, endpoints, CLI flags, function names) before writing any example. Do not write names from memory.
3. For a new getting-started page, create it from the sibling's structure: title, one-paragraph purpose, prerequisites, numbered setup steps, one minimal working example, and links to next steps.
4. For an update to an existing guide, grep for the old format's keys or headings to find every affected location, then edit only those sections and leave unrelated content untouched.
5. Keep every code sample consistent with the verified names and the current config format. Use obvious placeholders such as <YOUR_API_KEY> for secrets and never paste real values.
6. If the docs site uses a navigation file, sidebar, or index, add or update the entry for any new page so it is reachable.
7. Run the project's docs build, lint, or link-check script once through the package manager. Fix only the errors it reports, then rerun it once if needed.
8. Finish with a short summary listing the files changed, what was verified against the code, and anything you could not confirm.

## Notes

The sampled sessions were uniform (Read, Grep, Edit, one package-manager call) with zero errors, so the efficient path is short: read the reference page, grep for exact names, edit, and run one build check. Avoid re-reading files you already have and avoid repeated builds. The main risk in this work is inventing config keys or examples without grepping first, which produces wrong docs that only surface later. Keep the steps generic and do not hard-code project-specific page names, paths, or secrets into the skill.

---
name: fix-failing-and-flaky-tests
description: "Diagnoses and repairs a failing or flaky test file or suite by reproducing the failure, reading the spec and the code under test, making the smallest correct fix, and verifying with the file and then the full suite."
---

<!-- Draft generated by friskme from 4 sessions of "Fix failing and flaky tests" on 2026-11-12. Review and edit before installing to ~/.claude/skills/fix-failing-and-flaky-tests/SKILL.md. -->

# fix-failing-and-flaky-tests

Diagnoses and repairs a failing or flaky test file or suite by reproducing the failure, reading the spec and the code under test, making the smallest correct fix, and verifying with the file and then the full suite.

## When to use

Use when a named spec file or test suite fails locally or in CI, when a test started failing after a merge or rebase, or when a test passes and fails intermittently. Apply it to any module area such as checkout, cart, auth, search, tax, ledger, exports, or ingest.

## Steps

1. Detect the package manager and test runner from lockfiles and package.json scripts before running anything. Use the project's own test script rather than guessing a command.
2. Reproduce the failure by running only the failing spec file, with its name passed as an argument. Capture the first assertion or error message and the stack frame that points into project code.
3. Classify the failure before editing: a deterministic assertion mismatch, a missing or changed import or fixture, a shared-state or ordering dependency, a timing or async race, or an environment difference such as timezone, locale, or env vars. Check `git log` or recent diffs on the spec and the module it covers when the failure began after a merge.
4. Read the spec and the code under test together. Decide whether the regression is in the source (the behavior changed unintentionally) or in the test (the expectation is stale). Do not weaken or delete an assertion to make it pass unless the new behavior is clearly intended; if it is intended, update the expectation and say so.
5. Make the smallest edit that fixes the root cause. For flaky tests, remove the nondeterminism: await real promises instead of sleeping, inject or freeze clocks and random seeds, reset shared mocks and state in beforeEach or afterEach, and avoid depending on test execution order.
6. Re-run the single spec file several times (for example 3 to 5 runs) to confirm the fix is stable. For suspected flakiness, run it under the same conditions that failed before, such as a single worker or random order, to confirm the race is gone.
7. Run the full suite once to catch regressions the fix may have caused in neighboring specs or shared helpers. If unrelated tests fail, check whether they were already failing on the base branch before changing them.
8. Report back concisely: the root cause, the files changed, the command used to verify, and any remaining known-failing or skipped tests, without claiming the suite is green unless the full run actually passed.

## Notes

Every sample session hit one tool error and then re-ran commands, which suggests the first test invocation used the wrong runner, flags, or working directory. Step 1 and step 2 prevent this by reading the scripts first and running a single file with the correct invocation. The sessions also followed a fixed read-grep-read-edit cycle and then ran the whole suite as an afterthought; step 3 asks for failure classification and merge history up front so the edit targets the cause rather than the symptom. Flaky-test work is easy to "fix" by retrying or by loosening assertions, which hides real bugs; step 4 and step 5 require a root-cause decision and removal of nondeterminism instead. Running only the one file after an edit can miss breakage in shared helpers, so step 7 requires the full suite and a base-branch comparison for unrelated failures. Keep fixes out of unrelated files, and never paste secrets, tokens, or machine-specific paths into test code or reports.

---
name: payments-api-endpoints
description: "Adds or extends REST endpoints for payments resources (refunds, coupons, disputes, customers, payouts, webhooks) with request validation, tests, and matching OpenAPI spec updates, following the conventions already in the repo."
---

<!-- Draft generated by friskme from 4 sessions of "Payments API endpoints" on 2026-11-12. Review and edit before installing to ~/.claude/skills/payments-api-endpoints/SKILL.md. -->

# payments-api-endpoints

Adds or extends REST endpoints for payments resources (refunds, coupons, disputes, customers, payouts, webhooks) with request validation, tests, and matching OpenAPI spec updates, following the conventions already in the repo.

## When to use

Use when asked to add a route, CRUD operations, or validation for a payments resource in a payments API codebase, including follow-ups asking to document it in the OpenAPI spec. Use it for list/create/get/update/delete work on existing payment-domain resources.

## Steps

1. Read one existing sibling resource end to end (handler, request types, validation, and its test file) before writing anything, so the new code matches the project's naming, error shape, and routing style.
2. Read the router or route registration file to find where the new route group is mounted and any middleware (auth, idempotency, versioning) that applies under the version prefix.
3. Write each new Go source file in full in a single pass: handler, request/response types, and validation. Avoid writing a file and then patching it with multiple follow-up edits.
4. Validate request bodies at the boundary: required fields, types, enum values, currency and amount constraints (integers in minor units, positive where required), and ID formats. Return the same validation error structure the sibling handlers use.
5. Register the route in the router under the correct versioned path and method, reusing the existing middleware chain rather than adding new wiring.
6. Write table-driven tests covering the happy path, each validation failure, not-found or conflict cases, and the response shape. Put them alongside the sibling tests and reuse their helpers and fixtures.
7. Run the package build and its tests once (for example go build ./... and go test on the touched packages) and fix any failures in the same pass before moving on.
8. Update the OpenAPI spec in the same change: add the path, method, parameters, request and response schemas, and error responses that mirror the implementation. Reuse existing component schemas and refs instead of duplicating them.
9. Confirm the spec and the code agree on field names, required flags, status codes, and paths, then summarize the endpoints added and any assumptions made about domain rules.

## Notes

The sessions show no tool errors or interrupts, but they reveal a predictable pattern worth optimizing. The OpenAPI update was requested as a follow-up in every session, so the skill includes it up front instead of waiting to be asked. Go files were written, rewritten, and then patched with an Edit, which suggests the first draft was incomplete; drafting each file completely before writing avoids that churn. Validation and the build/test run happen only at the end, so a single verification pass catches problems early rather than after several rounds. Resource-specific names, paths, and secrets were intentionally left out; the agent should take them from the existing codebase at runtime.