ai-skills

Add tests to existing untested code. Picks a target by risk, reads the code to understand what it actually does, matches the repo's test style, then writes characterization tests that lock in current behavior — covering happy path, edge cases, and error paths. Surfaces suspected bugs instead of silently encoding them. Standalone: does NOT touch `.plan` docs. Complements `/tdd`, which specs tests for NEW features; this covers code that already shipped without them. Use when a module has no tests, before refactoring risky code, or when hardening a legacy area. Triggers: "add tests for this", "backfill tests", "this has no tests", "cover this code", "characterization tests".

Plan and safely execute a behavior-preserving refactor. Establishes a test safety net first (runs existing tests green, adds characterization tests where coverage is thin), learns the house style, plans the change as small atomic steps, then executes step by step keeping tests green the whole way — verifying behavior never changed. Standalone: does NOT touch `.plan` docs. Use when reshaping existing code without changing what it does — reducing duplication, untangling coupling, renaming, extracting, restructuring. Triggers: "refactor this", "clean up this code", "untangle this", "extract this", "restructure this". NOT for behavior changes — that's a feature, use `/scope`.

Fast pre-commit review of your uncommitted working diff, in house style, before you commit. Reads staged + unstaged changes and new files, learns how the codebase already does things, and gives a high-signal gut-check: correctness, consistency with the codebase, obvious security/data issues, leftover debug/dead code, and missing tests — separating blocking issues from nits. Standalone: does NOT touch `.plan` docs. Distinct from `/pr-review` (whole branch vs main, with GitHub context) — this is the quick check on the working tree. Use right before committing. Triggers: "review my changes", "review the diff", "check this before I commit", "quick review", "review my working tree".

Map an unfamiliar codebase or subsystem before you touch it. Reads the repo's structure, entry points, and key paths, traces how data and control actually flow, and extracts the house conventions — then delivers an architecture map: what the major pieces are, how they fit, where to make a given change, and what looks risky. Standalone: does NOT touch `.plan` docs, but its output is the ideal warm-up before `/scope`. Use when onboarding to a new repo/job, picking up an unfamiliar area, or answering "how does this work?". Triggers: "understand this codebase", "map this repo", "how does this work", "explain this subsystem", "help me onboard".

Capture something you just learned into your Obsidian vault as a well-placed, well-written note in your own voice. Takes a spoken/typed brain-dump, figures out where it belongs in the Learn/ hierarchy, decides whether to create a new note or merge into an existing one, writes it in Nitin's note-taking voice (not AI voice), wires up wikilinks, and updates the parent index hub. Auto-detects two modes: verbatim (you dumped the full content) and expand (you gave a topic + a few points and want it written up). Use when the user says "I just learned X", "add this to my second brain", "note this down", "put this in obsidian", "capture this", or invokes /note.

Staff/principal-engineer review of a pull request. Reads the current branch's commits and diff against the main branch, pulls extra context from GitHub via `gh` (PR description, linked issues, CI, existing review threads), then reviews the change the way a senior reviewer actually does: correctness and edge cases first, then architecture, then — critically — consistency with how THIS codebase already builds things, so the code reads like the team wrote it. Standalone: does NOT touch `.plan` docs or the eng-flow pipeline. Use when the user wants a PR or branch reviewed before it lands. Triggers: "review this PR", "pr review", "review my branch", "review before I merge", "code review this".

Write a real Product Requirements Document at the bar a senior/staff engineer or PM would ship at a top org (Google, Meta, Amazon, Apple). Gathers context, grills the user on the gaps, then produces a rigorous PRD: crisp problem statement, measurable goals & explicit non-goals, success metrics with baseline→target, prioritized requirements (P0/P1/P2), user journeys, risks, dependencies, and a phased rollout. Standalone — its output can feed /scope but it is NOT in the eng doc schema. Use when the user wants a PRD, product spec, one-pager, or PR/FAQ. Triggers: "write a PRD", "product spec", "product requirements", "spec this out", "one-pager", "PR/FAQ".

