handoff

Scan the codebase for architectural friction and propose deepening opportunities as candidate cards, then interrogate the chosen one into a decision. Two entry points — proactive, when the user asks "improve the architecture" or "why is this codebase painful to work in"; reactive, when the debug skill's "3+ failed fixes = architectural problem" rule hands off here. Inherently T2/T3; the outcome is a decision plus a plan.

Use when starting any new feature or product request, before writing a plan or code — turns an idea into a short approved spec by surfacing the decisions that will hurt later. Depth scales with risk tier.

Use when encountering any bug, test failure, unexpected behavior, or performance regression — before proposing any fix. Root-cause discipline plus a feedback-loop method; applies at every tier.

Use when designing or improving a module's interface, deciding where a seam goes, making code more testable or navigable, or pinning down domain terminology. Provides the deep-module vocabulary other skills lean on.

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".

Use at the end of T3 work, after an incident/rollback, or when the user asks for a retro — turns what happened into recorded learnings that live in the repo (CHANGELOG entry, typed LEARNINGS.md entries, follow-up tasks, and — only with explicit user approval — new RULES).

Scaffold the handoff project-memory system into THIS repository (new or existing) — copies the template tree into .handoff/, then runs a guided discovery pass that drafts a real STATUS, MAP, TECH_STACK, and PRODUCT from the actual codebase and confirms with the user before saving. Use when the user says "set up handoff", "initialize handoff", "add project memory", or when a repo has no .handoff/ and the user wants one. Run once per repo.

Use when work is verified and ready to leave the machine — branch/PR/merge/deploy/smoke-check. Triggers on "ship it", "deploy", "merge the PR", "push this", "release", "go live", "cutover". Covers git hygiene, PR and merge discipline, deploy-target detection (Cloudflare Workers/Pages via wrangler, Vercel, Convex, Supabase), post-deploy smoke checks, and the T3 launch runbook with rollback criteria.

Use when building any T3 feature or bugfix, recommended for T2 on the affected path — write the failing test before the implementation, one behavior at a time, through public interfaces.

The operating pipeline for all development work — 6 phases (Brief, Plan, Build, Verify, Ship, Learn) with risk tiers that decide how much process a task gets. Use at the start of any development task to pick the tier and execution mode, when unsure whether a task needs a plan/tests/review, or when another skill needs the phase and tier vocabulary. This skill overrides any process embedded in other skills.

Use to exercise the running app in a real browser — after UI changes, before ship, or when the user asks to QA the site, smoke-test a branch, or check "does it actually work". Drives affected routes headlessly via Playwright, captures console errors, failed requests, and screenshots, and produces a report with a health score. Report-only — it finds bugs, it never fixes them.

Use when a task would flood the main context window — broad searches, verbose test/build output, 2+ independent parallel tasks, or an isolated large workstream. How to hand work to subagents well, and when not to.

Use for a full security audit — T3 verify gate (money, auth, user data, migrations), pre-launch check, or when the user asks to audit the codebase for vulnerabilities. Whole-repo depth — for quick diff-scoped checks of pending changes, use the built-in /security-review instead.

Use when about to claim work is complete, fixed, or passing — before committing, opening a PR, or telling the user it works. Requires running verification commands and confirming output first; evidence before assertions, always.

Use when a task is T2/T3 — before building a feature that spans multiple files or carries risk. Produces an implementation plan with exact files, complete code steps, and per-stage verification.