hawk-skills

Plan a multi-PR feature, migration, or architectural change before writing code. Writes a `.plans/<slug>/` directory of HTML documents (with inline UI mockups and a review-tracking layer) — a 1-page `overview.html` for human review, a mandatory `data-model.html` that locks the schema before anything else, a terse `plan.html` of dependency-ordered increments, an ADR-style `decisions.html`, and a `verification.html` acceptance script. Use whenever the user says "plan this feature", "scope out the migration", "/plan-large", "architect this rollout", "I need a plan covering schema and API", "design this across multiple PRs", or "break this work up". Also use whenever the work touches a database migration, even if it's only two PRs — schema-first is the gate. Runs a blind self-review subagent before presenting. Do NOT use for single-PR changes — bail to `plan-small` at Step 0. Do NOT use to start implementing — that's `/implement-plan` after the plan is approved.

Plan a single-PR change end-to-end before writing code. Writes a terse `.plans/<slug>/plan.html` (HTML, with inline UI mockups where a screen changes, rendered through the shared design system) covering files to touch, data-model changes, edge cases, verification, and decisions/assumptions sourced to code or user. Use whenever the user says "plan this", "scope this out", "write up a plan for X", "/plan-small", "let's plan the new flag", or "plan before we start". Also use whenever the user describes a small feature without explicitly asking to plan — propose a plan before coding. Asks only what code can't answer (in-repo PRDs count), surfaces planned assumptions alongside questions, then runs a blind self-review subagent before presenting. Do NOT use for multi-PR work, schema migrations beyond adding a nullable column, or sequenced increments — bail to `plan-large` at Step 0. Do NOT use to start implementing — that's `/implement-plan` after the plan is approved.

Aggressive cleanup audit scoped to the user's specified changes plus tangibly-relevant surrounding code. Same blind audit-* specialists as code-audit, with a maximum-improvement posture — any code in the expanded review scope that can be cleaner WILL be made cleaner. Small fixes applied inline; big fixes (>5 files, schema, public API, redesigns) routed through `/plan-small` or `/plan-large`. Plan-overrides — when the audit reveals the original plan was wrong — route through `/plan-large` by default. Always improve over preserve.

Execute a plan increment-by-increment with the audit-* specialists running independently at strategic checkpoints. Use whenever the user says "implement the plan with audits", "audited implementation", "run with audits", "implement with cleanup checkpoints", "audit as you go", or invokes /implement-plan-audited. Inherits the full per-increment verification loop from `implement-plan` (done-criteria evidence, layered retry ladder, file-divergence check, outcome records) and adds checkpoint annotation, blind parallel audits, audit-fix verification (each FIX closes its own loop), plan-override propagation, and BEHAVIOR_CHANGE.md artifacts. Two modes — `manual` stops between increments for user review; `auto` applies audit fixes and proceeds without interruption, designed for hours of unattended execution. Specialists are blind to the plan and the goal. Do NOT use for unaudited plan execution — use `implement-plan`. Do NOT use for one-shot audits of existing code — use `code-audit`. Do NOT use for planning or repl

Execute an approved plan increment-by-increment with deterministic verification at each step. Use whenever the user says "implement the plan", "run the plan", "execute the plan", "work through the increments", "do the plan", or invokes /implement-plan. Done-criteria are checked against evidence on disk, not asserted from memory; failures escalate through a layered ladder rather than repeated identical attempts; existing code gets behavior-preservation tests before modification; file divergence (touched vs declared) is reconciled before each commit; structured outcome records land in the plan file. Designed for fresh sessions with no prior context. Do NOT use for planning itself — use `plan-small` or `plan-large`. Do NOT use for unplanned coding without a plan file — use `coding-process`. Do NOT use when the user wants audits in the loop — use `implement-plan-audited`.

Stress-test a plan file before committing to implementation. Catches architectural mistakes, convention violations, and missing dependencies while changes are still cheap. Invoked directly, not routed from coding-process.

Design or fix an LLM agent's system prompt, tools, and guardrails so it stays strictly inside its domain and only does what it can actually do. Use when building a new agent, writing a system prompt for a "<domain> agent", or when an existing agent misbehaves — drifting off-topic, answering like a general chatbot (e.g. a CRM that starts writing Python), claiming abilities it lacks, answering from memory instead of tools, or caving to off-scope requests. Triggers: "write a system prompt for X", "constrain this agent", "why is my agent answering off-topic", "add guardrails", "keep the agent in scope", "/write-agent". NOT for tuning a one-shot prompt/completion that isn't a tool-using agent, and NOT for general copywriting — that's prompt engineering, not agent scoping.

