ramstack 0.1.0

package/skills/poteto-mode/playbooks/prototype.md

@@ -0,0 +1,14 @@
+### Prototype
+
+**You own the design decision, not the code. The prototype is a throwaway instrument; the real build follows Feature.** For "prototype", "mock it up", "sketch this", "try this layout", or exploring a UI, interaction, or layout before committing. Also for settling an empirical fork (which behavior, which timing, which approach) by observing it run, when you would otherwise ask the human a question a quick sketch could answer for you.
+
+The one playbook where the Laziness Protocol's "smallest change" and the verification bar invert. Speed over polish, code quality does not matter, no planning. The rigor is in picking the right design cheaply. Be bold: propose variations the user didn't ask for, throw an approach away and try another.
+
+1. Scope the decision the prototype exists to make: which layout, which interaction, which density, or for an empirical fork which behavior, timing, or approach. No decision means no prototype; route to Feature.
+2. Gather references when the design space is open. Search for prior art, summarize a moodboard of themes, palettes, and layouts, let the user pick directions before building. Skip when the direction is set.
+3. Build throwaway in an isolated scratch dir, separate from production source. For a visual decision, vanilla HTML/CSS/JS or the lightest stack that renders the idea, CDN deps, a dev server with hot reload. For a behavioral or timing decision, the smallest script that exercises the question. No production framework, no tests, no abstractions.
+4. When comparing alternatives, build them behind one switcher (buttons or a keypress), each variant labeled so the user can name it. This is the **exhaust-the-design-space** principle skill made cheap.
+5. Verify on the matching surface. For a visual decision, screenshot each variant via the control skill and drive the interaction; the eye is the test. For a behavioral or timing decision, observe the thing you are deciding by logging the timing, printing the output, or watching the render. The observation is the test here, not an assertion.
+6. Present alternatives, tradeoffs, and a recommendation. The output is the decision plus the throwaway artifact, not shippable code. Hand the chosen direction to **Feature** (or `architect` for the shape) for the real build.
+
+**Reply:** the variants explored, the evidence (screenshots for a visual decision, the observed output or timing for a behavioral one), tradeoffs, your recommendation, and the scratch path. Say plainly that the prototype is throwaway.

package/skills/poteto-mode/playbooks/refactoring.md

@@ -0,0 +1,16 @@
+### Refactoring
+
+**You own the contract. The structure changes; the behavior does not.** For "refactor", "rename", "extract", "inline", "dedupe", "restructure", "move this module", "tidy up this area". Distinct from Feature, which adds behavior, and Bug fix, which corrects it.
+
+A refactor that smuggles in a behavior change loses its safety net. If the cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature. Large or cross-cutting structural work (a migration across many call sites, a coordinated reshape of many subsystems) belongs to the **figure-it-out** skill; this playbook is the focused-to-medium change.
+
+1. Pin the behavior contract first. Run the **how** skill over the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. The harness makes "refactor" a checkable claim (**principle-prove-it-works**). If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin.
+2. Name the structure the code is missing per **principle-model-the-domain**: a state machine over scattered booleans, a table or registry over spread-out branching, a typed model over repeated shape assumptions, a reducer over ad hoc mutations. Boring code stays when the shape is already clear and local; the reshape must delete branches or invalid states, not add indirection.
+3. Name the target shape. State what the module layout, types, and call graph should be if built today (**principle-foundational-thinking**, **principle-redesign-from-first-principles**). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move.
+4. Subtract before you add. Delete dead weight, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (**principle-subtract-before-you-add**). The smallest change that reaches the target shape ships (**principle-laziness-protocol**). A speculative cleanup that "might help" gets reverted, not left to ride.
+5. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (**principle-migrate-callers-then-delete-legacy-apis**). No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files; renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a subagent using your configured refactoring model (default `sonnet`) with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself.
+6. Prove behavior is unchanged on the real artifact, not "it compiles" (**principle-prove-it-works**). For larger reshapes, run an equivalence check: a script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant control skill. Own the verification yourself; do not trust a delegate's "looks good" summary.
+7. Confirm the change earns its place. The success measure is reduced reader load (**principle-minimize-reader-load**): fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. If the diff does not lower reader load somewhere, revert it.
+8. Rebase into small ordered commits that tell the story. A subtraction commit, then the reshape, then any follow-on cleanup, so a single revert undoes one slice. Shape them with the **sequence-verifiable-units** principle skill, so each behavior-preserving slice stays green before the next. Run **Opening a PR**.
+
+**Reply:** the structure that changed, the pin you held it against, the equivalence proof, the reader-load delta, what shipped and what got reverted. No new behavior.

package/skills/poteto-mode/playbooks/runtime-forensics.md

