claude-dotfiles

Audit a blueprint (or other plan/design/spec/diff) against the repository's Accepted ADRs to find where it VIOLATES or CONTRADICTS a binding decision — using parallel sub-agents that each own a slice of the ADR corpus, then a synthesized verdict. This is a companion to blueprint-review, meant to run during blueprint work once the design is drafted and before the build starts. Use when the user says "check the blueprint against our ADRs", "does this violate any ADRs", "audit the plan for ADR compliance", "make sure the blueprint doesn't contradict an ADR", or "/blueprint-adr-audit". It is READ-ONLY: it reports findings and does not edit the plan, the ADRs, or any code. Do NOT use it to WRITE a new ADR (that is adr-write), to REVIEW the blueprint for gaps/correctness (that is blueprint-review), to review code for bugs (/code-review), or to check a spec's documentation quality (review-openapi).

Review an existing Blueprint (the single product + technical design document) for gaps, inconsistencies, unresolved questions, correctness holes, and ambiguities that would force decisions during the build, then produce an updated version. Use when the user asks to "review the blueprint", "check the blueprint", or "update the blueprint". Reviews both halves and the user-stories section in one pass. Do NOT use to start a new Blueprint from scratch (use blueprint-create) or to make minor wording edits that don't need a structured review.

Finish a Linear ticket from inside its worktree and hand it back to the captain: verify the PR merged, set the ticket to Done, and post a `## Ticket Done` entry to the ticket's PROJECT status-update timeline (never a ticket comment) so the orchestrating /captain picks it up on its next re-hydrate. Use when a ticket's PR is merged and you're closing it out — 'captain done', '/captain-done', 'finish this ticket and tell the captain', 'mark this done for the captain', 'hand this back to the captain'. This is the worker-side finishing counterpart to /captain (the orchestrator) and a specialization of /linear-handoff for the merged-and-closed moment. Do NOT use to pause mid-ticket (use /linear-handoff), to hand off one long-running ticket's own progress as a ticket comment (that's /linear-handoff issue mode), or when the work isn't part of a captain-managed project.

Manage a Linear project across sessions as an orchestrator: each invocation it re-hydrates project state from Linear (the source of truth) plus its own last project status update (its memory), tells you what changed and what's ready next, and on your go launches the next ticket as a herdr worktree + Claude session via the captain-next wrapper. It sequences work (what's next, what's parallel-safe), keeps Linear current by writing the next project status update, and reconciles finished worktrees. Use when the user says 'run the captain for <project>', '/captain', 'what's next on <project>', 'manage the git-server build', 'start the next ticket', or 'I finished <ticket>, what now'. It is the ongoing, managing counterpart to /linear-resume (a one-shot read) and it drives /linear-start via the launcher. You can also ask it to help plan the project or create tickets WITHIN that already-managed project — the loop below is its default job, not its limit. Do NOT use captain to create or capture a standalone ticket, sp

Pick up a Linear ticket and start working it. Fetch the ticket, verify the current branch matches Linear's own git branch name (the worktree is created before the session, e.g. by a claude-branch-style wrapper), then classify the ticket (bug / improvement / feature) from its Linear labels — falling back to its content when unlabeled. Bugs and trivial improvements start immediately; features with enough detail hand off to /blueprint-create. Use when the user says 'pick up <TEAM>-<NUM>', 'work this ticket', 'start <ticket>', 'start working ENG-42', '/linear-start', or gives a Linear id/URL and asks to begin. This is greenfield only — to *resume* an in-flight build or long-running ticket from its latest handoff, use /linear-resume first. Do NOT use to merely create a ticket or to open a PR — those belong to the ticket-creation and PR skills.

Write or edit writing in the user's practitioner blog voice — experience-backed, conversational, story-driven, opinionated but humble. Use for blog posts, tech specs, engineering communications, and any long-form writing the user asks for. Activated when the user asks to "write a post", "draft a blog", "write up X", "edit this for style", "review this for my style", or invokes /writing-style directly.

Record the dated state of in-flight work in Linear — not a checked-in file — so the next session resumes from Linear. The handoff goes in whichever container spans the work: a Linear PROJECT (a coordinated multi-ticket build) gets a status update; an ISSUE (an epic, or a single long-running ticket) gets a `## Handoff` comment. Use when you finish or pause work that will be resumed later, or when the user says 'post a status update', 'record where the build is', 'hand off the build', 'write a handoff', 'update the project status'. This is the redirect target from the generic /handoff skill for Linear-tracked work. Do NOT use for work not tracked in Linear at all (use /handoff to write a file), or for design rationale (use /decisions-capture or /adr-write).

Resume in-flight work tracked in Linear by reading the latest handoff and surfacing where things stand + the reasoned next step. READ-ONLY: it reads, it does not branch, set up a worktree, change ticket status, or post anything. Use when the user says 'resume <project>', 'where did we leave off', 'pick up the git-server build', 'what's next on this ticket', '/linear-resume', or hands a Linear project/epic/ticket link and wants to continue. Two modes: (1) hand it a PROJECT or EPIC to learn which ticket is next, then run /linear-start <ticket>; (2) hand it a single TICKET to re-hydrate a long-running, multi-session effort on that one ticket. Do NOT use to start work on a fresh ticket (that's /linear-start, run inside the ticket's worktree) or to write a handoff (that's /linear-handoff).