Audit code adversarially with parallel independent specialist subagents — logic bugs, security, simplification, online research, architecture. Each runs blind to the user's goal and the plan, so they evaluate code on its own merits, not by deferring to existing patterns. Use whenever the user says "audit this", "review my code", "do a code audit", "check this diff", "audit the cleanup", "review HEAD~3", or asks for a quality pass on a PR or specific files — even if the code "looks fine" and even if it just shipped. Also use as a post-implementation pass on your own work to surface lazy patches and cross-cutting issues. Supports report mode (default — emits FIX/NOTE/QUESTION and stops for approval) and cleanup mode (applies local FIXes, surfaces cross-cutting work). Do NOT use for full-repo restructural rewrites (use `code-audit-hardcore`), pre-merge PR review of someone else's work (use `review-large-pr`), plan critique (use `review-plan`), or prose review (use `human-prose`).

Audit a Claude Code skill (SKILL.md or skill directory) against the nine principles that determine whether skills work reliably: description triggering, HOW-not-WHAT operational teaching, decision boundaries over principles, evidence-on-disk verification, failure-mode enumeration, voice-matches-content, bundled-work delegation, right-sizing, and internal consistency. Produces a graded audit report with ranked improvements ordered worst-grade-first. Use whenever the user wants to "audit my skill," "evaluate this skill," "review my skill," "grade this skill," "is this skill good," "what's wrong with this skill," "improve my skill," "rate this skill," "check if my skill follows best practices," or pastes a SKILL.md file by path or content. Also use when the user is working on a skill and wants feedback on it, even if they don't explicitly say "audit." Do NOT use for prose audit (use human-prose), code review (use code-audit), plan review (use plan-reviewer), or general writing feedback unrelated to skills.

Fix a bug via hypothesis-first root cause analysis. Use whenever the user reports a symptom and wants the cause found and fixed — phrasings like "it's broken", "this crashes", "intermittent failure", "stack trace says X", "works locally but fails in prod", "regression after the last deploy", "this used to work", "flaky test", "off-by-one somewhere", or "investigate why Y is happening". Also use when only a vague observation is provided ("seems wrong", "weird output"). Generates 5 ranked hypotheses BEFORE reading code; always considers online research at the hypothesis stage. Three-branch hypothesis revision (disconfirmed → next; new evidence → rewind; all 5 exhausted → escalate, never invent a 6th). Requires a failing reproduction test before the fix and evidence-on-disk that it passes after. Layered retry ladder — Stage 3 explicitly considers that the fix itself was wrong and reverts. Lazy patches (swallow-the-exception, mask-the-symptom, comment-instead-of-fix) are rejected. Do NOT use for refactor requests

Write prose that doesn't read as AI-generated. Use whenever the user asks for help writing or revising an article, essay, blog post, short story, social post, newsletter, op-ed, cover letter, personal email, marketing copy, speech, LinkedIn post, Substack post, or any standalone prose, including casually phrased requests like "write me a quick post about X," "draft a blog post," "help me write this up," or "make this sound better." Also use whenever the user wants writing to feel "natural," "human," "less AI," "less like ChatGPT," "less formal," "less stiff," "more like me," or asks to remove AI tells, slop, or stiffness from existing text. Use for any prose-writing task by default, including short ones. Do NOT use for structured technical writing where formal register is correct (API documentation, legal contracts, scientific abstracts, formal reports, code comments). Those have their own conventions and shouldn't be casualized.

Refactor existing code without changing behavior. Use when the user wants to improve readability, modularity, performance, type safety, or reduce duplication.

Remove a feature, delete dead code, drop a dependency, or simplify an abstraction. Use when the user wants to delete or clean up code.

Initialize a full Phoenix project from an AI-scaffold repo. Generates Docker environment, Makefile, standards, and config with all BEAM/macOS/Docker gotchas pre-solved. Invoked directly, not routed from coding-process.

Review a large pull request (30+ changed files) using chunked parallel review with synthesis. Each chunk is audited by the audit-* specialists in parallel, then synthesized into one consolidated report. Use when a PR is too large for a single audit pass.

Stage all changes, commit with a short message that matches the repo's existing commit style, and push. Use when the user wants to ship the current diff with no fuss.

Entry point for all work. Identifies your task type and routes to the right workflow skill. Start here when beginning any task.

Explore and explain how a system, module, or codebase works. Use when the user is onboarding, trying to understand unfamiliar code, or building a mental model.

Design a master class design system. Use when the user wants to design a master class design system.