skills

Write documentation someone will actually read — READMEs, guides, API references, runbooks — short, scannable, example-first, and verified against the code. Trigger on "write docs", "document this", "write a README", "explain how to use this", "our docs are too long/confusing", or a doc that needs rewriting for humans.

Review a diff, branch, or PR for correctness bugs, security issues, and simplification opportunities; findings to docs/<feature-name>/REVIEW.md. Trigger on "review this", "code review", "security review", "audit this", or after something is implemented and needs checking before merge.

Write docs/<feature-name>/PLAN.md with phased, checkbox-driven steps for a feature, refactor, upgrade, or infrastructure change. Trigger on "create/make a plan", "plan this feature/refactor/upgrade", any request to document steps before coding, and proactively when complexity warrants a written plan.

Decide a feature's shape before planning — system design, data model, API contract, UI/UX, whichever apply — and write docs/<feature-name>/DESIGN.md. Trigger on "design this feature/API/schema/UI", "how should we structure this", or between dev-research and dev-create-plan.

Execute an implementation plan from docs/<feature-name>/PLAN.md — tick checkboxes, commit each phase. Trigger on "implement/execute/continue/resume the plan", "start phase 1", "go" right after a plan was created, or whenever there is a PLAN.md to build, even if the user never says "plan".

Run an autonomous plan → implement → review loop for a feature, iterating until the code review passes and pausing for approval before pushing. Use on "loop on this", "keep going until it passes review", "autonomous dev loop", "plan implement and review", or a self-correcting agent workflow.

Repo-wide over-engineering scan — the whole tree instead of a diff, ranked by what to delete, simplify, or replace with a stdlib/native equivalent. Use on "audit this codebase", "audit for over-engineering", "what can I delete from this repo", "find the bloat", "where is this over-built". Reports; applies nothing.

Harvest every `TODO`/`FIXME` marker into one ledger with ceiling, trigger, owner, and age, flagging the ones that name no trigger. Use on "ponytail debt", "yagni debt", "what did we defer", "list the shortcuts", "collect the TODOs", "TODO ledger". Reports; changes no code.

Analyse test coverage, identify untested paths, write the missing tests (unit, integration, e2e), and produce a QA report. Use on "QA this", "write tests", "improve test coverage", "add tests for", "test this feature", "what's not tested", or a quality gate before release.

Answer one scoped question before code is written — a third-party API contract, a library capability, a doc lookup, or which approach to take — verified with spikes and web/doc lookups, written to docs/<feature-name>/RESEARCH.md. Trigger on "research/investigate/spike this", "explore options", "which library should we use".

Review a PLAN.md before implementation — vague tasks, missing completion criteria, risky assumptions, wrong phase ordering, scope issues — to docs/<feature-name>/PLAN-REVIEW.md with a verdict. Use on "review the plan", "check the plan", "is this plan ready", "validate the plan".

Build a clickable UI prototype as one self-contained HTML file (inline CSS, no build step, no framework) at docs/<feature-name>/prototype.html, opened straight in a browser. Trigger on "prototype this UI", "mock up this screen", "show me what this would look like", or wanting to click through a layout first.

Map a large, ambiguous project into a decision graph before planning — open questions resolved one ticket at a time in docs/<feature-name>/MAP.md until a PLAN.md is finally possible. Trigger on "this is too big to plan", "I don't know where to start", "chart this out", "map this project", "what do we need to decide first", or a request too undecided to phase.

Safety rules for destructive/history-rewriting git ops (force push, reset --hard, clean -f, branch -D, checkout over uncommitted changes, rebase/amend of pushed work) plus this repo's canonical commit hygiene. Trigger before any such command, or before any skill runs `git commit`.

REST/GraphQL design — resource/URL shape, pagination, versioning, HATEOAS, localization, GraphQL schema-first/DataLoader/Relay. Trigger on "design this API", "REST or GraphQL", "version/localize this API", "review this API design". For the OpenAPI document itself, use `openapi-spec`.

Ultra-compressed output. Drop articles, filler, pleasantries, hedging, and tool-call narration; keep every technical fact, exact symbol, and error string. Use on "caveman", "caveman mode", "be brief", "be terse", "less tokens", "stop explaining", "shorter answers", or when responses run too long.