Review an OpenAPI spec as the product it is — documentation for an external API consumer — and fix what fails that reader. Catches internal-context leaks (framework names, repo doc paths, ticket/design-doc ids, 'per <framework>' justifications), spec-splained self-correction machinery (did-you-mean 404s, teaching-error rules), condition-specific vocabulary on shared schemas that renders under every status, union error vocabularies that advertise codes an endpoint cannot return, and missing or incoherent request/response examples. Use when the user says 'review the openapi', 'review-openapi', 'audit the API docs', 'review the spec', or after contract changes. This is the API-consumer counterpart to review-for-reader (which reviews code comments/docs for the next maintainer); it is NOT a schema/breaking-change checker (use review-behavior-change) and NOT a linter substitute (duh lint still runs).

Run the full post-implementation review/hardening pass as one headless pipeline in an isolated worktree: code-review -> review-validate -> green-gate -> invariant-test -> review-tests -> review-openapi -> review-for-reader, then stop and present a unified report + combined diff for you to merge into the PR branch. Each stage's intentionally-failing tests are t.Skip()'d in place so later stages see a green baseline. Use when the user says 'run the review suite', 'review-suite', 'do the full review pass', or wants the tail of the workflow (validate/invariant/tests/openapi/reader) automated after a feature is built. Do NOT use for the design phase (blueprint/goal), for a single review skill (call it directly), or to fix a known list of bugs (use review-validate).

Emit a /goal command pointed at a feature directory containing a blueprint.md (or the legacy prd.md + tech-spec.md). Use whenever the user wants to implement, build, ship, or run a feature whose design lives in a docs/features/<name>/ directory (or similar). Do NOT use for design discussions or one-shot edits.

Write a brief capturing the current state of in-flight work so it can be resumed in a fresh context window. Use when the user says "write a handoff", "summarize this session", "I want to continue in a new context", or needs a continuation brief for PRs/investigations that aren't done yet.

Review a PR/diff from the perspective of the next maintainer who never saw the change — catching comments, docstrings, and docs that only make sense to someone holding the diff ("diff-anchored writing"), stale comments referencing removed code, journal/history comments, what-not-why comments, and README/doc drift. Then rewrite the flagged prose to current-state phrasing in place. Use when the user says "review for the next reader", "review my comments", "check for diff-anchored comments", "review the PR as a maintainer", "does this make sense without the diff", or "review-for-reader". This is the prose/reader counterpart to review-behavior-change (which reviews the contract) and is NOT a bug finder (use code-review / the built-in /review) or a guideline linter (use review-guidelines).

Run one continuous back-and-forth design discussion — product definition and technical design together — and write a single Blueprint to docs/features/{feature}/blueprint.md. Use when the user asks to "write a blueprint", "create a blueprint", "design this feature", "scope and design X", or otherwise wants to think through both what a feature must do and how it will be built before implementation. Replaces the older multi-document PRD + tech-spec + stories flow with one document and one conversation. Do NOT use for bug fixes or tweaks too small to warrant a design document, or when the user is brainstorming without committing to a document.

Spawn parallel advocate sub-agents to deliberate on a high-impact decision, then synthesize their arguments into a structured comparison with a recommendation. Use when a decision is central to the design, cascades to many other decisions, is hard to reverse, or genuinely uncertain. Triggered automatically by blueprint-create and blueprint-review when they detect a high-impact decision, or invoked directly by the user with "deliberate on this" or "/deliberate".

Create a standalone HTML explainer that teaches a thing visually, from the outside in — leading with the perspective of the person who uses or calls it (a UI's end user, a library's caller, a service's API consumer, an implementation's invoker) before any internal detail. Use when asked to "explain X visually", "make an explainer for X", "write a visual explainer", "explain this from the user's perspective", "render an explanation of X as a page", or to walk through how something behaves/works for the people who depend on it. Self-contained (bundles its own dark "dimmed-terminal" template); if the project has an html-docs skill or docs/design.md, prefer those tokens. Do NOT use for plain reference docs with no teaching/perspective angle, or for PRDs/ tech specs.