Break a PRD, epic, or feature idea into well-formed user stories — "As a <persona>, I want <goal>, so that <benefit>" — each with clear, testable acceptance criteria (Gherkin given/when/then). Uses real personas when a personas skill is available, sizes stories to be independently shippable, and orders them. Output feeds /scope. Use when the user has a PRD/epic to slice or asks for user stories. Triggers: "user stories", "break into stories", "write stories for this", "slice this epic", "story map".

Summarize what changed so you can re-enter work fast. Given a branch, PR, commit range, file, or "since yesterday", it reads the diff/commits and produces a tight summary: what changed, why, risk areas, and what's left. Great for resuming after a break, reviewing what a teammate pushed, or before picking up a PR. Use when the user asks what changed or wants to get back up to speed. Triggers: "catch me up", "catchup", "what changed", "what did I miss", "summarize this branch/PR/diff", "since I last looked".

Standalone, relentless interview about a plan or design until you reach shared understanding, resolving each branch of the decision tree one at a time with a recommended answer for each. General-purpose — for any plan/design discussion, NOT tied to the eng pipeline's .plan docs (use eng's /grill for those). Use when the user wants to stress-test thinking or get grilled. Triggers: "grill me", "stress-test this plan", "poke holes in this", "interview me about this design".

Compact the current conversation into a handoff document for another agent to pick up. Use when the user wants to hand off work, end a session cleanly, or prep context for a fresh agent. Triggers: "handoff", "write a handoff", "hand this off", "prep for next session".

Orchestrator for the eng pipeline. Runs the five skills in order — scope → grill → eng-review → tdd → execute — driven entirely off the phase recorded in the .plan doc, pausing at a gate between each so the user stays in control. Picks up wherever the doc left off, so it's also "resume my planning flow". Use when the user wants to run the whole plan-to-ship pipeline rather than invoking skills one at a time. Triggers: "eng flow", "run the pipeline", "plan to ship", "take this from idea to code", "resume the flow".

Third pass of the eng pipeline. An engineering-manager review of a .plan doc: rates the plan across architecture, edge cases, test coverage, performance, and — critically — consistency with how THIS codebase already builds things (APIs, components, patterns), so the eventual code matches house style. Scores each dimension 0-10, explains what would make each a 10, and folds the fixes back into the doc. Use when a grilled .plan doc is ready for architectural review before defining tests. Triggers: "eng review", "review the plan", "review the architecture", "lock in the plan".

Final pass of the eng pipeline. Implements a fully-planned .plan ticket: writes the unit tests the doc specified (TDD — failing first), implements against the acceptance criteria following the repo's conventions, runs the tests until they pass, then verifies the acceptance criteria and walks the manual QA checklist. Updates the doc's Work Log and the README status. Use when a tested .plan doc is ready to build. Triggers: "execute", "implement this", "build this ticket", "do the work".

Second pass of the eng pipeline. Reads the Open Questions a scope doc already recorded, grills the user about them one batch at a time, then adds its own engineering and business questions to close remaining ambiguity — exploring the codebase a little more if it needs context. Writes answers into the doc's Decisions section and sharpens scope/acceptance criteria. Use when a .plan doc exists and needs its requirements nailed down. Triggers: "grill me", "ask me questions about this", "tighten the requirements", "resolve open questions".

Front door of the eng pipeline. Takes a task description, explores the codebase deeply, decides (with the user) whether it needs a Jira ticket and whether to split into one or many tickets, then writes a planning doc per ticket into the project's .plan folder — including real file:line touchpoints, house conventions, and open questions for the next step. Use when the user describes a feature/task and wants it scoped, broken down, or turned into Jira tickets. Triggers: "scope this", "break this down", "turn this into tickets", "plan this feature".

Fourth pass of the eng pipeline. Turns a reviewed .plan doc's acceptance criteria into a concrete test contract: a unit-test spec (what to test, edge cases, following the repo's existing test style) plus a manual/UI QA checklist a human runs after the feature is built. Specifies tests; does not write code — execute does that. Use when a reviewed .plan doc is ready to define tests before implementation. Triggers: "tdd", "define the tests", "write the test plan", "test cases for this".