adrWrite an Architecture Decision Record: the forces, the options genuinely considered, the choice, and the consequences you are accepting. Also supersedes an earlier ADR.
backfill-testsAdd 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 silen
conventionsScan a repo once and cache its house style to `.plan/_conventions.md`, how APIs are defined, how components are structured, error handling, logging, config, naming, the existing test style, and which shared primitives already exist, each with real file:line evidence. Every other eng skill reads this
debugSystematically root-cause a bug instead of guessing at fixes. Reproduces the failure first, narrows the surface with evidence, forms explicit competing hypotheses and kills them one at a time, confirms the true cause by predicting and observing, then fixes the cause (not the symptom) and locks it wi
eng-flowRun the whole eng pipeline off the `.plan` doc's phase and track, pausing at a gate between each pass. Resumes wherever you left off.
eng-reviewEngineering-manager review of a `.plan` doc: architecture, edge cases, tests, performance, and consistency with how this codebase already builds things. Scores each and folds fixes back in.
executeBuild a fully-planned `.plan` ticket: failing tests first, implement to the acceptance criteria in house style, make them pass, then verify and log the work.
grillInterview you about a scope doc's open questions, then add its own, and write the answers into the doc's Decisions.
migratePlan and run a data or schema migration without losing data. Characterizes the real data first, picks a strategy, writes the rollback before the migration, and verifies with queries rather than hope.
pr-reviewStaff/principal-engineer review of a pull request, yours or someone else's. Takes a PR number, URL, branch, or the current branch, reads the commits and diff against the base, pulls extra context from GitHub via `gh` (PR description, CI, existing review threads) and the linked ticket from whichever
pr-walkthroughUnderstand a pull request you did not write, before you judge it. Takes a PR number, URL, or branch, pulls the author's stated intent and the linked ticket, then maps how the touched subsystem works TODAY on main so the diff is readable, names a "start here" file and a dependency-ordered reading pat
refactorPlan 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, v
researchInvestigate a question against primary sources and return a cited answer. Reads specs, RFCs, official docs, changelogs, and library source rather than blog posts and summaries, weighs each source by trust, and says plainly where the sources disagree or go silent. Every claim carries a link. Can be s
resolve-conflictsResolve git merge, rebase, or cherry-pick conflicts hunk by hunk, by tracing what each side was trying to do rather than by picking a side. Reads the commits behind both branches, keeps both intents where they are compatible, flags semantic conflicts that leave no markers, and finishes the operation
reviewFast 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, leftove
scopeExplore the codebase and turn a task into planning docs in `.plan/`, one per ticket, with real file:line touchpoints, a chosen track, and open questions. Front door of the eng pipeline.
shipLand finished work: review the diff, split it into atomic commits in the repo's style, push, and open a PR whose body comes from the `.plan` doc.
spikeTimeboxed investigation that ends in a recommendation: evaluate 2-4 approaches against this codebase's real constraints and pick one, with a confidence level.
tddTurn a reviewed `.plan` doc's acceptance criteria into a test contract: a unit-test spec plus a manual QA checklist. Specifies tests; does not write code.
understandAnswer a question about a codebase, or map an unfamiliar one, with real file:line evidence. Two modes, auto-detected: QUESTION mode ("how does auth refresh work?", "where is rate limiting enforced?") searches the whole codebase and delivers a sourced answer; MAP mode ("understand this repo", "explai