Turn a feature's design document (its blueprint, or a legacy tech spec) into a human-facing overview document for developers impacted by the change. Use when you want to communicate a technical change to the broader engineering org: "write a developer communication", "create an overview for devs", "make this accessible to impacted engineers", "create an overview from the blueprint".

Write the fewest words that carry the facts — terse, plain, human, not lawyerly. Auto-apply whenever the user asks to draft a message, write something up, write a Slack/email/standup/PR description, or 'write up X for the team'. Also invocable directly as /lazy. Do NOT apply to ADRs, blueprints, tech specs, or other documents where structure and completeness are the point.

Review whether a feature's existing tests actually cover the acceptance criteria, scenarios, and correctness constraints documented in its Blueprint (blueprint.md) — then fill the gaps with surface tests, and finally sweep the implementation's code coverage to a soft 80% floor by surfacing still-uncovered code as candidate behaviors. Spawns gap-finding sub-agents plus a validator and a skeptic to eliminate false positives, then (when nothing is left for the user to decide) an implementer that writes the missing tests following the surface-testing skill. Use when the user says "review the tests", "check test coverage for this feature", "find test gaps", "review-tests", or wants to audit a feature's tests against its blueprint. Do NOT use to write tests from scratch for an unbuilt feature, or to validate a list of already-identified bugs (use review-validate for that).

Derive surface tests from a service's stated invariants (Accepted ADRs, load-bearing doc comments, tech specs), targeting the assertions a codebase's defensive mechanisms (mutexes, transactions, atomic backend ops) cannot satisfy — then write each test and mutation-validate it red-then-green so it provably fails when the invariant is violated. Use when the user says "test the invariants", "what test would have caught this", "find correctness-test gaps", "harden the tests against invariant violations", "invariant-test", or after a concurrency/correctness bug that passed `-race` and every existing test (e.g. a single-writer or ownership violation) and you want a test that would have caught it. Do NOT use to check coverage against PRD acceptance criteria (use review-tests), to validate a list of already-identified bugs (use review-validate), or to fix the implementation (this skill writes the proving test and reports live violations loud; hand fixes to review-validate).

Write surface tests that exercise the system through its surface — the outermost layer consumers interact with (HTTP endpoints, CLI entry points, exported functions). Never test internal functions directly. Expose observability APIs when async behavior isn't visible at the surface.

Monitor and fix automated review comments (Copilot, SonarCloud) and CI failures on the current branch's PR. Gets the PR into a human-reviewable state autonomously. Use when the user says 'babysit this PR', 'fix CI', 'handle the automated reviews', or 'get this PR green'.

Detects bugs, logic errors, and edge case handling issues in code. Use when reviewing code for runtime errors, null/undefined handling, type errors, and edge cases. Returns structured bug reports with file paths, line numbers, and suggested fixes.

Validate reported bugs/issues via sub-agents, write surface tests proving each one, then present findings for review before fixing. Use when bugs have been identified (by bug-detector, code review, or discussion) and you want to confirm they're real, prove them with tests, and fix them safely. Trigger phrases include "validate these issues", "prove these bugs", "test and fix these", "validate and test", or "review-validate".

Record a single architecture decision as a numbered ADR. Use when the user says "record this as an ADR", "log this decision", "capture this as an ADR", or "create an ADR"; or when another skill has surfaced a decision at the end of a discussion and the user has approved turning it into an ADR; or when a significant architectural call has been made mid-implementation and the user wants it preserved.

Review code changes for undocumented behavioral/surface changes. Flags modifications to public interfaces, API contracts, or observable behavior that lack justification in an ADR, PRD, tech spec, or implementation plan. Use when the user asks to "check for breaking changes", "review surface changes", "audit behavioral changes", or "validate contract compliance".

Capture decisions, rationale, and context from the current conversation into a referenceable document

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".

Review GitHub pull request comments and address reviewer feedback. Use when the user says 'review PR comments', 'address PR feedback', or provides a GitHub PR URL.

Address // REVIEW annotations left in source files. Use when the user says 'fix review comments', 'address review comments', or when a file contains // REVIEW markers.

Review code changes for compliance with CLAUDE.md guidelines. Use when the user says 'review guidelines', 'check guidelines', or 'validate against guidelines'.

Present investigation evidence as markdown directly in chat. Shows commands run and their full output as copyable markdown. Use when the user says 'show work', 'show me the evidence', or 'give me the receipts'.