On invocation: announce \"Running paad:paad-help v1.31.0\" before anything else.
\nShow help for paad skills. If $ARGUMENTS matches a skill name, show detailed help for that skill. Otherwise, show the overview.
/paad-help — show all available skills/paad-help vibe — show detailed help for a specific skill/paad-help agentic-review — skill names with hyphens work tooIf $ARGUMENTS is provided and matches a skill name (with or without the paad: prefix), show the detailed help for that skill only. If the argument doesn't match any skill, say \"Unknown skill: [name]. Available skills:\" and show the overview.
Do NOT read files or run commands. All help text is below.
\n| Mistake | \nWhat to do instead | \n
|---|---|
| Paraphrasing or summarizing the help text | \nDisplay the blocks verbatim. Arguments and output paths are exact; a paraphrase invents flags that don't exist. | \n
| Answering for a skill not listed here | \nIf it isn't below, it isn't a paad skill. Say \"Unknown skill: [name]\" and show the overview. | \n
| Running the skill the user asked about | \nThey asked what it does, not for it to happen. Show the help and stop. | \n
When showing the overview, display exactly this:
\npaad — Engineering-driven AI.\nUse your engineering excellence — the one thing AI reliably skips.\n\nAvailable skills:\n\n /agentic-a11y [path] Accessibility audit (web, mobile, desktop, CLI, games)\n /agentic-architecture [path...] Multi-agent architecture analysis (strengths & flaws)\n /fix-architecture [report] Fix architectural flaws from an analysis report\n /agentic-review [base-branch] [path] Multi-agent code review of current branch (bug hunting)\n /alignment [files...] Requirements-to-tasks alignment + TDD rewrite\n /makefile Create or update a Makefile with standard targets\n /pushback [document] Spec/PRD/doc critic (finds issues before you build)\n /vibe [task description] Safe vibe coding with TDD guardrails\n\nExperimental — may change or be withdrawn in any release, including patches:\n\n /agentic-dedup [scope] Find semantic duplication (same meaning, different code)\n /agentic-owasp [scope] Security review against the OWASP Top 10:2025\n /handoff [save|resume] Hand this session's work to a fresh session, in writing\n /rethink [what to re-examine] Verify the premises under options already on the table\n /test-roadmap Plan and build a test suite that catches real regressions\n\nPicking between them:\n\n Want structural flaws found? agentic-architecture (diagnoses, does not fix)\n Want them fixed? fix-architecture (needs a report first)\n Want bugs in a branch? agentic-review (a diff, not the codebase)\n Want accessibility barriers? agentic-a11y (not general correctness)\n Want duplicated logic found? agentic-dedup (experimental; reports,\n never refactors)\n Worried about security specifically? agentic-owasp (experimental; the OWASP\n Top 10:2025, never exploits or fixes)\n Have no tests, or tests you distrust? test-roadmap (experimental; the only\n skill that writes and commits code)\n Have one document, is it any good? pushback (a spec, a steering file, a\n generated report)\n Been handed options, are they sound? rethink (experimental; checks premises,\n does not invent alternatives)\n Out of context, work unfinished? handoff (experimental; writes a file for\n a NEW session — /compact stays in this one)\n Have a spec AND a plan, do they match? alignment (needs both; does not read code)\n Making a small change? vibe (1-3 files, same module)\n Change is clearly multi-module? write a plan, then alignment against it\n Build is broken? none of these — makefile manages targets,\n it does not debug builds\n\nRun /paad-help <skill-name> for detailed help on a specific skill.\n\nInvoking: the names above are slash commands on Claude Code. If your\nassistant does not take them, ask for the skill by name (\"run the pushback\nskill\"). If another plugin ships a skill with the same name, disambiguate with\nthe paad: prefix — /paad:vibe rather than /vibe.\n/agentic-a11y [path]\n\nComprehensive multi-agent accessibility audit of user-facing code.\n\nSupports: web, iOS, Android, React Native, Flutter, desktop, CLI, and games.\nTarget: WCAG 2.2 AA baseline, AAA flagged as bonus recommendations.\nOutput: paad/a11y-reviews/\n\nArguments:\n /agentic-a11y Audit all user-facing code in the repo\n /agentic-a11y src/components/ Scope to a directory\n /agentic-a11y Modal.tsx Scope to a file\n\nWhat it does:\n 1. Detects the platform(s) automatically\n 2. Dispatches 5 specialist agents in parallel:\n - Screen Reader & Assistive Tech\n - Visual & Color\n - Keyboard & Motor\n - Cognitive & Learning\n - Multimedia & Temporal\n 3. Dispatches a Platform-Specific agent if a framework is detected\n 4. Verifies findings (filters false positives from component libraries)\n 5. Writes a report with:\n - Impact summary by user group\n - Issues ranked by severity (Critical/Serious/Moderate/Minor)\n - WCAG conformance checklist\n - Quick wins (top 5 highest-impact, lowest-effort fixes)\n\nBest used in a fresh session — consumes significant context.\n/agentic-architecture [path...]\n\nMulti-agent architecture analysis. Diagnosis only — finds strengths and\nflaws with evidence but does not propose fixes.\n\nOutput: paad/architecture-reviews/\n\nArguments:\n /agentic-architecture Full repo\n /agentic-architecture src/ Scope to a directory\n /agentic-architecture packages/api/ packages/shared/ Multiple dirs\n\nWhat it does:\n 1. Reconnaissance: repo overview, dependency snapshot, steering files\n 2. Dispatches 5 specialist agents in parallel:\n - Structure & Boundaries (god objects, cohesion, domain modeling)\n - Coupling & Dependencies (tight coupling, circular deps, abstractions)\n - Integration & Data (API contracts, data ownership, resilience)\n - Error Handling & Observability (error strategy, logging, config)\n - Security & Code Quality (auth, secrets, dead code, test coverage)\n 3. Verifies findings (reads actual code, checks git history)\n 4. Writes a report with:\n - 14 strength categories assessed\n - 34 flaw/risk types assessed\n - Coverage checklist (every category: observed / not observed / N/A)\n - Hotspots (top 3 files/directories to review)\n - Next questions (max 5, no solutions)\n\nBest used in a fresh session — consumes significant context.\n/fix-architecture [report]\n\nGuided fixing of architectural flaws from an agentic-architecture report.\nTest-first workflow with developer approval at every step.\n\nOutput: Updates the report in paad/architecture-reviews/ with fix status\n\nArguments:\n /fix-architecture Find most recent report\n /fix-architecture path/to/report.md Use a specific report\n\nRequirements:\n - Must be on a feature branch (not main/master/trunk)\n - An architecture report must exist (run /agentic-architecture first)\n\nWhat it does:\n 1. Pre-flight: branch check, report staleness, test infrastructure,\n baseline test run\n 2. Developer conversation:\n - Solo or team? (affects batch size recommendations)\n - Auto-commit or manual review?\n - Flaw triage: high-impact, quick wins, or specific F-IDs\n - Plan confirmation before any code is touched\n 3. For each selected flaw:\n - Validates the flaw still exists (checks code and git history)\n - Assesses test coverage, writes safety-net tests if needed\n - Proposes fix options with tradeoffs (recommended option first)\n - Executes with red/green/refactor\n - Handles test failures (distinguishes structural vs behavioral)\n - Commits (one per fix) and updates the report\n - Checks if the fix resolved other flaws too\n 4. Post-session summary with remaining flaw count\n\nStatus tracking in the report:\n Fixed | Won't fix | Partially fixed | Skipped |\n Fixed (pre-existing) | Attempted, reverted\n\nBest used in a fresh session — consumes significant context.\n/agentic-review [base-branch] [path]\n\nMulti-agent bug-hunting code review of the current branch.\n\nOutput: paad/code-reviews/<branch>-<timestamp>-<short-sha>.md (per-review)\n paad/code-reviews/backlog.md (project-wide, persistent)\n\nArguments:\n /agentic-review Diff against the default branch\n /agentic-review develop Diff against a different branch\n /agentic-review main src/auth/ Scope to a directory\n\n One argument is read as a base branch if git can resolve it, otherwise\n as a path if it exists on disk. If it is both -- \"docs\", \"release\",\n \"test\" and \"api\" are ordinary names for either -- the skill stops and\n asks rather than guessing.\n\nRequirements:\n - Must be on a feature branch (not the repository's default branch,\n resolved from origin/HEAD, falling back to main/master/trunk)\n - Uncommitted changes: asks whether to review the committed state or wait\n\nStops before reviewing when:\n - The base branch does not resolve\n - A path filter was given and does not exist\n - An argument is neither a ref nor a path, or is ambiguously both\n - An argument holds a character git could read as a flag\n - The default branch cannot be determined at all\n - The filtered diff is empty\n\nWhat it does:\n 1. Reconnaissance: diff stats, file manifest, callers/callees\n 2. Dispatches 6 specialist agents in parallel:\n - Logic & Correctness\n - Error Handling & Edge Cases\n - Contract & Integration\n - Concurrency & State\n - Security\n - Spec Compliance — pulls intent from PR description, plan/design\n docs, recent commits, or branch name; flags missing features,\n deviations, and out-of-scope additions (replaces the older\n Plan Alignment agent)\n 3. Verifies findings (reads actual code, filters false positives)\n 4. Classifies each finding as in-scope (this branch caused/worsened it),\n out-of-scope (pre-existing bug — persists to project-wide backlog),\n or out-of-scope-addition (this branch added it but the spec didn't\n promise it — flagged for per-PR user decision)\n 5. Writes a report with:\n - In-scope issues ranked: Critical / Important / Suggestion\n - Out-of-scope bugs batched by tier with handoff instructions\n - Out-of-scope additions in a separate section for keep/split/revert\n decisions (no backlog persistence)\n - Each finding: file:line, bug, impact, suggested fix, confidence,\n and the model that found it\n - Backlog updates surfaced in metadata\n\nBest used in a fresh session — consumes significant context.\n/alignment [files...]\n\nChecks that requirements and implementation plans are aligned.\nRewrites all tasks in TDD red/green/refactor format (mandatory).\n\nOutput: paad/alignment-reviews/\n\nArguments:\n /alignment Auto-detect documents\n /alignment requirements.md plan.md Specific files\n /alignment docs/specs/ docs/plans/ Directories\n\nAuto-detection scans: .kiro/, specs/ (spec-kit), docs/plans/, docs/specs/,\ncommon filenames, and conversation history.\n\nWhat it does:\n 1. Classifies documents as intent (requirements) vs action (tasks)\n 2. Reality check: scans git history for conflicts\n 3. Three alignment checks:\n - Requirements coverage (every requirement has tasks?)\n - Scope compliance (every task maps to a requirement?)\n - Design alignment (if design docs exist)\n 4. Presents issues one at a time, dependency-ordered:\n - Missing requirements first (root causes)\n - Design gaps second\n - Missing/orphaned tasks last (symptoms)\n 5. Rewrites all tasks in red/green/refactor format\n 6. Updates documents or writes a separate report\n\nWorks within an existing conversation — no fresh session needed.\n/makefile\n\nCreates or updates a project Makefile with standard targets.\n\nArguments:\n /makefile Create a new Makefile or update an existing one\n\nWhat it does:\n 1. Detects your stack (reads CLAUDE.md, README, package.json, etc.)\n 2. Checks if a Makefile already exists\n 3. Creating: builds from scratch with all required targets\n 4. Updating: adds missing targets; asks before changing existing ones\n\nRequired targets (always included):\n help List all targets with descriptions\n all Full CI pass (lint + format + test)\n test Run test suite\n cover One-shot coverage report\n lint Lint (with autofix if available)\n format Format code\n\nExtra targets (build, dev, preview, etc.) added only if the project\nsupports them.\n\nKey rules:\n - Never modifies an existing target without explicit approval\n - Forces one-shot mode for coverage (no watch-mode hanging)\n - Uses self-documenting pattern (## comments + grep/awk help target)\n - Balanced test output: concise on success, detailed on failure\n\nNo fresh session needed — this is a lightweight workflow skill.\n/pushback [document]\n\nCritically reviews a spec, PRD, or design before you start building —\nor any document that makes claims about the code, such as an agent\nsteering file (CLAUDE.md, AGENTS.md) or a generated analysis report.\nEvery finding must name a concrete consequence and the mechanism behind\nit; candidates that can't are dropped and reported as discards. Each\nfinding also names the off-disk fact that would change its severity —\nor says it is unconditional.\n\nOutput: the conversation, plus your spec if you ask for edits.\n Writes paad/pushback-reviews/ only when issues go undiscussed\n or you ask for a report.\n\nArguments:\n /pushback path/to/spec.md Review a specific file\n /pushback Auto-detect from conversation or files\n\nAuto-detection checks: conversation history first, then common locations\n(docs/plans/, docs/specs/, requirements.md, PRD.md, spec.md), then agent\nsteering files (CLAUDE.md, AGENTS.md, .cursorrules, .kiro/steering/,\n.github/copilot-instructions.md) and generated analysis (paad/*-reviews/).\n\nWhat it does:\n 1. Reality check: scans git history for conflicts with what the\n spec assumes (presented upfront — showstoppers first)\n 2. Scope shape check:\n - Feature cohesion: flags unrelated features bundled together\n (things that would be separate PRs)\n - Spec size: flags oversized specs, suggests splits only when\n each piece delivers independent value\n 3. Analyzes the spec across 6 categories:\n - Contradictions\n - Feasibility (given the current codebase)\n - Scope imbalance\n - Omissions\n - Ambiguity\n - Security concerns\n 4. Presents issues one at a time, most impactful first\n 5. For each: concrete options from best to worst, with recommendation\n 6. Stop when you say \"good enough\"\n 7. Updates the spec or writes a separate report\n\nWorks within an existing conversation — no fresh session needed.\n/rethink [what to re-examine] EXPERIMENTAL\n\nIndependently verifies the premises under options that are already on\nthe table. Reports what it checked, and how it checked it.\n\nExperimental: arguments, verdicts, and output shape may change — or the\nskill may be withdrawn — in any release, including a patch release.\n\nOutput: none — it speaks in the conversation and writes no files.\n\nArguments:\n /rethink Re-examine the most recent option set\n /rethink the caching approach Name which decision, if several are live\n\nWhat it does:\n 1. Extracts every premise the recommendation depends on, including\n the unstated ones, and sorts them:\n - checkable now (a primary source exists)\n - checkable by experiment (names the cheapest one)\n - not checkable (judgment, taste, prediction)\n 2. Dispatches one read-only subagent to verify them against\n PRIMARY sources — the software, not its documentation\n 3. Reports one of five verdicts:\n - Sound premises hold, and were checked\n - Lucky premises hold, but nobody checked them\n - Wrong reason a premise is false, the conclusion survives\n - Premise false a premise is false, the conclusion does not\n - Ungrounded unsettleable; names the experiment that would settle it\n 4. Per premise: what was claimed, what was found, what was checked\n 5. Re-presents the options in plain language — no jargon, no internal\n names — with pros AND cons for each, and says what verification\n changed about their standing\n 6. Recommends one, with the reason. Where the call also turns on\n something it cannot see — a deadline, headcount, an unshipped\n roadmap — it still recommends, then names that input and what it\n would flip the answer to. It withholds entirely only when the\n evidence supports no default at all\n\nWhat it deliberately does NOT do:\n - Produce an option list. It is not pushback. It proposes an\n alternative only when verification exposed a defect, and then\n exactly one, tied to that defect.\n - Write, edit, or create any file.\n\nUse it when a choice rests on cited docs, remembered behavior, or\npremises nobody tested. Not for critiquing a spec — that is pushback.\n/vibe [task description]\n\nSafe vibe coding. Quick fixes with TDD guardrails.\n\nArguments:\n /vibe fix the login timeout Task description inline\n /vibe Ask what needs fixing\n\nWhat it does:\n 1. Understands the task (asks clarifying questions if needed)\n 2. Pre-flight checks:\n - Test infrastructure exists?\n - Scope check (4+ files = warning)\n - Architecture smell (simple task but hard work = investigate)\n - Reusable components (search before building from scratch)\n 3. Implements with mandatory red/green/refactor:\n - RED: one failing test first — a new one, or an existing test\n updated to the new expectation (stop if unexpected behavior)\n - GREEN: write minimal code to pass\n - REFACTOR: clean up duplication, hard-coded values, patterns\n 4. Post-fix summary with contextual follow-up suggestions:\n - Security-sensitive code → /agentic-review\n - UI changes → /agentic-a11y\n - Harder than expected → /agentic-architecture\n\nNo fresh session needed — this is a lightweight workflow skill.\n/agentic-dedup [scope]\n\nEXPERIMENTAL — arguments, output paths, and behavior may change or be\nwithdrawn in any release, including patch releases.\n\nMulti-agent hunt for semantic duplication: code that means the same thing\nbehind different names, different syntax, different control flow, or\nindependently evolved implementations. Not a syntactic clone detector.\n\nOutput: paad/dedup-reviews/<branch-or-scope>-<timestamp>-<sha>.md\n paad/dedup-reviews/INDEX.md (persistent, newest run on top)\n\nArguments:\n /agentic-dedup Scan the repository\n /agentic-dedup src/auth/ Scope to a path or module\n /agentic-dedup --changed main Seed from the diff against main\n /agentic-dedup --type-constraints Schemas, type aliases, validators\n /agentic-dedup --domain \"payments\" Scope to a domain term\n\nWhat it does:\n 1. Reconnaissance: manifest grouped by semantic domain, not by extension\n 2. Candidate discovery via six strategies: name/concept search,\n behavioral fingerprints, type & constraint equivalence, control-flow\n normalization, tests as behavioral specs, canonical utility search\n 3. Dispatches 5 specialist agents in parallel:\n - Semantic Equivalence\n - Type & Constraint Equivalence\n - Domain Boundary & Intent\n - Divergence Risk\n - Refactoring Safety\n 4. Verifies findings — rejects name-only, shape-only, and structural\n matches, and anything where duplication is the safer choice\n 5. Writes a report with:\n - Findings ranked Critical / Important / Suggestion\n - Type and constraint equivalence table (exact/overlap/subset/drift)\n - Rejected candidates, so the next run does not rediscover them\n - A consolidation strategy with a safe migration sequence\n\nNever refactors anything. The report is the deliverable.\n\nBest used in a fresh session — consumes significant context.\n/agentic-owasp [scope]\n\nEXPERIMENTAL — arguments, output paths, and behavior may change or be\nwithdrawn in any release, including patch releases.\n\nMulti-agent security review of source code against the OWASP Top 10:2025.\nReads code. Never starts the app, never sends a request anywhere, never\nwrites exploit code, never fixes what it finds.\n\nOutput: paad/owasp-reviews/<branch-or-scope>-<timestamp>-<sha>.md\n paad/owasp-reviews/INDEX.md (persistent, newest run on top)\n\nArguments:\n /agentic-owasp Review the repository\n /agentic-owasp src/api/ Scope to a path or module\n /agentic-owasp --changed main Seed from the diff against main\n /agentic-owasp --category A01 One category, or A01,A05,A07\n /agentic-owasp --deps Supply chain only: deps, CI/CD\n\nWhat it does:\n 1. Reconnaissance: framework defaults first — the ORM, template engine,\n and middleware decide which findings are even real\n 2. Attack surface mapping: untrusted sources, dangerous sinks, and the\n controls already sitting between them, each with path:line.\n Then, before specialists launch, an optional benign-execution offer:\n with your explicit yes, specialists may run read-only in-process\n probes — your existing tests, a deparse, a pure-function call on\n ordinary input — to settle questions reading cannot. Never a payload,\n never a server or network, never a write; a separate decision from the\n proof stage below, and off unless you say yes\n 3. Dispatches 7 specialist agents in parallel. Six cover all ten\n categories with none left over:\n - Access Control & Authentication (A01, A07)\n - Injection & Untrusted Input (A05)\n - Cryptography & Data Protection (A04)\n - Configuration & Supply Chain (A02, A03)\n - Design, Integrity & Failure Modes (A06, A08, A10)\n - Logging, Alerting & Detection (A09)\n The seventh owns no category and hunts by mechanism instead:\n - Mechanism & Round-Trip (the seams)\n Round-trip asymmetry between paired APIs, and facts the code\n stores twice where a control reads only one copy. Files its\n findings under the category of the impact.\n 4. Exploitability gate: a finding must name an attacker-controlled\n source, a traced path to the sink, and why the existing controls do\n not hold. Anything that cannot becomes a hardening note or is rejected.\n The verifier's job is to refute, not confirm, and it clears a control\n by enumerating the callers that bypass it — not by reading where the\n control lives, and it composes across specialists before rejecting —\n each specialist reports out-of-category observations as fragments, so a\n weakness split across two categories is not lost by both\n 5. Optional proof stage: where a sink is reachable in-process, offers to\n write a standalone script per finding that exits 0 while the weakness\n is open, worked down the severity order rather than by whichever\n proof looks easiest. Always asks first, with the trade-offs; never\n executes without a yes. Declining costs nothing — unproven findings\n keep their severity, and each says why it went unproven\n 6. Writes a report with:\n - Coverage table across all ten categories — \"not assessed\" is\n stated, never passed off as clean\n - Findings ranked Critical / High / Medium, hardening notes separate\n - Dependency findings marked called vs present-but-unreachable\n - Every pooled fragment listed individually — path:line, what the\n specialist saw, where it ended up — not just a count, so a sink\n that was seen and dropped stays distinguishable from one nobody\n looked at once the session is gone\n - Rejected candidates, each with the positive evidence that killed\n it, so the next run does not rediscover them\n - A remediation order, which is not severity order\n\nLive credentials are reported by location and type only — never by value,\nand rotation comes before anything else in the report.\n\nNo report is a complete list of the weaknesses in the code, and the skill\nsays so at the end of every run — along with why committing the report is\nrisky even after the findings are fixed: git history is permanent, the\nreport ages into a false clearance, and the caveats do not travel with the\nseverity table. Zero findings means one reviewer looked once inside ten\ncategories and could not prove a path — not that the code is secure. Two\nruns find different things, and the larger the codebase the wider the gap,\nso union two runs rather than diffing them. Severity states impact;\nwhether a finding was executed is a separate field and never lowers it.\n\nScope is gated on size. Past roughly 40 source files the skill stops and\noffers a choice: narrow to the untrusted-input surface, split into separate\nsubsystem passes, or take one wide pass with the dilution recorded in the\nreport. Breadth costs depth, and it costs it silently — a wide run returns a\ndifferent result rather than a shallower one, often reporting more findings\noverall while missing a weakness a narrow pass over the same file finds\nevery time. Prefer several scoped runs to one repository-wide sweep.\n\nBest used in a fresh session — consumes significant context.\n/test-roadmap\n\nEXPERIMENTAL — arguments, output paths, and behavior may change or be\nwithdrawn in any release, including patch releases. This is the only paad\nskill that writes and commits code.\n\nBuilds a test suite that catches real regressions, in phases, across as\nmany sessions as it takes. One command on day 1 and on day 90.\n\nRun it once to get a roadmap, then KEEP RUNNING IT — one phase of tests\nper run — until it tells you the roadmap is finished. A 14-phase roadmap\ntakes 15 invocations. Running it once leaves you with a plan and no\ntests.\n\nOutput: paad/test-roadmap/test-roadmap.md (the roadmap, and the memory)\n Tests, committed one phase per commit, on your working branch\n\nArguments:\n /test-roadmap No arguments — the roadmap file decides the mode\n\nRequirements:\n - A git checkout (bug injection runs in a disposable git worktree)\n - A working branch, not main/master/trunk — it offers to make one\n\nWhat it does:\n Routing is one check: does paad/test-roadmap/test-roadmap.md exist?\n\n Absent → BUILD mode, five stages:\n 1. Detect — stack, test runner, and existing tests from manifests,\n never from a hardcoded language list\n 2. Grade — fan-out subagents grade existing tests for weakness and\n classify mocks (see the test-theater catalog)\n 3. Plan — phases, each naming the bug it would catch\n 4. Critique — a phase that cannot name its bug is coverage theater\n and gets rewritten or dropped\n 5. Write — the roadmap, including the decisions you settled\n\n Present → EXECUTE mode, one phase per run:\n - Writes that phase's tests\n - break-it-check: injects the very bug the phase claims to catch,\n in a throwaway worktree, and confirms the test goes red\n - Runs your whole suite, once normally and once under coverage;\n will not call a phase done while the run is noisy\n - Commits the phase and marks it done\n - Ends by telling you where you are (Phase 8 of 14 — 7 done, 6 to\n go) and to run it again, until no phases remain\n\n Logs concrete bugs it finds along the way. It never fixes them.\n\nBest used in a fresh session — consumes significant context.\n/handoff [save|resume] EXPERIMENTAL\n\nWrites a handoff.md that lets a FRESH session continue this one's\nwork, and reads it back on the other side.\n\nExperimental: arguments, file format, and behavior may change — or the\nskill may be withdrawn — in any release, including a patch release.\n\nOutput: handoff.md in the working directory. Suggests you gitignore it.\n\nArguments:\n /handoff Infer: history above → save, empty session → resume\n /handoff save Write a handoff regardless\n /handoff resume Read the existing handoff regardless\n\nWhy not just /compact:\n /compact summarizes and keeps working — same session, and the\n summary is machine-written, unreviewed, and buried in\n the transcript where you cannot edit it\n --resume restores the whole prior conversation, re-paying the\n context cost you were escaping\n /clear genuinely fresh, carries nothing forward\n handoff a file a human reads and corrects BEFORE anything is\n built on it\n\n That review is the only thing it adds. A handoff nobody reads is a\n worse /compact.\n\nSaving:\n 1. Checks .gitignore for handoff.md and suggests adding it —\n never edits .gitignore itself\n 2. Verifies with tools what agents get wrong from memory:\n commit and branch, what is really IN the last commit (not what\n its message claims), file paths, line numbers, test names,\n whether the suite passes. Unsettleable claims are marked\n inferred, not asserted\n 3. Writes the file: goal and what done looks like, decisions and\n why, approaches ruled out and how far they got, constraints the\n user stated, the next step, the verify command\n NOT: architecture tours, session narrative, anything git diff\n already shows — padding makes the file too long to review\n 4. Names the two or three claims it is least sure of, instead of a\n generic \"review this, AI makes mistakes\"\n\nResuming:\n 1. Reads handoff.md, summarizes it in a few lines\n 2. Compares the recorded commit against HEAD and reports drift\n 3. Asks before proceeding\n 4. Confirms the files and state it names still exist, reports every\n mismatch, asks again\n 5. Then starts the recorded next step\n\n Never deletes handoff.md — it is untracked, so git cannot restore\n it. The next save overwrites it.\n