@@ -0,0 +1,11 @@
+### Runtime forensics
+
+**You own the diagnosis. Instrument the live process, don't theorize from source.** For "why is X leaking / spinning / slow at runtime", heap snapshots, idle-but-busy processes, intermittent glitches. The deliverable is a cited diagnosis, not a fix.
+
+1. Capture the live signal on the matching surface via the control skill: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP trace for a visual glitch. A real artifact, not a guess.
+2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread.
+3. Prove the mechanism before believing it. Inject instrumentation via CDP eval on the running process, or hotfix the live code without reloading, to confirm the hypothesis cheaply. A plausible-but-unconfirmed cause can be wrong while the real one sits one layer over.
+4. Map the finding back to source: file, symbol, the line that allocates or schedules.
+5. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`.
+
+**Reply:** the signal captured, the reduced finding, how you proved the mechanism, the source location, artifact paths. No fix unless asked; hand back to Bug fix or Perf once the cause is known.

package/skills/poteto-mode/playbooks/session-pickup.md

@@ -0,0 +1,13 @@
+### Session pickup
+
+**You own the resume point. Read the prior trail, don't redo it.** For "take over this", "resume this conversation", "continue from <transcript path>", "you're taking over", "pick up where X left off", a cloud-agent URL handoff, or a pushed branch you're meant to continue.
+
+A pickup is inheritance. The prior agent already paid the cost of reading the code, running the repros, making the design choices. Redoing loses the bias check and burns context. Resist the urge to re-derive; read.
+
+1. Locate the prior trail. A local transcript in the workspace's transcript directory (Claude Code: `~/.claude/projects/<slug>/`; Codex: `~/.codex/sessions/`; do not glob across other projects' directories, that crosses workspace boundaries and reads private chats from unrelated projects), a cloud-agent URL, or a pushed branch. Read the metadata overview and last messages first, then scan back for the decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread (the **principle-guard-the-context-window** skill).
+2. Reconstruct operational state. The branch and worktree, what already landed (`git log`, `git diff` against the base), the open todos, the decisions made. The prior trail is authoritative input. Resist the bias to re-derive it.
+3. Diff done vs pending. Compare what shipped against what was planned, name the resume point, do not re-run the prior repro or redo completed work. A "let me verify from scratch" pass is the tell that you're treating the trail as untrustworthy when it's actually authoritative.
+4. Route the remaining work to the matching playbook and pick the verdict: continue the execution, ship a finished recommendation, ratify or override a prior conclusion, or postmortem a failed run. The pickup playbook ends here; the routed playbook owns the rest.
+5. Verify the inherited claims against the original goal on the real artifact (the **principle-prove-it-works** skill). A passing prior self-report is not the proof.
+
+**Reply:** where the prior agent stopped, what you inherited vs redid (ideally nothing redone), the resume point, and the outcome.

package/skills/poteto-mode/playbooks/shipping.md

@@ -0,0 +1,20 @@
+### Shipping
+
+**You own what lands. Verify each PR independently, land only the verified run from the root, then keep your hands off the queue.** For "land the stack", "ship it", "enable merge when ready", or the second half of a stack that **Babysit** already drove to green.
+
+This is the half after `playbooks/babysit.md`. Babysit makes a stack mergeable. Shipping decides what is actually safe to merge and lets Graphite drain it. Green is not safe, and the gap between those two words is where this playbook lives.
+
+1. **Verify every PR independently before arming anything.** One subagent per PR, not batched, each a cloud or background subagent, each exercising the real surface (browser automation for UIs, the real binary for CLIs, or the project's `verify-*` skill) against parent versus head. Each returns `PASS`, `PASS+NOTES` or `FAIL` and posts that verdict on its own PR so the record outlives the chat. Safe means a verdict from an agent that did not write the code. CI green is not a verdict, and an approving bot review is not a verdict.
+2. **Land only the contiguous verified run rooted at the bottom.** Walk up from the lowest unmerged PR and stop at the first one without a passing verdict, where both `PASS` and `PASS+NOTES` pass. A verified PR sitting above an unverified one is not landable, because merging it would pull the gap in underneath it. Report the ceiling as a PR number and say what breaks the chain.
+3. **Re-check that the verdicts still describe the code.** A restack rewrites every SHA above it and silently invalidates every verdict without touching a single check. Compare `git patch-id` at the verdict SHA against the current head before trusting an older verdict, and re-verify anything that actually drifted. Twenty-one verdicts went stale this way in one run with no signal at all.
+4. **Arm merge-when-ready through Graphite, and pass `--always`.** A no-op submit skips the Graphite update and silently arms nothing, which reads exactly like success.
+   ```bash
+   gt submit --merge-when-ready --always --update-only --no-interactive
+   ```
+5. **Never enable GitHub auto-merge on a stack.** Only the root targets protected trunk. Every child targets its unprotected parent branch and already reads `CLEAN`, so GitHub would merge children into parents immediately and collapse the stack into itself. Graphite is what makes the merges sequential. If a previous agent armed it, disarm with `gh pr merge <n> --disable-auto` and confirm the field is back off.
+6. **Do not read `autoMergeRequest` as proof that MWR is armed.** It stays off until Graphite reaches that PR at the queue front, so an unarmed reading is meaningless and acting on it leads to re-submitting branches that were already fine. Confirm arming from Graphite's own state, and if you cannot, say so rather than inferring it.
+7. **Once the queue is draining, stop touching the stack.** No `gt sync`, no restack, no speculative pushes, and no `gt submit --stack`, which reaches downstack into PRs that are mid-merge. Even a plain `gt submit` can retarget a base if local Graphite tracking has diverged, so never run `gt` from a worktree whose parentage you have not just checked. Independent work gets re-parented onto trunk and shipped on its own.
+8. **Watch the drain, do not drive it.** Arm the watcher in queued mode over the verified run and hold it under `/loop` in dynamic mode, re-armed after any verdict you act on, until COMPLETE at the ceiling. ADVANCE is progress, not termination. Bases retarget and `graphite-base/*` refs get cut as each PR merges; that is Graphite working, not damage. Report each merge and the new ceiling. If the queue stalls, diagnose before mutating, because a stalled queue and a broken stack look identical from the outside.
+9. **Stop at the ceiling.** When the verified run is merged, report what landed, what the next unverified PR is, and what verifying it would take. Extending the run is a new pass through step 1, not a judgment call you make at 3am.
+
+**Reply:** the verified run and its ceiling, each PR's verdict and who produced it, what you armed and how you confirmed it, what landed, and what the next gap needs.

package/skills/poteto-mode/playbooks/trace-forensics.md

@@ -0,0 +1,14 @@
+### Trace forensics
+
+**You own the diagnosis from the artifact. Load it, shape it, narrow to the cause, attribute to source.** For a dropped `.cpuprofile`, `Trace-*.json.gz`, `Spindump.txt`, or `.heapsnapshot` paired with "why is this slow / unresponsive / leaking / crashing".
+
+Distinct from **Runtime forensics**, which instruments the live process. Here the capture already exists; the artifact is a fixed dataset, read it, don't re-run it. Keep tooling generic so the playbook stays portable: a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot.
+
+1. Identify the format and load it with the right tool. Parse large artifacts in a subagent (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread.
+2. Transform the raw artifact into a form you can query. Dump the trace or heap snapshot into sqlite, one row per sample, frame, or node. Reach the queryable shape before you read.
+3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree to the hot path. For a leak, follow the retainer chain from the leaked object to a GC root. For a spindump, find the thread stuck on-CPU or blocked and its wait reason.
+4. Attribute to source. Map the hot frame to file, symbol, and line via the artifact's own symbols. A frame with no source mapping is not yet a diagnosis; resolve the symbols, or say plainly the artifact does not carry them.
+5. Confirm against a paired capture when you have one. Diff a before and after artifact so the attribution is the real regression, not background noise. Without one, mark the finding as the strongest hypothesis the artifact supports, not a confirmed cause.
+6. Hand back a cited diagnosis, no fix unless asked. Route to Bug fix or Perf issue once the cause is known. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`.
+
+**Reply:** the artifact and format, the reduced finding, the source location, the artifact paths, and whether a paired capture confirmed it.

package/skills/poteto-mode/playbooks/visual-parity.md

@@ -0,0 +1,11 @@
+### Visual parity
+
+**You own pixel-exact equivalence. The baseline is the spec; you do not touch it.** For "make X match Y exactly", styling-system migrations, porting a UI across frameworks. Equivalence is verified by image diff, not by eye.
+
+1. Establish the baseline first, before any migration: a visual regression harness that screenshots the current component across its states, plus the target when matching two implementations. No baseline, no parity claim. A blocking prerequisite, not a follow-up.
+2. Anti-shortcut clauses, stated and held: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask, don't edit it.
+3. Migrate one component at a time. Each is an independent artifact, so parallelize across worktrees, one owner per component (the **separate-before-serializing-shared-state** principle skill). Shared primitives migrate first as a blocking phase.
+4. Verify each component against its baseline via image diff on the matching surface via the control skill. A nonzero diff is a fail; investigate the pixel delta, don't wave it through. `/loop` per component until the diff is zero.
+5. Run **Opening a PR** per component or per safe batch.
+
+**Reply:** components migrated, the diff result for each, the baseline harness location, what's left.

package/skills/poteto-mode/playbooks/worktree-cleanup.md

@@ -0,0 +1,14 @@
+### Worktree and simulator cleanup
+
+**You own the disk and the safety gate.** Prune merged or abandoned git worktrees and stale iOS simulators to reclaim space. Deletion is irreversible, so every step guards against deleting something in use or holding uncommitted work.
+
+1. Snapshot and audit. Record `df -h /`, then run `scripts/worktree-audit.sh` (principle-build-the-lever). It reads paths from `git worktree list`, never hand-typed, since a hand-typed `myrepo-worktrees/x` misses one that lives at a tool-managed path like `.cursor/worktrees/myrepo/x` or a worktree the host created itself (principle-encode-lessons-in-structure). It classifies each worktree by size, age, merge state, uncommitted work, PR state, and the newest chat that touched it, then suggests a bucket. The transcript scan is slow, so background it.
+2. The bucket is advice, not permission. The pinned and active chats are the real artifact (principle-prove-it-works). Get that set from the user or sidebar and cross-check every candidate. The lever has marked `safe` a worktree the user had pinned, so the pinned set wins.
+3. Verify usage before deleting. For every `verify-recent-chat` row, or anything you doubt, fan subagents out to read the transcripts and report whether the chat is pinned or ongoing and which worktrees it touches (principle-guard-the-context-window, transcripts are bulk). A pinned chat spawns arena and repro trees into sibling worktrees via background subagents, and those are in use even when their names never hit the sidebar.
+4. Pause on irreversible loss. `wip:N` is N tracked uncommitted edits. Show the diff and get a decision first, since removing a clean worktree is recoverable from its branch but uncommitted work is gone. `scratch:N` is untracked throwaway, safe to drop, but name the files. Per Autonomy, clean and merged and not-in-use proceeds; `wip` and in-use pause.
+5. Prune the confirmed set. Per path, `git worktree remove --force <path>`; if the dir survives on ignored build artifacts, `rm -rf` it, then `git worktree prune`. Branch refs survive, so no commits are lost. Confirm with `df -h /` and re-list.
+6. Simulators and other reclaimers. Simulators are usually the next-biggest win. `xcrun simctl --set testing delete all` (XCTestDevices clones), `xcrun simctl delete unavailable`, and `xcrun simctl runtime list` then `runtime delete <id>` for old runtimes. More when needed: Xcode `DerivedData` and `iOS DeviceSupport`; the host editor's data directory, e.g. `~/Library/Application Support/Cursor` (`state.vscdb.backup`, and `snapshots/roots/<root>` where a `<root>` named for a folder you opened as a workspace balloons); package caches (pnpm, uv, brew, yarn). Clear only caches the user has not said to keep.
+
+This is the one playbook that deletes user state with no code review to catch a slip, so the gates above are the review.
+
+**Reply:** `df -h /` before and after with space reclaimed, the worktrees pruned, and a one-line reason for each held back (in-use by which chat, or uncommitted work).

package/skills/poteto-mode/references/bugbot-triage.md

@@ -0,0 +1,142 @@
+# Bugbot triage
+
+Use this reference when the Babysit playbook (`../playbooks/babysit.md`) handles Bugbot or review-automation comments. The goal is not to ignore Bugbot by default. The goal is to stop treating every comment as a required code change.
+
+## Decision rubric
+
+Classify each Bugbot thread before acting:
+
+- `fix`: The comment identifies a plausible correctness, security, privacy, data loss, auth, billing, migration, idempotency, race, or shipped-behavior issue. Fix it in the lowest owning PR, then reply with the commit SHA and resolve the thread.
+- `dismiss`: The comment matches a documented low-risk noisy pattern, and the current code/context proves the concern does not need a code change. Reply with a short reason and resolve the thread.
+- `ask`: The comment is novel, high-severity, security/privacy/data-related, or ambiguous. Ask the user instead of guessing.
+
+When in doubt, ask. Skipping a noisy code-quality comment is cheap; skipping a real data or security bug is not.
+
+## Learned pattern format
+
+Add future patterns in this shape:
+
+```markdown
+### <short pattern name>
+
+- Confidence: candidate | recurring | strong
+- Skip when: <conditions that must be true>
+- Do not skip when: <risk boundaries>
+- Example signal: <phrases or code context that identify the pattern>
+- Source: <PR/comment URL or short historical note>
+```
+
+Use `candidate` for one or two examples. Use `recurring` after multiple real dismissals. Use `strong` only when the pattern is narrow, repeatedly verified, and low-risk.
+
+## Recurring skip candidates
+
+### Intentional UI or design-system visual changes
+
+- Confidence: candidate
+- Skip when: The PR description, screenshots, design review, or nearby code makes the visual change explicit, and the Bugbot comment is only restating that a shared visual default changed.
+- Do not skip when: The comment points to accessibility, focus visibility, keyboard navigation, color contrast, or a component API contract that the PR did not intentionally change.
+- Example signal: Comments about focus outlines, button sizes, spacing, or shared component visual defaults where the owner replies "intentional" or "intended".
+
+### Upstack or stack-local usage Bugbot cannot see
+
+- Confidence: candidate
+- Skip when: Bugbot flags an export, component, helper, or file as unused, and `gt ls -s`, upper-stack diffs, or PR context shows it is used by a later PR in the stack.
+- Do not skip when: The current PR is not part of a stack, the symbol is public API, or the supposed upstack use cannot be verified.
+- Example signal: "Exported component is never used" with a human reply like "used upstack".
+
+### Temporary duplication during parallel implementation
+
+- Confidence: candidate
+- Skip when: The PR intentionally duplicates a small amount of code to keep a new path parallel to an old path that is being deleted, replaced, or proven out.
+- Do not skip when: The duplicated code changes security, billing, data access, API behavior, or a long-lived shared abstraction would clearly reduce risk.
+- Example signal: "Significant duplication" or "duplicated validation logic" where the owner explains the old path will be deleted or the duplicate logic is intentionally local.
+
+### Existing framework or component invariant covers the warning
+
+- Confidence: candidate
+- Skip when: The concern is already guaranteed by a shared component, framework contract, type invariant, or single source of truth visible in the current diff or nearby code.
+- Do not skip when: The invariant is assumed but not enforced, depends on timing, or crosses async/state boundaries where values can diverge.
+- Example signal: Comments about missing max-height on an inner popover when the shared popover enforces viewport bounds, or nullable values where the local checked value and passed value share the same source.
+
+### Owner-declared follow-up or deferred cleanup
+
+- Confidence: candidate
+- Skip when: The PR owner explicitly says the issue is a known follow-up, the behavior is not made worse by the current PR, and the comment is not about a high-risk area.
+- Do not skip when: The agent is acting without owner input, the issue is medium/high severity product behavior, or deferring would merge a new regression.
+- Example signal: "I'll worry about that later" or "we'll delete this eventually".
+
+### Self-withdrawn or explicit false-positive rule comments
+
+- Confidence: recurring
+- Skip when: The comment body or a later Bugbot reply explicitly says the finding is withdrawn, compliant, or a false positive, and the agent can verify the relevant rule locally.
+- Do not skip when: The only evidence is a human saying "false positive" on a high-risk issue without explanation.
+- Example signal: A file-naming rule comment whose body says the file is already compliant.
+
+## Ask by default
+
+Do not auto-skip these categories, even if a previous PR dismissed something similar:
+
+- Security, privacy, auth, billing, data retention, training-data, and permission-boundary findings.
+- High-severity findings.
+- Migration, schema, idempotency, concurrency, and cross-system behavior findings.
+- Comments where the suggested fix is small and clearly reduces risk without changing product intent.
+
+Historical data showed humans sometimes dismiss security/data-flow comments. Treat those as owner judgment calls, not team-wide skip rules.
+
+## Candidate learnings from recent babysits
+
+Append new candidate learnings here during or after babysitting when they look team-useful but not yet mature. Prefer promoting recurring candidates into the section above once several PRs confirm the pattern.
+
+### Manual reimplementations of native browser behavior
+
+- Confidence: candidate
+- Skip when: Practically never. When a diff replaces native browser behavior with a manual equivalent (native sticky → JS-positioned clones, native scroll targeting → forwarded wheel/touch events, paint-order occlusion → masks/clip-path), Bugbot's logic-bug findings against that code have been consistently legitimate.
+- Do not skip when: The finding concerns event-forwarding gaps (wheel deltaMode, touch pans, scroll-chaining at edges, tap slop), mask/clip hit-testing divergence, or observer-vs-React state timing races in such code. Default to fix.
+- Example signal: "masks do not affect hit-testing", "overlay blocks wheel scroll", "ignores deltaMode", "runs in the IntersectionObserver callback before React applies state".
+- Source: one sticky-occlusion PR: six Bugbot passes, roughly eighteen findings, every one fixed rather than dismissed.
+
+### Contract-test drift claims are cheaply verifiable — run the test first
+
+- Confidence: candidate
+- Skip when: Never skip the verification itself; it costs one command. When a PR
+  ships a contract test that pins protocol or documentation prose (regexes over
+  a SKILL.md, snapshot of doc wording), and Bugbot claims "the test no longer
+  matches the doc" (or vice versa), run that test on the PR tip before
+  classifying. A red run confirms the claim empirically; a green run is a
+  concrete disproof for the dismissal reply.
+- Do not skip when: n/a — this is a verification shortcut, not a dismissal
+  pattern. Note that repeat-pass lean-dismiss heuristics would misfire here:
+  prose-pinning tests drift precisely BECAUSE earlier fix rounds edit the prose.
+- Example signal: "Contract test omits the pre-fix wait" on a PR whose earlier
+  fix commits reworded the pinned passage; the test run on the tip failed on
+  exactly the cited assertion.
+- Source: one prose-pinning PR with eight Bugbot passes; the claim was real on
+  pass 7 despite every earlier pass being fixed-and-resolved.
+
+### Stale security-review finding already fixed later in the same PR
+
+- Confidence: candidate
+- Skip when: An agentic security review (or similar) claims a missing authz/validation call, and the current PR tip clearly includes that exact gate (with tests), typically added in a later hardening commit after the review ran.
+- Do not skip when: The cited helper is a no-op for the principal under discussion, the check runs after the side effect it guards, or coverage for the claimed principal is missing.
+- Example signal: A HIGH "missing authorization check" finding while the exact guard is already called before the side effect on the tip.
+- Source: one webhook-endpoint PR whose hardening commit postdated the review run.
+
+### Widening a deliberately narrow error condition would mask the real error
+
+- Confidence: candidate
+- Skip when: The finding asks to broaden a narrow error condition (a specific
+  `errno`, error code, or status class) into a catch-all, and that narrowness
+  encodes a real distinction. The canonical shape is a dependency fallback
+  gated on `ENOENT`: "binary is not installed" is a different situation from
+  "the command ran and failed". Retrying on any non-zero exit would re-run a
+  legitimate failure (not found, expired auth, network) against the fallback
+  and then report the fallback's error, hiding the true one.
+- Do not skip when: The narrow condition misses a case in the SAME category
+  (another "binary unusable" errno such as `EACCES`, another transport-level
+  failure), the unhandled path loses data or leaves partial state, or the retry
+  is idempotent AND the original error is still surfaced.
+- Example signal: "only retries when X fails with ENOENT … never tries the
+  fallback even when a working Y exists", pointing at code whose fallback
+  exists for a missing dependency rather than a failed operation.
+- Source: one CLI-rename PR whose fallback existed for a missing binary rather
+  than a failed command.

package/skills/poteto-mode/references/plan.md

@@ -0,0 +1,105 @@
+# Plan
+
+Produce a phased implementation plan grounded in the **Principles** section of the `poteto-mode` skill. The plan is the deliverable. Do not implement.
+
+Open a todolist with one item per step below.
+
+## 0. Triage
+
+Skip the plan when the change is one or two files with an obvious approach. Say so and stop.
+
+Plan when the change spans three or more files, introduces architecture, has competing approaches or unclear scope, or the user asked for one.
+
+## 1. Re-read principles
+
+Read the **Principles** section of the `poteto-mode` skill end to end, and the leaf `principle-*` skills it indexes. The principles govern every plan decision; cross-link them.
+
+## 2. Scope and constraints
+
+State your read of scope and constraints in one paragraph. Use `AskUserQuestion` only for genuinely ambiguous intent (the **never-block-on-the-human** principle skill); give concrete options with each open question.
+
+Resolve what is in scope vs explicitly out, technical or platform constraints, patterns to preserve, and the definition of done.
+
+## 3. Explore in subagents
+
+Delegate codebase exploration (the **guard-the-context-window** principle skill).
+
+- Prefer `subagent_type: "poteto-agent"`. `general-purpose` is the fallback. Never use the built-in `plan` subagent_type; it ignores this skill.
+- Pass `model:` explicitly per the configured roles (defaults `sonnet` for code, `fable` for judgment).
+
+Each explorer returns file pointers, conventions, dependencies, test infrastructure, and entry points. No inlined dumps.
+
+## 4. Write the plan
+
+The user specifies where the plan lives.
+
+Single file `NN-slug.md` for small plans. For three or more phases, a directory with `overview.md` plus phase files:
+
+```
+NN-slug/
+├── overview.md
+├── phase-1-scaffold.md
+├── phase-2-...md
+└── testing.md
+```
+
+### Phase sizing
+
+- One function or type plus tests, or one bug fix. Not "one file".
+- Two to three files touched, max.
+- Prefer eight to ten small phases over three to four large ones to preserve option value (the **foundational-thinking** principle skill).
+- Split if a phase has more than five test cases or three functions.
+
+### Overview file
+
+- **Context.** Problem and why now.
+- **Scope.** Included; explicitly excluded.
+- **Constraints.** Technical, platform, dependency, pattern.
+- **Alternatives.** Two or three approaches sketched, choice and rationale (the **exhaust-the-design-space** principle skill). Skip when constraints dictate one.
+- **Applicable skills.** Domain skills the implementer should invoke, by name.
+- **Phases.** Ordered standard-markdown links to phase files.
+- **Verification.** Project-level commands.
+- **Implementation guidance.** Per section 6.
+
+### Phase files
+
+- Back-link to overview.
+- **Goal.** What the phase accomplishes.
+- **Changes.** Files affected and the change at a high level. What and why, not how. No code snippets.
+- **Data structures.** Name the key types or schemas. One-line sketch only (the **foundational-thinking** principle skill).
+- **Verification.** Per section 6.
+
+Order phases so infrastructure and shared types land first (the **foundational-thinking** principle skill). Each phase should be independently shippable.
+
+For changes touching existing code, apply the **redesign-from-first-principles** principle skill: if we'd built this with the new requirement on day one, what would it look like? Redesign holistically; deliver incrementally.
+
+If a phase creates or edits a skill, the phase instructs the implementer to use the host's skill-authoring skill when one is installed, and otherwise to author the SKILL.md directly (frontmatter `name` and `description`, imperative body).
+
+## 5. Verification per phase
+
+Each phase needs both:
+
+**Static.** Type check, lint, project tests pass.
+
+**Runtime.** Exercise the feature on the matching surface:
+
+- Browser / Electron / Web UIs: the project's `verify-*` skill when one exists, otherwise browser automation.
+- CLIs and TUIs: the project's `verify-*` skill, otherwise run the real binary in a scripted harness.
+- Native mobile: whatever simulator-driving skill your team has.
+- No way to drive the touched surface: flag it in the plan (and consider `/create-verification-skill`).
+
+For bug fixes, the loop is reproduce on the surface, fix, verify on the same surface. Unit tests show a branch behaves a certain way; they do not prove the bug is gone (the **prove-it-works** principle skill).
+
+## 6. Implementation guidance
+
+In the overview, name which poteto-mode non-negotiables the implementer must apply, by name:
+
+- the **how** skill over each unfamiliar subsystem before changing it.
+- the **interrogate** skill for adversarial review on contested designs before shipping.
+- a deslop pass over each diff before commit (no narration comments, dead code, or workaround sermons). the **unslop** skill over any prose surface.
+- the **show-me-your-work** skill to keep a decision trail when the plan is large enough to need an auditable record.
+- the **Babysit** playbook after opening the PR.
+
+## 7. Hand back
+
+Summarize phases, scope boundaries, applicable skills, and verification. Stop. The user decides when implementation starts.

package/skills/poteto-mode/scripts/bootstrap.ts

@@ -0,0 +1,62 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const scriptsDirectory = import.meta.dir;
+const nodeModulesDirectory = join(scriptsDirectory, "node_modules");
+const commanderPackagePath = join(
+  nodeModulesDirectory,
+  "commander",
+  "package.json"
+);
+const installKeyPath = join(
+  nodeModulesDirectory,
+  ".poteto-mode-tools-install-key"
+);
+
+function currentInstallKey(): string {
+  return createHash("sha256")
+    .update(readFileSync(join(scriptsDirectory, "package.json")))
+    .update("\0")
+    .update(readFileSync(join(scriptsDirectory, "bun.lock")))
+    .digest("hex");
+}
+
+export function ensureDependenciesInstalled(): void {
+  const installKey = currentInstallKey();
+  if (
+    existsSync(commanderPackagePath) &&
+    existsSync(installKeyPath) &&
+    readFileSync(installKeyPath, "utf8").trim() === installKey
+  ) {
+    return;
+  }
+
+  const result = Bun.spawnSync(
+    [process.execPath, "install", "--frozen-lockfile"],
+    { cwd: scriptsDirectory }
+  );
+  if (result.exitCode !== 0) {
+    process.stdout.write(result.stdout);
+    process.stderr.write(result.stderr);
+    throw new Error(
+      `bun install --frozen-lockfile exited with status ${result.exitCode}`
+    );
+  }
+  if (!existsSync(commanderPackagePath)) {
+    throw new Error(
+      "bun install --frozen-lockfile completed without installing commander"
+    );
+  }
+
+  writeFileSync(installKeyPath, `${installKey}\n`);
+
+  const restarted = Bun.spawnSync([process.execPath, ...process.argv.slice(1)], {
+    cwd: process.cwd(),
+    env: process.env,
+    stdin: "inherit",
+    stdout: "inherit",
+    stderr: "inherit",
+  });
+  process.exit(restarted.exitCode ?? 1);
+}

package/skills/poteto-mode/scripts/bun.lock

@@ -0,0 +1,67 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@cursor-skill/poteto-mode-tools",
+      "dependencies": {
+        "commander": "14.0.0",
+      },
+      "devDependencies": {
+        "bun-types": "latest",
+        "typescript": "latest",
+      },
+    },
+  },
+  "packages": {
+    "@types/node": ["@types/node@26.1.2", "", { "dependencies": { "undici-types": "~8.3.0" } }, "sha512-Vu4a5UFA9rIIFJ7rB/Vaafh9lrCQszopTCx6KjFboXTGQbPNasehVR5TEiithSDGyd1DEiUByggTZsg8jukeIg=="],
+
+    "@typescript/typescript-aix-ppc64": ["@typescript/typescript-aix-ppc64@7.0.2", "", { "os": "aix", "cpu": "ppc64" }, "sha512-MTKKkWB7p/0E9xi1d1tHtZ5PiLkGEMIq88pK2CubZjOsLtYTLqhgIgi6zepFa+9GHZ6h05NMCkQxGKiPXMxXtQ=="],
+
+    "@typescript/typescript-darwin-arm64": ["@typescript/typescript-darwin-arm64@7.0.2", "", { "os": "darwin", "cpu": "arm64" }, "sha512-gowzar9MwS/aRWp6f3a4KUqzRjAZjOsmGNCM6LcTgXum+dBfgsBVMN+AgvOCCbguXyick6LJhpBszxMebJ8syA=="],
+
+    "@typescript/typescript-darwin-x64": ["@typescript/typescript-darwin-x64@7.0.2", "", { "os": "darwin", "cpu": "x64" }, "sha512-SZ9xZInqApNlNGc9s0W1VSsktYSOe9cFqNOIqmN1Gs8SmkjKZYFt017G4VwPxASInODuAdbTW7sXiFUf893RgA=="],
+
+    "@typescript/typescript-freebsd-arm64": ["@typescript/typescript-freebsd-arm64@7.0.2", "", { "os": "freebsd", "cpu": "arm64" }, "sha512-W5NH4y/J0plIIS5b2xvTEkU7JFxyqdMAOgf+Ilhl0vHQXKO5dZoxd+C/jEtq56c4F3wk71RB4BMRQ2XdI+bwYQ=="],
+
+    "@typescript/typescript-freebsd-x64": ["@typescript/typescript-freebsd-x64@7.0.2", "", { "os": "freebsd", "cpu": "x64" }, "sha512-UMGDx5sTpzNw3WiPebH7l90IWfJggEd+egHt/q6p7/Cm3zqoV7VxkGXt+3DxPIw8CcmvAB0j3sVVfbhX+M4Tpw=="],
+
+    "@typescript/typescript-linux-arm": ["@typescript/typescript-linux-arm@7.0.2", "", { "os": "linux", "cpu": "arm" }, "sha512-gffT3xPz9sR7j/YJExkyPntrI0P2EP9XbOyWzth2/Gs0RstK+90RBcO0ncXoXy/beYll1SXw846Nf2zdnEz0QQ=="],
+
+    "@typescript/typescript-linux-arm64": ["@typescript/typescript-linux-arm64@7.0.2", "", { "os": "linux", "cpu": "arm64" }, "sha512-Qh4eU4/y3yDjnfjjyPYihMj5/ODIlmt+Bzu17OI+fiSRDW57QmU5SiN63exPRNJPKUzcc1INa1NXdrJ+MqHjUQ=="],
+
+    "@typescript/typescript-linux-loong64": ["@typescript/typescript-linux-loong64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-uEHck9i8hoAzXPiYRib1O7miOnz23SxIeVl6F4LXox+qov1K35jHcEW6VHKvZI+pyvl7fZEP4MCU5LYvIq1GuQ=="],
+
+    "@typescript/typescript-linux-mips64el": ["@typescript/typescript-linux-mips64el@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-R4KvAMnE43W5Qeqb0Ly56O3mWMWIAgsMyz36DCaycd5nbg/9kzm0liw3JocfRqyJY0KPmzFjbswozXyW0DnIYA=="],
+
+    "@typescript/typescript-linux-ppc64": ["@typescript/typescript-linux-ppc64@7.0.2", "", { "os": "linux", "cpu": "ppc64" }, "sha512-DORx5b3sd/4S7eayxm4FQv+A7CrkUIGRaHiwI8oiHTAI1fAPWhF4J0vAlkC8biAlHSVVwxMQ3tjZ2/DVbnQiiA=="],
+
+    "@typescript/typescript-linux-riscv64": ["@typescript/typescript-linux-riscv64@7.0.2", "", { "os": "linux", "cpu": "none" }, "sha512-wf0jqEDOjrPRnKwYRyyJDRo11KMbvMFrU+q4zqKyChODBzvlkbhNQfKvLxQCcwTpdDaXSHZTVuh0JoCrKCUMHQ=="],
+
+    "@typescript/typescript-linux-s390x": ["@typescript/typescript-linux-s390x@7.0.2", "", { "os": "linux", "cpu": "s390x" }, "sha512-IkwJc3L7yhytWd/ewjyxNDfOmswCm9GWMJT/ue/dU4aZNbwZeYAetq42VyLmsmSjvoX7z74X6ZaYCtzAr0EuGw=="],
+
+    "@typescript/typescript-linux-x64": ["@typescript/typescript-linux-x64@7.0.2", "", { "os": "linux", "cpu": "x64" }, "sha512-EYdf2cNg7rgCWJnxCdJ+F3V39O8ihb37eHAu1LK8oAFizgTQbPOK7zHHXbPt8rX24COqODXeI3sIf0fCXG7H/A=="],
+
+    "@typescript/typescript-netbsd-arm64": ["@typescript/typescript-netbsd-arm64@7.0.2", "", { "os": "none", "cpu": "arm64" }, "sha512-+polYF4MF04aPpO5FTkHran9yUQDSXqy5GiSDKpsll5jy3l3+g9QLhpf39T+ePtefhXLOGrLl0QIjkQP6VnelA=="],
+
+    "@typescript/typescript-netbsd-x64": ["@typescript/typescript-netbsd-x64@7.0.2", "", { "os": "none", "cpu": "x64" }, "sha512-8YIT0EHM/3dq10ZOVF/A7pc/YSMtbcecct4rWtexrnSCHOPcpC2KTLXfTCR6vDpnSiY12heNb1GiN/wu+T/FyA=="],
+
+    "@typescript/typescript-openbsd-arm64": ["@typescript/typescript-openbsd-arm64@7.0.2", "", { "os": "openbsd", "cpu": "arm64" }, "sha512-APT8+ClYnuYm1u9+kgGXoMj2VzWzcymwh2gNSQVySHfkRDGOTVkoWLjCmOQSaO+PoqQ57B0flRp9SA+7GnnkzQ=="],
+
+    "@typescript/typescript-openbsd-x64": ["@typescript/typescript-openbsd-x64@7.0.2", "", { "os": "openbsd", "cpu": "x64" }, "sha512-yX7s+Q0Dln0Dt9tEzZsAjXXR/+ytBM7AlglaqyeMPxQszJ1JhlJdZ6jLA+IzldHtflX81em7lDao1xXu+aRRkg=="],
+
+    "@typescript/typescript-sunos-x64": ["@typescript/typescript-sunos-x64@7.0.2", "", { "os": "sunos", "cpu": "x64" }, "sha512-dLJDGaLZ1D4HPQn62u1n8mBDkJREwMsAkCdkwd4Ieqw+x3TUyTsqY0YiBCtE6H6OzzgGk3iuZ3vFWRS+E8/d1g=="],
+
+    "@typescript/typescript-win32-arm64": ["@typescript/typescript-win32-arm64@7.0.2", "", { "os": "win32", "cpu": "arm64" }, "sha512-Gyl1Vy6OsWesLzmq+EP0Fb7b4Nid5232AvcA2SFcdYreldpNtYFFofPjnt62y9hQy7VTaZp65ICJjuAQRaVcIQ=="],
+
+    "@typescript/typescript-win32-x64": ["@typescript/typescript-win32-x64@7.0.2", "", { "os": "win32", "cpu": "x64" }, "sha512-0BQ3HkAHHlKLSp1qRvf3SUhGpGsDuhB/jgFw75guyqbxJqEaS0Cw/VFO8i2nHglJUzQCRtMMR/IBAKE3ETMC4g=="],
+
+    "bun-types": ["bun-types@1.3.14", "", { "dependencies": { "@types/node": "*" } }, "sha512-4N0ig0fEomHt5R0KCFWjovxow98rIoRwKolrYdCcknNwMekCXRnWEUvgu5soYV8QXtVsrUD8B95MBOZGPvr6KQ=="],
+
+    "commander": ["commander@14.0.0", "", {}, "sha512-2uM9rYjPvyq39NwLRqaiLtWHyDC1FvryJDa2ATTVims5YAS4PupsEQsDvP14FqhFr0P49CYDugi59xaxJlTXRA=="],
+
+    "typescript": ["typescript@7.0.2", "", { "optionalDependencies": { "@typescript/typescript-aix-ppc64": "7.0.2", "@typescript/typescript-darwin-arm64": "7.0.2", "@typescript/typescript-darwin-x64": "7.0.2", "@typescript/typescript-freebsd-arm64": "7.0.2", "@typescript/typescript-freebsd-x64": "7.0.2", "@typescript/typescript-linux-arm": "7.0.2", "@typescript/typescript-linux-arm64": "7.0.2", "@typescript/typescript-linux-loong64": "7.0.2", "@typescript/typescript-linux-mips64el": "7.0.2", "@typescript/typescript-linux-ppc64": "7.0.2", "@typescript/typescript-linux-riscv64": "7.0.2", "@typescript/typescript-linux-s390x": "7.0.2", "@typescript/typescript-linux-x64": "7.0.2", "@typescript/typescript-netbsd-arm64": "7.0.2", "@typescript/typescript-netbsd-x64": "7.0.2", "@typescript/typescript-openbsd-arm64": "7.0.2", "@typescript/typescript-openbsd-x64": "7.0.2", "@typescript/typescript-sunos-x64": "7.0.2", "@typescript/typescript-win32-arm64": "7.0.2", "@typescript/typescript-win32-x64": "7.0.2" }, "bin": { "tsc": "bin/tsc" } }, "sha512-8FYau96o3NKOhbjKi/qNvG/W5jhzxkbdm5sj9AbZ/5T5sWqn3hJgLfGx27sRKZWTvyzCP8dLRBTf5tBTSRVUNA=="],
+
+    "undici-types": ["undici-types@8.3.0", "", {}, "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ=="],
+  }
+}