Housekeeping — delete merged local and remote branches, prune stale tracking refs, close resolved GitHub issues, remove leftover worktrees. Use on "clean up", "prune branches", "remove merged branches", "close issues", "tidy up", "housekeeping".

Systematically debug a failing test, error, or unexpected behavior — reproduce, isolate root cause, fix minimally, verify. Use on "debug", "fix this bug", "it's broken", "this is failing", "why is this happening", or a shared error message, stack trace, or failing test output.

Write and maintain Playwright end-to-end tests that drive the whole system through its real UI/API — setup, fixtures, test independence, flake handling, CI wiring. Trigger on "write e2e tests", "set up Playwright", "test the full user flow", "our e2e tests are flaky", or when tests/e2e needs work.

Profile, optimize, and benchmark performance — measure baseline first, find the real bottleneck, optimize one thing at a time, prove it with numbers. Use on "it's slow", "optimize this", "improve performance", "reduce latency", "profile this", or shared timing/benchmark output.

Review a diff or branch for over-engineering only — reinvented stdlib, dependencies the platform covers, one-implementation abstractions, dead flexibility, code that shrinks. Use on "review for over-engineering", "is this over-engineered", "what can we delete", "simplify review". Correctness, security, and performance stay with `dev-code-review`.

Build the smallest thing that works — question whether the code needs to exist, reuse what the repo has, stdlib over a dependency, native platform over a library, one line over fifty. Use on any coding task, and on "ponytail", "be lazy", "yagni", "keep it simple", "minimal solution", "don't over-engineer", or complaints about bloat, boilerplate, or dependencies. Not for prose or research.

Refactor existing code without changing behavior — extract functions, reduce duplication, simplify logic, improve naming, against a test baseline taken before and verified after. Use on "refactor this", "clean up", "simplify", "extract", "reduce duplication", "improve naming", or a request for structural improvement without new features.

Cut a release — derive the version bump from conventional commits since the last tag, generate a changelog, bump version files, tag, publish a GitHub release. Use on "release", "cut a release", "ship it", "tag a version", "bump the version", "publish a release", "generate a changelog".

Write and run smoke tests — thin one-check-per-file scripts under scripts/test-<check-name>.sh|py that answer "is the build/deploy alive" in one command instead of clicking around by hand. Not a CI gate, not regression coverage. Trigger on "smoke test", "sanity check this deploy", "is the build healthy", "quick check this is working".

Test-driven development — the red → green loop, done so the resulting tests are worth keeping. Use when building a feature or fixing a bug test-first, or on "red-green-refactor", "TDD", or integration tests that survive refactors.

Brainstorm any idea — feature, name, business, creative direction — as an interactive back-and-forth partner, not a one-shot list dump. Trigger on "let's brainstorm", "I need ideas for X", "what are some ways to...", "I'm stuck on...", "help me name/pitch this", or an open-ended idea.

Create/review GitHub Actions workflows — CI, release pipelines, reusable workflows, composite actions, matrix builds, caching, security hardening (least-privilege permissions, pinned SHAs). Trigger on "set up CI", "add a GitHub Actions workflow", or editing `.github/workflows/*.yml`.

Generate Mermaid diagrams (flowchart, sequence, architecture, deployment, class, state, ER) from a description or source code, with high-contrast styling and syntax validation. Trigger on "create/generate a diagram", "document this architecture", "diagram this code/workflow", or a doc needing an embedded diagram.

Write and validate OpenAPI 3.1 spec documents (no code generation) — $ref-based components, Spectral/Redocly lint rules. Trigger on "write an OpenAPI spec", "generate a Swagger doc", "validate my openapi.yaml", or editing a spec file. Shape or versioning not decided yet? Use `dev-api-design`.

Build a throwaway prototype in the real codebase to answer one design question before production code — does this state model hold up, what should this screen look like. Trigger on "prototype this", "spike this", "quick prototype", "throwaway version", "let me try a few variants first". Not `dev-ui-design` (a standalone HTML mockup) or `dev-research` (verifying an approach).