# pstack — full corpus # LLM Wiki An open-source template for building LLM-powered knowledge bases, following [Andrej Karpathy's "LLM Wiki" pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f). You provide raw sources. The LLM reads them, writes structured wiki pages, cross-links everything, and maintains it over time. You never edit the wiki directly — you curate sources and ask questions. ## How It Works The system has three layers: ``` raw/ Sources you collect (articles, transcripts, notes, PDFs) wiki/ LLM-written & maintained pages (summaries, concepts, entities, syntheses) CLAUDE.md Schema that tells the LLM how to structure everything ``` Three operations drive the workflow: | Operation | Trigger | What happens | |-----------|---------|--------------| | **Ingest** | "ingest raw/my-source.txt" | LLM reads the source, creates a summary page, creates/updates concept and entity pages, adds cross-links, updates the index and log | | **Query** | Ask any question | LLM searches the wiki, synthesizes an answer with citations, optionally creates a synthesis page for novel insights | | **Lint** | "lint" or "health check" | LLM audits all pages for orphans, contradictions, missing links, incomplete sections, and low-confidence claims — fixes what it can, reports the rest | ## Quick Start 1. **Clone this repo** ```bash git clone https://github.com/YOUR_USERNAME/llm-wiki.git my-knowledge-base cd my-knowledge-base ``` 2. **Customize CLAUDE.md** for your domain - Update the Purpose section with your topic - Replace the placeholder tagging taxonomy with your own categories - Adjust confidence level descriptions if needed - Everything else (workflows, page formats, linking rules) works as-is 3. **Drop sources into `raw/`** - Text files, transcripts, articles, notes — any plain text - These are immutable once added; the LLM never modifies them 4. **Tell the LLM to ingest** ``` ingest raw/my-first-source.txt ``` The LLM will create summary pages, concept pages, entity pages, cross-links, and update the index. 5. **Ask questions** ``` What are the key differences between X and Y? ``` The LLM answers from the wiki, citing specific pages. 6. **Run health checks** ``` lint ``` The LLM audits the wiki and fixes issues. ## Directory Structure ``` . ├── CLAUDE.md # Schema — the LLM's instructions ├── raw/ # Your source documents (immutable) └── wiki/ ├── index.md # Master catalog of all pages ├── log.md # Append-only activity log ├── dashboard.md # Dataview dashboard (Obsidian) ├── analytics.md # Charts View analytics (Obsidian) ├── flashcards.md # Spaced repetition cards ├── summaries/ # One page per source document ├── concepts/ # Concept and framework pages ├── entities/ # People, tools, organizations, etc. ├── syntheses/ # Cross-cutting analyses and comparisons ├── journal/ # Research/session journal entries │ └── template.md # Journal entry template └── presentations/ # Marp slide decks ``` ## Enhancements This template includes several extras beyond the core wiki pattern: ### Dataview Dashboard (`wiki/dashboard.md`) Live queries that surface low-confidence pages, recent updates, concepts by tag, and pages with the most sources. Requires the [Dataview](https://github.com/blacksmithgu/obsidian-dataview) Obsidian plugin. ### Charts View Analytics (`wiki/analytics.md`) Visual analytics with pie charts, bar charts, and word clouds. Requires the [Charts View](https://github.com/caronchen/obsidian-chartsview-plugin) Obsidian plugin. ### Mermaid Diagrams Use Mermaid code blocks in any wiki page to create flowcharts, sequence diagrams, or concept maps. Native support in Obsidian and GitHub. ### Marp Slides (`wiki/presentations/`) Create slide decks from markdown using [Marp](https://marp.app/). Drop presentation files in this directory. ### Research Journal (`wiki/journal/`) Track your research sessions, experiments, or applied work with the included template. The LLM can reference journal entries when answering queries. ### Spaced Repetition (`wiki/flashcards.md`) Flashcards in the format used by the [Spaced Repetition](https://github.com/st3v3nmw/obsidian-spaced-repetition) Obsidian plugin. Ask the LLM to generate flashcards from any wiki page. ### MCP Server This repo works with Claude Code's MCP server capabilities. Point an MCP-compatible client at this repo and the LLM can read/write the wiki programmatically. ## Customizing for Your Domain The schema in `CLAUDE.md` is domain-agnostic. To adapt it: 1. **Purpose** — Describe your knowledge domain in one paragraph 2. **Tagging taxonomy** — Replace placeholder categories with your own (e.g., for a cooking KB: `cuisine`, `technique`, `ingredient`, `equipment`) 3. **Confidence levels** — Adjust the descriptions to match your domain's evidence standards 4. **Entity types** — Update the entity page description to match what entities mean in your domain (people, tools, companies, etc.) 5. **Journal template** — Customize `wiki/journal/template.md` for your workflow Everything else — page format, linking conventions, workflows, rules — is universal and works across domains. ## Example Domains This template works for any knowledge-intensive topic: - **Research notes** — papers, experiments, methodologies - **Book analysis** — themes, characters, author techniques - **Competitive analysis** — companies, products, market trends - **Course notes** — lectures, readings, key concepts - **Personal development** — frameworks, habits, book summaries - **Technical documentation** — APIs, architectures, design patterns - **Hobby deep-dives** — any subject you want to master ## License MIT --- title: "pstack KB — Master Index" type: index updated: 2026-10-21 pstack_version: "0.15.29" sources: ["raw/github_doc-pstack-plugin-json.md", "raw/github_doc-pstack-cursor-plugin-plugin-json.md"] --- # pstack KB — Master Index **Domain:** pstack, the Cursor plugin of rigorous agent-engineering skills by Lauren Tan (poteto): /poteto-mode and its 23 playbooks, 32 non-principle skills, 24 principles, the poteto-agent and Comment Sicko subagents, helper scripts (watch-pr, orch, check-plan, worktree-audit), the dormant Benny automation, and running pstack under Claude Code. **Scope:** pstack as published in cursor/plugins at fetch time (both manifests say 0.15.29), its issues and its last 100 commits. Not covered: cursor-team-kit skills pstack references (/deslop, control-cli, control-ui), Cursor built-ins (/create-skill, /autopilot, plan mode), the generated harness/pstack copy, and Codex support (only open issues). **Pages:** 30 (6 syntheses · 16 concepts · 3 entities · 5 summaries) **Sources fetched:** 2026-10-21 Start at [[syntheses/overview]] if you are new. ## Syntheses - [[syntheses/getting-started]] — The README's "get started" is two steps: run /setup-pstack and pick a reasoning budget and models, then use /poteto-mode whenever you're doing anything that requires… - [[syntheses/overnight-and-autonomous-runs]] — Guide 07 ("Run work while you sleep") says leaving an agent alone is safe only with "a checkable finish condition, an isolated worktree or cloud agent, and a decision… - [[syntheses/overview]] — pstack is a Cursor plugin of agent-engineering skills whose README is written in the first person by poteto (the plugin manifest lists the author as Lauren Tan),… - [[syntheses/pstack-on-claude-code]] — Running pstack under Claude Code: install commands, /pstack: prefixes, the model rule file, the generated harness copy, and what is skipped. - [[syntheses/recipes-and-pitfalls]] — Prompts worth copying, the mistakes guide 10 says "everyone makes once", and a troubleshooting table built from poteto-help and the issue tracker. - [[syntheses/which-skill-when]] — Decision map from "I want to…" to the right skill or playbook, plus close calls (arena vs swarm, how vs why vs teach, verification vs formal verification, interrogate vs reflect). ## Concepts - [[concepts/benchmarks-and-numbers]] — pstack treats every measured number (a speedup, a regression, a throughput, a latency, an eval result) as a claim that must be vetted before anyone reports or acts on it. - [[concepts/build-and-clean]] — Guide chapter 05: the build playbooks (feature, bug fix, refactor, perf, hillclimb), /tdd, /no-comments, /typescript-best-practices and /blast-radius. - [[concepts/code-review-with-interrogate]] — /interrogate is pstack's multi-model adversarial review. - [[concepts/decision-logs]] — /show-me-your-work keeps one canonical, reviewable decision trail for long-running or unattended work: a single TSV file with one row per decision (what, why,… - [[concepts/design-before-code]] — Guide chapter 04: /architect, /arena, /swarm and prototypes to settle a design before code locks it in. - [[concepts/formal-verification]] — /create-formal-verification-skill generates a project-local skill that formally verifies one property of the code "where a bug costs the most and tests reach the… - [[concepts/installation-and-model-setup]] — Installing pstack adds its skills and agents; /setup-pstack then configures which model each pstack role uses and at what reasoning budget. - [[concepts/make-it-yours]] — Guide chapter 09: "poteto-mode is one person's style." The playbooks, routing, and model roles work just as well with yours. - [[concepts/orchestration-and-multi-phase-plans]] — The orchestrate and multi-phase-plan playbooks for work bigger than one PR, the orch script, check-plan.mjs and autopilot-stack. - [[concepts/poteto-mode]] — poteto-mode is pstack's front door: "poteto's agent style for concise, detailed responses, deliberate subagents, unslopped prose, simple code, and verified work." You… - [[concepts/prompting-pstack]] — pstack prompts state intent and a check for done; the playbook supplies the steps. - [[concepts/shipping-prs-and-watch-pr]] — Opening a PR, shipping and babysit playbooks, Bugbot triage, and the bundled watch-pr CLI that reports PR/stack status until a terminal verdict. - [[concepts/technical-writing-and-unslop]] — The prose skills: /technical-writing (the layered doc standard), /unslop (removes AI tells) and /bro (plain restatement). - [[concepts/understanding-code]] — pstack's comprehension layer (guide chapter 03, "Understand the code before changing it") is four read-mostly skills that make the agent build and state a checkable… - [[concepts/verification-skills]] — A verification skill is a project-local skill that lets any agent drive your real app the way a user does and capture evidence that a behavior works. - [[concepts/worktrees]] — pstack does all PR work in git worktrees: the Opening a PR playbook says "Work from a git worktree off main. ## Entities - [[entities/benny-automation]] — Benny, the dormant Cursor-only automation pack that triages Slack issue reports and reproduces and fixes confirmed bugs; setup, config keys and templates. - [[entities/poteto-agent-and-comment-sicko]] — The two subagents pstack ships: poteto-agent (wrapper for delegates, not the runner) and Comment Sicko (read-only comment reviewer). - [[entities/pstack]] — pstack is a Cursor plugin of rigorous agent-engineering skills, published in the cursor/plugins repository under the pstack/ folder. ## Summaries - [[summaries/known-issues]] — All 25 pstack issues in the corpus with state as of 2026-10-21, grouped by theme, data-loss hazards first. - [[summaries/playbook-catalog]] — The playbooks inside /poteto-mode, one row each. - [[summaries/principles-catalog]] — The 24 principles with group and rule, and how to steer an agent mid-task by principle name. - [[summaries/release-history]] — Digest of the last 100 commits touching pstack/ (fetched 2026-10-21): version bumps and major additions by date. - [[summaries/skill-catalog]] — Every non-principle skill under pstack/skills/ (32 directories as fetched 2026-10-21), one row each. --- title: "Benchmarks and Numbers: /benchmark-checklist, Explain the Number, Hillclimb, Eval" type: concept tags: [benchmark-checklist, explain-the-number, performance, measurement, hillclimb, eval, decision-tsv] created: 2026-10-21 updated: 2026-10-21 confidence: high sources: ["raw/github_doc-pstack-skills-benchmark-checklist-skill-md.md", "raw/github_doc-pstack-skills-principle-explain-the-number-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-hillclimb-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-eval-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-perf-issue-md.md", "raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md", "raw/github_doc-pstack-docs-guide-05-build-and-clean-md.md", "raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md", "raw/github_doc-pstack-docs-guide-09-make-it-yours-md.md", "raw/github_doc-pstack-readme-md.md"] --- # Benchmarks and Numbers: /benchmark-checklist, Explain the Number, Hillclimb, Eval ## Definition pstack treats every measured number (a speedup, a regression, a throughput, a latency, an eval result) as a claim that must be vetted before anyone reports or acts on it. - **Explain the Number** (principle): "Ask 'why not double?'" Name the resource or code path that bounds the result, using a profile or system counters, not a guess from reading code. List what else the number could be measuring and rule each out with evidence. Keep the run count, spread, and limiter with the number. "If you cannot say why the number is not twice as good, you do not know what you measured." - **`/benchmark-checklist`**: the working form of that principle for performance numbers. Seven questions, each answered with evidence from a run. - **Hillclimb playbook**: sustained improvement of one metric through a frozen, vetted harness. - **Eval playbook**: measures how a skill or prompt change affects agent behavior, blinded. ## How It Works ### Before running (benchmark-checklist) Write the claim you expect to ship ("export is 30% faster at p50 on the 60k-row dataset"). Read the measurement script. Check load with `uptime` and cores with `nproc`. If the machine is busy and you can't stop the load, interleave the sides and say so. ### The seven questions 1. **Why not double?** Name the limiter. Profile in a run you don't report, with `top`, `pidstat`, `node --cpu-prof`, `py-spy`, `perf`, or `strace -c`. Watch the load generator: if it saturates first, you measured the load generator. 2. **Was it tuned?** Run every side the way production runs it (release builds, production flags, pools, warm or cold caches as production sees them). One side on defaults means you compared configurations. If you can't tune it, don't pick a winner. 3. **Did it break limits?** Do the arithmetic against disk, network, and cores. "Removing a piece that takes 10% of the run can make the run at most about 11% faster." 4. **Did it error?** Count failures and check output correctness. Rejections are fast; timeouts and retries are slow. 5. **Does it reproduce?** **At least 5 runs per side, alternating A, B, A, B.** Report the median and range. A gap smaller than run-to-run variation is no difference. For a close call, use a rank-sum test or the harness's statistics. 6. **Does it matter?** Measure the end-to-end path a user waits on, and report the micro result as a share of it. 7. **Did it even happen?** Confirm the work ran inside the timed region. Watch for lazy generators, unawaited promises, results the JIT discards, and timeouts. ### Report Lead with the verdict: **faster, slower, no measurable difference, or inconclusive**. Give the number with unit, run count, range, and limiter, e.g. "p50 41 ms → 33 ms, median of 7 runs per side, range 32 to 35 ms after, bound by JSON parsing on one core." The verdict is **inconclusive** when you claim a difference but can't name the limiter, when a side ran untuned, or when you couldn't check questions 4 and 7 (name the gap). A PR body keeps one primary number; runs and evidence go in a linked artifact. ### Hillclimb playbook "One change, one measurement, keep or revert." 1. Ground with `how`, pick a case that reproduces the complaint (if none does, fix the repro first), and fix a metric, a direction, and a stop predicate pairing a target with a **floor on attempts** (e.g. "at least 50% better than baseline and at least 10 iterations"). 2. Build the harness, prove it can tell contrasting workloads apart, vet it with `benchmark-checklist`, make it print error and work counts, then **freeze** it. Record the baseline and a green regression gate. 3. Keep a gitignored `decision.tsv` via `show-me-your-work`, one row per attempt: id, hypothesis, change, before, after, delta, tests, verdict, note. See [[concepts/decision-logs]]. 4. Each hypothesis names a specific mechanism. For perf, order hypotheses by the performance mantras from the Perf issue playbook. 5. Loop: delegate one change to the hillclimb model (default `grok-4.7-xhigh-fast`), parallel worktrees for independent hypotheses; accept only past noise with a green gate, otherwise revert in full; one commit per accepted fix with `git add `, never `-A`. 6. Push past the first plateau (pivot category, combine near-misses). Correctness and simplicity outrank the number. 7. Stop at the predicate. Never relax it. 8. Opening a PR with accepted commits stacked in order. Reply: metric and target, baseline → final with percent delta, iterations kept vs. reverted, `decision.tsv` path, next idea. ### Perf issue vs. Hillclimb Perf issue is a one-off fix tied to a baseline trace that is vetted, with every later number, by `benchmark-checklist`. Hillclimb vets its harness before freezing; the frozen harness then prints error and work counts, so each keep-or-revert "checks questions 4 and 7 for free". See [[concepts/build-and-clean]]. ### Eval playbook (measuring agent behavior) Blinding non-negotiables: none of `eval`, `test`, `judge`, `experiment`, `rubric`, `score`, `compare`, `benchmark`, `candidate`, or `arena` in anything the candidate sees; an organic-looking prompt; no chain-eliciting cues; sanitized directory names; candidates never told others exist; the judge sees sanitized labels only, never model names; one judge scores both variants in one pass. Steps: frame plus a 3 to 6 criterion rubric held back from candidates, sanitized environments, one organic prompt, N candidates on different models (arena Phase B), one blinded judge on a different family (arena Phase C), grade chain-following from transcripts of which files were actually read, then read every output yourself. For eval results the principle asks: did every run do the task, does the gap hold across trials and models, does the scenario matter? ## Key Parameters | Parameter | Value | |---|---| | Minimum runs per side | 5, alternating | | Quick ballpark | 1 run allowed if the user asked for one; still check questions 4 and 7 and say it is one run. "A choice between options is never a ballpark." | | Verdicts | faster / slower / no measurable difference / inconclusive | | Hillclimb model | default `grok-4.7-xhigh-fast` | | Hillclimb log | `decision.tsv`, gitignored | | Eval rubric | 3 to 6 criteria, judge-only | ## When To Use - `/poteto-mode` already runs the checklist inside Perf issue and Hillclimb. Type it yourself when you measured something outside them, or when someone else's number looks too good: `/benchmark-checklist vet the export speedup before it goes in the pr`. - One metric to push over many iterations → Hillclimb. A one-off regression → Perf issue. - A skill or prompt change → Eval playbook ([[concepts/make-it-yours]]). ## Risks & Pitfalls - **Trusting an unvetted number.** Recipes guide: "A warm cache or a skipped code path can fake a speedup." - **Untuned comparisons.** Narrowing the claim to "the code as it ships today" doesn't fix it when the user is choosing what to adopt. - **Results past a physical limit** measured a cache, a no-op, or a bug. - **Telltale skip:** no run count, no spread, or no named limiter, or time saved larger than the time the changed piece took. - **Hillclimb:** stacking untested changes, claiming wins from code inspection, relaxing the predicate, quitting while cheap hypotheses remain. - **Eval observer effect:** an agent that knows it is evaluated behaves differently. Grade from files actually read, not self-report. If you disagree with the judge, suspect the rubric first (guide chapter 09; the playbook itself says disagreement means "a model is biased or the rubric is ambiguous"). ## Related Concepts [[concepts/build-and-clean]], [[concepts/verification-skills]], [[concepts/decision-logs]], [[concepts/make-it-yours]], [[summaries/principles-catalog]], [[summaries/playbook-catalog]]. ## Sources - raw/github_doc-pstack-skills-benchmark-checklist-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/benchmark-checklist/SKILL.md) - raw/github_doc-pstack-skills-principle-explain-the-number-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/principle-explain-the-number/SKILL.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-hillclimb-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/hillclimb.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-eval-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/eval.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-perf-issue-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/perf-issue.md) - raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/06-verify-and-ship.md) - raw/github_doc-pstack-docs-guide-05-build-and-clean-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/05-build-and-clean.md) - raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/10-recipes-and-pitfalls.md) - raw/github_doc-pstack-docs-guide-09-make-it-yours-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/09-make-it-yours.md) - raw/github_doc-pstack-readme-md.md (https://github.com/cursor/plugins/blob/main/pstack/README.md) --- title: "Build and Clean: Build Playbooks, /tdd, /no-comments, /blast-radius, TypeScript Rules" type: concept tags: [build, bug-fix, feature, refactoring, perf, tdd, no-comments, comment-sicko, blast-radius, typescript] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-docs-guide-05-build-and-clean-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-feature-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-bug-fix-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-refactoring-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-perf-issue-md.md", "raw/github_doc-pstack-skills-tdd-skill-md.md", "raw/github_doc-pstack-skills-no-comments-skill-md.md", "raw/github_doc-pstack-agents-comment-sicko-md.md", "raw/github_doc-pstack-skills-blast-radius-skill-md.md", "raw/github_doc-pstack-skills-typescript-best-practices-skill-md.md", "raw/github_doc-pstack-skills-typescript-best-practices-references-patterns-.md", "raw/github_issue-pstack-483-pstack-comment-sicko-agent-name-has-a-space-and-grok-rejects.md", "raw/github_issue-pstack-474-principle-test-behavior-not-implementation-listed-matchers-d.md"] --- # Build and Clean: Build Playbooks, /tdd, /no-comments, /blast-radius, TypeScript Rules ## Definition Guide chapter 05 ("Build the change and clean the diff"): the build playbooks share one discipline. You say what you observed, and the playbook demands the evidence. A cleanup pass then keeps the diff reviewable. The skills in this layer: - **Build playbooks** under `/poteto-mode`: Bug fix, Feature, Refactoring, Perf issue (plus Hillclimb, Runtime forensics, Trace forensics). - `/tdd`: failing test first, when the test path is cheap. - `/no-comments`: hands comments to the **Comment Sicko** agent, a reviewer that didn't write them. - `/blast-radius`: what a change breaks *elsewhere*, with the key safety fact proven by running code. - `/typescript-best-practices`: concrete type-system rules for `.ts`/`.tsx`. ## How It Works ### Prompting each playbook (verbatim guide examples) ```text /poteto-mode this command emits two records after a retry. repro first, then fix and verify. /poteto-mode add a --json flag. text output stays byte-identical. verify both forms. /poteto-mode move parsing into one module, zero behavior change. record the current output first and prove it's unchanged after. /poteto-mode startup takes 1.8s on this fixture. trace it, fix the measured cause, show me before and after. ``` The playbook supplies the unstated steps: reproduce before fixing, name the data shape before implementing, pin behavior before restructuring, profile before optimizing. ### The playbooks - **Bug fix.** "Every shipped line traces to runtime evidence." (1) Reproduce it yourself on the matching surface; ask the user only with a specific reason the control surface can't reach. (2) Binary-search the cause with hypotheses seeded by `how` and `why`; instrument rather than guess; Cursor's `/loop` for long hunts. (3) `architect` first if the fix crosses a function boundary; delegate to the bug-fix model. (4) Verify on the same surface; "Inconclusive" or wrong-surface is not a pass. (5) Stage commits so the failing repro lands before the fix in git history (`tdd` cadence when the bug has a cheap local test path; skip it when the test would be expensive, integration-heavy, or unclear). (6) Opening a PR. Reply pastes failing-then-passing output verbatim. - **Feature.** `how` → `architect` → a four-item **throughput checkpoint** (Blocking first steps, Independent workstreams, Shared mutable state, Smallest safe decomposition; non-applicable items stay with `n/a: `). Delegating code-writing to a subagent is **mandatory** (the gain is review separation); use `arena` when several shapes are valid. Verify, rebase into small ordered commits, `interrogate` if the design is contested, then Opening a PR. - **Refactoring.** "The structure changes. The behavior does not." Pin behavior first with a characterization test, snapshot, or equivalence harness ("Type check and lint are not a pin"). Subtract before adding; migrate every caller and delete the old API in the same wave (no shims). Spot-check renames, which miss usages in strings and prose. Prove equivalence on the real artifact. If the diff doesn't reduce reader load, revert it. Large or cross-cutting work belongs to `/figure-it-out` ([[concepts/make-it-yours]]). - **Perf issue.** Baseline trace first, vetted with `benchmark-checklist`. Apply the performance mantras cheapest first: Don't do it; Do it, but don't do it again; Do it less; Do it later; Do it when they're not looking; Do it concurrently; Do it cheaper. Stop when one meets the target. Reply: baseline, post-fix, delta, artifact path. Sustained metric work goes to Hillclimb ([[concepts/benchmarks-and-numbers]]). - **Runtime / Trace forensics** return a diagnosis, not a fix (live process vs. an already-captured profile such as a cpuprofile). ### /tdd Six steps: understand the bug; choose the narrowest existing executable check; write the smallest failing test; run it and confirm it fails *for the intended reason*; make the smallest fix; rerun. If a test needs broad harness setup, brittle mocks, slow E2E, production-only state, or large fixture churn, use the closest executable check instead (script, repro command, browser automation, snapshot, log assertion). "Prefer no new test over a bad test." In context, `/tdd implement` can be the whole prompt. ### /no-comments and Comment Sicko Scope: the caller's files or diff, else the current diff against the base branch (default `main`) including the working tree. Steps: spawn `Task` with `subagent_type: "comment-sicko"`; audit its report (reject application-code edits, scope escapes, misstated `MUST KILL` reasons; run `/how` or `/why` before accepting thin `IMPORTANT`/`do not remove` claims); fix trivial flags directly, or run `/architect` once (stop at the sketch) when a fix needs a shape; implement the smallest root-cause fix in scope, never symptom guards; for constraint comments, offer a type, runtime check, test, or CI lint encoding and wait for approval (unattended runs need caller pre-approval), then delete. A rejected report is rerun once; a second rejection fails `/no-comments`. Comment Sicko (the guide calls it a read-only reviewer; the agent file says "Report only" and has it delete comments while never writing application code; opens with "Yes... Ha ha ha... Yes!") keeps only: legal/license headers; non-obvious behavior forced by an external dependency, platform, vendor, or protocol; `// prettier-ignore`; doc comments defining a public API contract; issue or RFC links explaining a constraint code can't express. "When I am not sure a keep clause applies, the comment dies." Surprises in *our own* code get deleted and the symbol marked `MUST KILL` for a rename, extract, type, or rearchitecture. `eslint-disable`, `@ts-ignore`, `@ts-expect-error` die when the rule protects correctness or safety. It never writes application code. ### /blast-radius "Listing the callers is not the job." Find the one fact the change is safe because of, then prove it as far down this ladder as is cheap: 1 you said so; 2 you pointed at the line (`file:line`); 3 you showed the bad case can't happen; 4 you ran it (a script calling the real code); 5 you reproduced it in the running app. Look where grep stops: library source and pinned version, timing (microtasks, teardown), JSON/DB/wire formats, feature flags, code three hops downstream. For big changes, run it as an `arena`. Hand back: What it does, The one fact (proven or "unproven"), Risks, Cleared, Before you merge. ## Key Parameters | Item | Value | |---|---| | Bug-fix / feature / refactoring / perf-issue delegate models | each default `grok-4.7-xhigh-fast` | | `/no-comments` base branch | `main` | | Comment Sicko spawn id | `subagent_type: "comment-sicko"` | | `typescript-best-practices` paths | `["**/*.ts", "**/*.tsx"]`, but `disable-model-invocation: true`, so type it by name | | TS rules | discriminated unions (`kind`), branded types (`& { readonly __brand: "X" }`), constructive modeling (`[T, ...T[]]`), `unknown` over `any`, schemas before guards (`z.infer`), no `as`, narrowing hierarchy, exhaustiveness (`const _exhaustive: never = x;`), `satisfies` over `as`, boundary validation, schema-derived types, object args, real tests, structured telemetry (no `console.log`) | Examples for each TS rule live in `references/patterns.md`. ## When To Use - Bug with a cheap local test → `/tdd`; otherwise Bug fix via [[concepts/poteto-mode]]. - `.ts`/`.tsx` work → type `/typescript-best-practices` ("It doesn't load on its own"). - Before review → `/no-comments the diff`. Code slop → `/deslop` (in the `cursor-team-kit` plugin, not pstack). Prose slop → `/unslop` ([[concepts/technical-writing-and-unslop]]). - A small diff you don't trust → `/blast-radius`. A broader review → [[concepts/code-review-with-interrogate]]. ## Risks & Pitfalls - **Cleanup is not optional polish.** Narrating comments and defensive dead weight read as unfinished, "and the extra code is where the next bug hides". Say `deslop it` before committing. - **Authors defend their own comments**; that's why `/no-comments` uses a separate reviewer. - **Comment Sicko spawn name (issue #483, closed as completed as of fetch 2026-10-21).** In pstack 0.15.5/0.15.6 the agent's name was `Comment Sicko` (with a space); Grok Build's `spawn_subagent` rejected `pstack:Comment Sicko`. A commenter (deanrie) said the space worked in Cursor and pointed to #486 renaming it to `comment-sicko`, which is the id the current skill uses. - Forcing a bad test (mocks, implementation details, timing) is worse than none. `/tdd` guardrail: don't change tests merely to match a wrong implementation, and don't weaken existing assertions unless the expected behavior genuinely changed. - Unit tests show branch behavior, not bug absence; a blast-radius writeup "that sounds right is worthless" without a proven fact. - **Vacuous-test heuristic was inaccurate.** Issue #474 (open as of fetch 2026-10-21) showed that matchers the `principle-test-behavior-not-implementation` skill listed as passing on `undefined` (`toBeDefined`, `toBeTruthy`, `toBeInstanceOf`, `toBeGreaterThan(0)`, `toEqual([])`, `toHaveLength(0)`) actually fail or throw. A later commenter reported that #633 (merged Oct 14) removed the matcher list from main. Judge a test by whether it would catch a wrong but plausible value, not by matcher name. ## Related Concepts [[concepts/design-before-code]], [[concepts/verification-skills]], [[concepts/shipping-prs-and-watch-pr]], [[entities/poteto-agent-and-comment-sicko]], [[summaries/playbook-catalog]], [[summaries/principles-catalog]]. ## Sources - raw/github_doc-pstack-docs-guide-05-build-and-clean-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/05-build-and-clean.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-feature-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/feature.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-bug-fix-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/bug-fix.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-refactoring-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/refactoring.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-perf-issue-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/perf-issue.md) - raw/github_doc-pstack-skills-tdd-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/tdd/SKILL.md) - raw/github_doc-pstack-skills-no-comments-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/no-comments/SKILL.md) - raw/github_doc-pstack-agents-comment-sicko-md.md (https://github.com/cursor/plugins/blob/main/pstack/agents/comment-sicko.md) - raw/github_doc-pstack-skills-blast-radius-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/blast-radius/SKILL.md) - raw/github_doc-pstack-skills-typescript-best-practices-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/typescript-best-practices/SKILL.md) - raw/github_doc-pstack-skills-typescript-best-practices-references-patterns-.md (https://github.com/cursor/plugins/blob/main/pstack/skills/typescript-best-practices/references/patterns.md) - raw/github_issue-pstack-483-pstack-comment-sicko-agent-name-has-a-space-and-grok-rejects.md (https://github.com/cursor/plugins/issues/483) - raw/github_issue-pstack-474-principle-test-behavior-not-implementation-listed-matchers-d.md (https://github.com/cursor/plugins/issues/474) --- title: "Code Review with /interrogate" type: concept tags: [interrogate, code-review, multi-model, adversarial-review, rubric, lead-judgment, reflect] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-skills-interrogate-skill-md.md", "raw/github_doc-pstack-skills-interrogate-references-rubric-md.md", "raw/github_doc-pstack-skills-interrogate-references-code-quality-review-md.md", "raw/github_doc-pstack-skills-interrogate-references-lead-judgment-md.md", "raw/github_doc-pstack-skills-interrogate-references-reviewer-prompt-md.md", "raw/github_doc-pstack-docs-guide-04-design-md.md", "raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md", "raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-skills-reflect-skill-md.md", "raw/github_issue-pstack-335-pstack-default-task-model-slugs-are-unresolvable-in-current-.md", "raw/github_issue-pstack-601-pstack-claude-code-and-codex-mapping-for-cursor-specific-ins.md", "raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-feature-md.md"] --- # Code Review with /interrogate ## Definition `/interrogate` is pstack's multi-model adversarial review. It spawns **one reviewer per configured model**, all reviewing the same diff, intent, and rubric. "The adversarial signal comes from model diversity, not assigned personas." Different model families have different blind spots, so a finding that two models raise independently is the strongest signal. The output is a synthesized verdict sorted into four buckets. It **never auto-applies changes**. The README describes it as the tool for when "you have a diff and want different models to try to break it, including a strict code-quality lens." ## How It Works 1. **Scope.** Use the files or diff the user points at. On a feature branch, `git diff main...HEAD` (or the right base). Package surrounding context files the reviewers need. 2. **Intent.** State the intent in one paragraph from the user's message, commit messages, PR description, and code. If unsure, ask the user first. Reviewers are told: "Do NOT question the intent itself", only the execution. 3. **Spawn reviewers.** All in one message with the Task tool, labelled Reviewer A, B, ... per entry on the `interrogate reviewers` line. Each gets `subagent_type: generalPurpose`, `readonly: true`, and the same prompt built from `references/reviewer-prompt.md` + `references/rubric.md` + `references/code-quality-review.md`. 4. **Synthesize.** Merge findings that describe the same issue, note which models raised each, and record disagreements. 5. **Lead judgment.** The lead is "a pragmatic senior engineer, not a neutral aggregator". It buckets every finding with the model(s) that raised it and a one-line rationale: - **Act on**: real correctness, security, or maintainability issues that would block a real PR. - **Consider**: legitimate but maybe not worth the cost now. - **Noted**: valid but not actionable (context-dependent, premature optimization, low impact). - **Dismissed**: wrong, nitpicky, or missing context, with a brief reason. **Output sections:** Intent, Reviewers (model + finding count each), Act On, Consider, Noted, Dismissed, Agreement Map. ### Reviewer prompt Each finding has a **Severity** (`critical` | `warning` | `nit`), **Finding** (specific lines or functions), **Evidence**, and an optional **Suggestion**, under `## Findings` / `### 1. [Severity] Short title` with **Location**. Reviewers must not praise the code or restate it, and should not force lenses that don't apply. "An empty review is a valid outcome"; reply "no findings" and stop. ### Rubric lenses (`references/rubric.md`) - **Correctness:** edge cases, error handling, off-by-one, races, idempotency ("what happens if this operation runs twice"), concurrency. Trace the execution path, don't just flag "could be nil". - **Root causes vs. symptoms:** guards masking invariant violations, retries hiding broken contracts, casts silencing modeling errors, "don't do X" comments that should be a type, lint, or runtime check. - **Structural integrity:** boundary discipline, coupling, data-model fit, bolted-on vs. integrated, legacy dual-paths. "Premature abstraction is worse than duplication." - **Verification:** tests of behavior vs. implementation, a test for the bug, checking the real thing rather than a proxy, verifying artifacts rather than self-reports. - **Complexity budget:** single-call-site abstractions, speculative config, dead code, obsolete compat paths. "Simpler is better unless simpler is wrong." - **Security:** trace input to sinks (SQL, shell, eval, innerHTML), auth gaps, secrets in logs, TOCTOU. ### Code-quality lens (`references/code-quality-review.md`) "Be ambitious about code structure." Look for **"code judo"** moves: restructurings that keep behavior while making whole branches, helpers, or layers disappear. Presumptive blockers unless justified: - incidental complexity a code-judo move would delete; - a PR that **pushes a file from below 1000 lines to above 1000 lines**; - ad-hoc branching tangling an existing flow, or feature checks scattered across shared code; - unnecessary abstractions, wrappers, or cast-heavy contracts, duplicated helpers, logic in the wrong layer. Also flagged: needless sequential orchestration and non-atomic updates. Tone: "direct, serious, and demanding". ### Lead-judgment filters (`references/lead-judgment.md`) - **Nitpick gravity:** reviewers inflate nits to fill a review. All-nits means the code is probably fine. - **Hypothetical vs. actual:** "what if null" counts only if a caller can actually pass null. Trace it. - **Premature abstraction warnings:** dismiss unless the code needs to change a second way. - **"I would have done it differently":** the most common false positive. Dismiss unless a concrete problem is shown. - **Missing context:** suggestions on unmodified code, or flags on codebase-consistent patterns. - Reviewers are right when several models agree, a concrete execution path is shown, or the finding exposes a gap in your mental model. Be especially careful dismissing security and correctness findings, even from one model. ## Key Parameters | Setting | Value | |---|---| | Model line | `interrogate reviewers` in `~/.cursor/rules/pstack-models.mdc` (written by `/setup-pstack`) | | Default Reviewer A | `claude-opus-5-5-xhigh` | | Default Reviewer B | `grok-4.7-xhigh-fast` | | `auto` / `inherit-parent` | omit `model`; that reviewer runs on the parent model | | Rejected slug | run on the family default and say so. Families: `claude-*`; `grok-*` with `cursor-grok-*` and `composer-*`. Refused `composer-*` → Reviewer B default; no family match → Reviewer A default. If a table default is rejected, use the closest valid slug from the error and open a separate PR to update the table. Don't block the review on it. | | Base branch | `main` by default | ## When To Use - On a **diff**, not an abstract plan. The design guide warns that reviewers pointed at a code-less plan "invent theoretical risks and edge cases that will never happen." - A small finished change you're unsure about (`/interrogate` alone), or a contested, expensive-to-reverse design after `/architect` and before shipping ([[concepts/design-before-code]]). `/poteto-mode` routes "contested design" here, and the Feature playbook runs it when the design is contested. - Verbatim recipe: `/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's an actual bug or regression in behavior.` "don't change anything yet" keeps it read-only, and the nitpick rule pre-filters noise. README shorthand: `/interrogate review this pr.` **How `/reflect` differs.** `/reflect` also fans out three reviewers, but it reviews the *session transcript*, not code. Its lenses are assigned (Judgment and Divergent default `claude-opus-5-5-xhigh`, Tooling default `grok-4.7-xhigh-fast`), and it runs in agent mode (`readonly: false`) because its reviewers need MCP access. Its synthesizer returns Accepted / Rejected / Backlog skill edits rather than review buckets. See [[concepts/make-it-yours]]. ## Risks & Pitfalls - **Accepting every comment.** The recipes guide lists this as a pitfall ("you can override either way"). The design guide adds: "Read the dismissals too. The lead is a pragmatic senior engineer, not an oracle, and you can override it." - **Same-family panel.** The value comes from model diversity. Issue #601 (open, as of fetch 2026-10-21) describes a third-party adaptation that keeps the panel cross-family outside Cursor by running the second seat through the other harness's CLI (`codex exec` from Claude Code, `claude -p` from Codex). The author reports `/interrogate` ran end to end in both. See [[syntheses/pstack-on-claude-code]]. - **Unspawnable default slugs.** Issue #335 (open, as of fetch 2026-10-21) reports baked-in Task model slugs that Cursor's allow-list rejects. A comment by deanrie on pstack 0.15.6 found `grok-4.7-xhigh-fast` resolving while `claude-opus-5-5-max` and `gpt-5.6-sol-max` did not. The current interrogate skill's table names `claude-opus-5-5-xhigh`, not `-max`; nobody tested `-xhigh` directly, but the issue body reports that Task "still does not expose `-max` / `-xhigh` even when those models are selected in the picker", so expect the default to be rejected and the skill's fallback rule to fire. - **Intent drift.** If the stated intent is wrong, every reviewer evaluates against the wrong goal, so ask when unsure. ## Related Concepts [[concepts/design-before-code]], [[concepts/build-and-clean]] (`/blast-radius` for a small diff you don't trust), [[concepts/shipping-prs-and-watch-pr]], [[concepts/installation-and-model-setup]], [[syntheses/recipes-and-pitfalls]], [[summaries/known-issues]]. ## Sources - raw/github_doc-pstack-skills-interrogate-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/interrogate/SKILL.md) - raw/github_doc-pstack-skills-interrogate-references-rubric-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/interrogate/references/rubric.md) - raw/github_doc-pstack-skills-interrogate-references-code-quality-review-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/interrogate/references/code-quality-review.md) - raw/github_doc-pstack-skills-interrogate-references-lead-judgment-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/interrogate/references/lead-judgment.md) - raw/github_doc-pstack-skills-interrogate-references-reviewer-prompt-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/interrogate/references/reviewer-prompt.md) - raw/github_doc-pstack-docs-guide-04-design-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/04-design.md) - raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/10-recipes-and-pitfalls.md) - raw/github_doc-pstack-readme-md.md (https://github.com/cursor/plugins/blob/main/pstack/README.md) - raw/github_doc-pstack-skills-reflect-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/reflect/SKILL.md) - raw/github_issue-pstack-335-pstack-default-task-model-slugs-are-unresolvable-in-current-.md (https://github.com/cursor/plugins/issues/335) - raw/github_issue-pstack-601-pstack-claude-code-and-codex-mapping-for-cursor-specific-ins.md (https://github.com/cursor/plugins/issues/601) - raw/github_doc-pstack-skills-poteto-mode-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-feature-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/feature.md) --- title: "Decision Logs (/show-me-your-work and log.sh)" type: concept tags: [show-me-your-work, decision-log, audit-trail, tsv, overnight, review] created: 2026-10-21 updated: 2026-10-21 confidence: high sources: ["raw/github_doc-pstack-skills-show-me-your-work-skill-md.md", "raw/github_doc-pstack-skills-show-me-your-work-scripts-log-sh.md", "raw/github_doc-pstack-skills-show-me-your-work-references-decision-log-temp.md", "raw/github_doc-pstack-docs-guide-07-overnight-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autonomous-run-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-full-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-pause-safely-md.md", "raw/github_doc-pstack-skills-principle-prove-it-works-skill-md.md"] --- # Decision Logs ## Definition `/show-me-your-work` keeps **one canonical, reviewable decision trail** for long-running or unattended work: a single TSV file with one row per decision (what, why, evidence, result). It is user-invoked (`disable-model-invocation: true`), and other skills and playbooks route their audit trail to it by name instead of inventing their own. Guide 07 calls it "what makes the run reviewable" after an overnight run. ## How It Works ### The format Start from `references/decision-log-template.tsv`, which is just the header row: ```text ts phase decision why evidence result ``` | Column | Content | |---|---| | `ts` | ISO8601 timestamp | | `phase` | the phase or workstream | | `decision` | what was chosen or done, one line | | `why` | the reason in plain words (name a principle plainly, not as a jargon tag) | | `evidence` | a pointer, never a paragraph: commit SHA, PR number, `file:line`, artifact/trace/screenshot path | | `result` | outcome or predicate state, e.g. `tests green`, `reverted`, `pixel-diff 0`, `INCONCLUSIVE`, `open` | Cells stay single-line. Write rows the way you'd tell a teammate; `/unslop` applies to log text too (see [[concepts/technical-writing-and-unslop]]). ### Logging a row with log.sh ```bash scripts/log.sh ``` From the script source: - Requires exactly 6 arguments; otherwise prints the usage line and exits 1. - Creates the log's parent directory if missing. - Writes the header row if the file is empty or missing (always appends with `>>`, never `>`, so a flaky network mount costs at most a stray header, not rows). - Stamps `ts` itself as UTC `date -u +%Y-%m-%dT%H:%M:%SZ`; you pass the other five cells. - Replaces tabs, newlines and CRs in each cell with spaces. - Prefixes any cell starting with `=`, `+`, `-` or `@` with a single quote, so evidence such as PR titles or filenames can't become a spreadsheet formula. A bare `printf` append also works, but then you must handle those same bytes yourself. ### What to log Decision points and checkpoints, not every action: a fork chosen, a unit completed with its verification result, a pivot or revert and its trigger, a blocker surfaced, a gate fixed. For loop runs, one row per iteration. **Runs and `start` rows.** A run is one agent conversation (including later turns). A pickup, replacement agent or new chat is a new run. When a run adds to a log that already has rows, its first row has phase `start`, naming the `ts` range of prior rows it didn't write, with its agent id as evidence. `start` is used for nothing else. ### Audit and cross-model review (before handing back) 1. **Audit the log against the transcript**: read this run's transcript under the active workspace's `agent-transcripts/` (never glob `~/.cursor/projects/*/`), check each row maps to a real decision and its evidence resolves, add rows for unlogged forks or pivots. "Correct the log, not the story": never edit or delete a row; supersede it. 2. **Cross-model review**: spawn a subagent on a *different model family* to read the trail and transcript and flag weak evidence, skipped verification, risky choices and gaps. 3. Every reply for a run with a trail ends with an **"Attention"** section, led by `reviewed by `; "No flags" is valid. Render in a terminal with `column -s$'\t' -t decisions.tsv`; GitHub renders a committed TSV as a table. ## Key Parameters | Item | Value | |---|---| | Default path | `decisions.tsv` in the work dir | | Parallel efforts | `.audit/.tsv` | | Committed? | No by default; leave it out of git | | Rule | append-only; never edit or delete history | | Orchestrate store file | `decisions.tsv` inside `orchestrate//` | | Morning prompt | `/show-me-your-work catch me up on what you did last night` | ## When To Use - **When to commit it:** "only when the work is ambitious enough that a reviewer needs the trail to trust the result." The Prove It Works principle gives a similar rule (commit only for large or complex work where the trail must be auditable later), citing a big port or migration as the example. - **Overnight and autonomous runs** (see [[syntheses/overnight-and-autonomous-runs]]): Autonomous run checkpoints every iteration with a row for what changed and whether the predicate moved; guide 07's loop is "One change, one check, one log row, every iteration." Autopilot-full owners start a trail in the root agent's store soon after starting ("Assume the VM dies"). Orchestrate keeps `decisions.tsv` in its store and audits the trail, including its cross-model review, at Close. `/figure-it-out` wires the decision log in when work will be reviewed after you step away. - **Pauses:** Pause safely's resume note points at an existing trail instead of duplicating it. - For a quick read-only status rather than an audit, guide 07 suggests `/ketchup`. ## Risks & Pitfalls - **Evidence must be a pointer**, ideally produced by committed scripts; a paragraph is not evidence. - **Self-review is not a substitute** for the cross-model reviewer. - **Don't glob across `~/.cursor/projects/*/`** during the audit; that reads unrelated private chats. - **Hand-rolled appends** skip log.sh's tab stripping and formula-prefix protection. - **A row may be wrong**; the audit adds a superseding row rather than rewriting history, so read later rows before trusting an early one. ## Related Concepts - [[syntheses/overnight-and-autonomous-runs]] · [[concepts/orchestration-and-multi-phase-plans]] · [[concepts/verification-skills]] · [[concepts/poteto-mode]] · [[summaries/skill-catalog]] ## Sources - raw/github_doc-pstack-skills-show-me-your-work-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/show-me-your-work/SKILL.md) - raw/github_doc-pstack-skills-show-me-your-work-scripts-log-sh.md (https://github.com/cursor/plugins/blob/main/pstack/skills/show-me-your-work/scripts/log.sh) - raw/github_doc-pstack-skills-show-me-your-work-references-decision-log-temp.md (https://github.com/cursor/plugins/blob/main/pstack/skills/show-me-your-work/references/decision-log-template.tsv) - raw/github_doc-pstack-docs-guide-07-overnight-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/07-overnight.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-autonomous-run-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/autonomous-run.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-full-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/autopilot-full.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/orchestrate.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-pause-safely-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/pause-safely.md) - raw/github_doc-pstack-skills-principle-prove-it-works-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/principle-prove-it-works/SKILL.md) --- title: "Design Before Code: /architect, /arena, /swarm, Prototypes" type: concept tags: [architect, arena, swarm, prototype, design, red-flags, exhaust-the-design-space] created: 2026-10-21 updated: 2026-10-21 confidence: high sources: ["raw/github_doc-pstack-docs-guide-04-design-md.md", "raw/github_doc-pstack-skills-architect-skill-md.md", "raw/github_doc-pstack-skills-architect-references-design-red-flags-md.md", "raw/github_doc-pstack-skills-architect-references-rationale-template-md.md", "raw/github_doc-pstack-skills-architect-references-runner-prompt-md.md", "raw/github_doc-pstack-skills-arena-skill-md.md", "raw/github_doc-pstack-skills-swarm-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-prototype-md.md", "raw/github_doc-pstack-skills-principle-exhaust-the-design-space-skill-md.md"] --- # Design Before Code: /architect, /arena, /swarm, Prototypes ## Definition Guide chapter 04 ("Design before you write code") targets two mistakes: taking the agent's first design, and polishing a plan no code has tested. pstack's answer is to **plan through code**: prototypes answer open questions, a README or tutorial sets the target, and a written plan comes last. - `/architect` sketches types, signatures and module boundaries (with `not implemented` bodies) before implementation. - `/arena` runs N parallel attempts at one brief, picks a base, and grafts in the best parts of the losers. - `/swarm` fans N workers across slices or races for **coverage**, without arena's base/graft ceremony. - The **Prototype playbook** builds throwaway variants to decide a design from visible evidence. - The **exhaust-the-design-space** principle: for a novel UI interaction or architectural decision with no precedent, build 2 to 3 competing prototypes and compare side by side before committing (also applies to product design where experience depends on feel). ## How It Works ### /architect (phases: Ground, Sketch, Agree, Implement, Scrap) - **A. Ground.** Run `how` over every touched subsystem ("Naming a file isn't grounding"); add `why` when the design redefines ownership or layering. Skip only for genuinely greenfield work. - **B. Sketch.** Run `arena` with `references/runner-prompt.md` as each runner's prompt. "Design it twice": at least two structurally distinct candidates, whole-shape alternatives, not point fixes. Screen each against the design red flags. Prefer the deeper interface (more complexity hidden behind a smaller public surface). - **C. Agree (opt-in).** Default proceeds straight to implementation with no human checkpoint. Opt in with "/architect with checkpoint" or "stop and show me before implementing". Human pushback on the shape counts as Phase A evidence: re-ground and re-run Phase B. - **D. Implement** against the sketch; deviations are signal to surface, not friction to absorb silently. - **E. Scrap** when friction forms a *pattern*: the same workaround across unrelated code; many unrelated special-case branches; types needing `any`, casts, or always-set optional fields; a "we need a lock" reflex when the sketch said state wasn't shared; callers needing internal rules; two or more independent Phase D deviations of the same shape. Then re-run `how`, redesign from first principles, subtract before adding (new sketch smaller than the old), and return to Phase B. **Runner discipline:** caller's usage first (README-style usage plus two or three call sites, then derive types; reconcile the sketch to the usage); data structures first; no transport or wire types on the public API; per-actor state with a merge at the read boundary when two actors might write; invariants in types > runtime checks > comments; validate at boundaries; single source of truth; idempotent transitions; if tracing a flow needs more than three files, flatten. Runners should not hedge toward a "safe-looking middle". **Design red flags** (`references/design-red-flags.md`): shallow module, information leakage, temporal decomposition, pass-through method, split ownership, two ways to do one task, importable internals, hand-synced list. They assume the next contributor is an agent that copies the nearest example and takes the shortest path that compiles. **Rationale template** sections: Problem, Usage (caller's view, written first), Shape, Synthesis decision (filled by arena), Tradeoffs accepted ("we accept X in exchange for Y"), Alternatives considered (required, at least one), Open questions and risks, Next implementation step. ### /arena (phases: Frame, Fan out, Cross-judge, Pick, Graft, Verify) 1. **Frame:** same prompt for every candidate; a 3 to 6 criterion rubric that only the picker sees; each candidate gets its own git worktree or `/tmp/arena-/candidate-/`. 2. **Fan out:** all N in one message with `run_in_background: true`. A dropout means proceed with N-1 and note it. 3. **Cross-judge:** one readonly judge, preferably a different model family from the parent, spawned only after candidates finish. 4. **Pick:** read every candidate end to end and score criterion by criterion. Choose the base a future maintainer can extend most easily. 5. **Graft:** usually one or two things per loser, folded in by hand. Convergence means ship the consensus. Wild divergence means Phase A was under-specified: reframe, don't average. 6. **Verify** per prove-it-works. ### /swarm (phases: Frame, Fan out, Aggregate, Report) Declare the done predicate. Choose slices, a race, or both; for races declare `first pass`, `rank all`, or `best-of` before spawning. Workers spawn with `subagent_type: generalPurpose`, `environment: "cloud"`, `run_in_background: true` (`environment: "local"` only when the worker needs the user's computer; `cloud_base_branch` for a non-default pushed branch). Each reports `PASS`, `ISSUES`, or `BLOCKED` with evidence. A result missing its named SHAs and method is dropped and respawned once; a second miss is a gap, and "A gap does not count as a pass." ### Prototype playbook "You own the design decision, not the code." Scope the decision (no decision → route to Feature), gather references if the space is open, build throwaway in an isolated scratch dir (vanilla HTML/CSS/JS or the smallest script; no production framework, no tests), put variants behind one switcher, verify on the matching surface (screenshots, or logged timings and output), then present tradeoffs and a recommendation and hand off to Feature or `architect`. ## Key Parameters | Setting | Source | Default if missing | |---|---|---| | `architect runners` (replaces `arena runners` inside architect) | `pstack-models.mdc` | `claude-opus-5-5-xhigh` and `grok-4.7-xhigh-fast` | | `arena runners` | `~/.cursor/rules/pstack-models.mdc` | one each on `claude-opus-5-5-xhigh` and `grok-4.7-xhigh-fast` | | `arena cross-judge pool` | same | choose from `claude-opus-5-5-xhigh`, `grok-4.7-xhigh-fast` | | `swarm workers` | same | `grok-4.7-xhigh-fast` | | Arena rubric | Phase A | 3 to 6 criteria | `auto`/`inherit-parent` means omit `model`. Arena families go by prefix (`claude-*`; `grok-*` with `cursor-grok-*` and `composer-*`); a refused `composer-*` entry runs on `grok-4.7-xhigh-fast`. Panels come from `/setup-pstack` (see [[concepts/installation-and-model-setup]]) and can be adjusted per task, e.g. `/arena this, 5 candidates.` ## When To Use The guide's ladder ("Most changes need none of it"): - Small finished change you're unsure about → `/interrogate` alone ([[concepts/code-review-with-interrogate]]). - Crosses function boundaries or moves ownership → `/architect` (brings `/arena`). - Standalone decision (naming, formats, an algorithm) → `/arena` directly. - Coverage matrix, parallel checks, declared race → `/swarm`. - Answerable by running something → prototype, not debate. - Contested and expensive to reverse → `/architect`, then `/interrogate` before shipping. - Several PRs → a plan written after design settles (Multi-phase plan playbook; see [[concepts/orchestration-and-multi-phase-plans]]). pstack has no planning skill, on purpose. `/poteto-mode` already applies this ladder; boundary-crossing work triggers `/architect` on its own. For shared packages or APIs, write the README or tutorial first. ## Risks & Pitfalls - **Reviewing an abstract plan.** `/interrogate` belongs on a diff; on a code-less plan reviewers "invent theoretical risks". Note that the architect skill itself permits running `interrogate` on the synthesized sketch for adversarial pressure; the guide's warning targets plans with no code behind them. - **Patching a wrong design** instead of scrapping it (Phase E tells above). - **Averaging divergent arena candidates** instead of reframing. - **Migrations:** say "bugs included" so the migration doesn't quietly fix things and make old vs new output incomparable. - A plan's proof per PR can't be "a passing test suite alone". ## Related Concepts - [[concepts/understanding-code]] (grounding phase), [[concepts/build-and-clean]] (implementation playbooks), [[concepts/code-review-with-interrogate]], [[concepts/worktrees]], [[summaries/principles-catalog]], [[syntheses/which-skill-when]]. ## Sources - raw/github_doc-pstack-docs-guide-04-design-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/04-design.md) - raw/github_doc-pstack-skills-architect-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/architect/SKILL.md) - raw/github_doc-pstack-skills-architect-references-design-red-flags-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/architect/references/design-red-flags.md) - raw/github_doc-pstack-skills-architect-references-rationale-template-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/architect/references/rationale-template.md) - raw/github_doc-pstack-skills-architect-references-runner-prompt-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/architect/references/runner-prompt.md) - raw/github_doc-pstack-skills-arena-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/arena/SKILL.md) - raw/github_doc-pstack-skills-swarm-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/swarm/SKILL.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-prototype-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/prototype.md) - raw/github_doc-pstack-skills-principle-exhaust-the-design-space-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/principle-exhaust-the-design-space/SKILL.md) --- title: "Formal Verification Skills (/create- and /maintain-formal-verification-skill)" type: concept tags: [formal-verification, tla-plus, model-checking, drift, create-formal-verification-skill, maintain-formal-verification-skill] created: 2026-10-21 updated: 2026-10-21 confidence: high sources: ["raw/github_doc-pstack-skills-create-formal-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-maintain-formal-verification-skill-skill-md.md", "raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md"] --- # Formal Verification Skills ## Definition `/create-formal-verification-skill` generates a **project-local skill that formally verifies one property** of the code "where a bug costs the most and tests reach the least", in any language, with whichever verification tool fits. `/maintain-formal-verification-skill` brings that verification back in line after code changes that skipped it. Both are user-invoked (`disable-model-invocation: true`). A test checks the cases someone thought to write; formal verification checks every case in a stated scope: every order of steps in a model, every input up to a bound, or every input. Guide 06 positions it as the complement to [[concepts/verification-skills]]: those prove the paths you drive, while this reaches paths nobody drives (two overlapping retries, a lock that expires mid-write, a state change arriving out of order). ## How It Works ### Choosing the target Answered from the codebase; ask the user only what you cannot observe; if the user named an area or bug, start there. A good target is **a promise the code makes, where a break harms users and tests rarely reach the case that breaks it**. Choose the *strongest* such target in the repo, not the easiest to verify. Example from guide 06: ```text /create-formal-verification-skill the job lease and retry logic. a job must never run twice at once. ``` ### Tool selection ("Let the question choose the tool") Pick the tool that answers the question at the lowest cost: a model checker, a proof assistant, an SMT-backed verifier, or another tool. | Question | Usual fit (per source) | |---|---| | Can events happen in a bad order? | A model checker over a small model of the design; **TLA+ is the default for that in any language** | | Does the code itself behave for every input (memory safety, overflow, a data-structure invariant)? | A verifier that runs on the code | | No verifier runs on this language | Say so, and **test the real code with generated inputs**, not a hand model of the function | | Must hold at every size, where a bound is not enough | Can need a proof | Prefer a tool the repo's developers can install and run, and tell the user why you chose it. The source names no specific tool besides TLA+. ### Quality bar ("What makes it good") - **True to the code**: every part of the model or proof points to code a reviewer can open; one indivisible step in the verification is one indivisible step in the code; names come from the repo. - **Able to fail**: show each property failing on a broken variant (a removed check, a reordered step). - **Findings stay findings**: when current code breaks the property, report the counterexample; do not weaken the property or model, and do not change product code unless asked. - **Honest about scope**: bounds, assumptions, exclusions. - **Readable without the tool**: property and harm in one plain sentence each; counterexample as a short sequence of steps in the code's words. - **Cheap to rerun**: one command, a reproducible tool version, a short run. - **Kept in step with the code**: record which files and functions each check covers and the **sync commit** at which the verification was last confirmed to describe them. ### Generate, prove, hand off The generated skill needs frontmatter (or it never registers) and must let the next agent tell whether a change touches verified code, run the check, tell a real bug from a modeling error, and update the verification when a change is intended. Before handoff, follow it once on a **scratch change that breaks the property** in real code; it must catch the break. Then drop the scratch change and confirm the check is back where it started. If the skill misses the break, fix the skill or verification, not the scratch change. Handoff covers: what was verified, which tool and why, bounds, findings in plain words, how to run it, what it does not cover. ### /maintain-formal-verification-skill pass 1. **Find the checks** by what they do (a verify skill has no fixed name). Collect property, covered code, bounds and assumptions, command, sync commit. No sync commit recorded: use the last commit that changed the verification files, and say so. No verify skill: stop and point at `/create-formal-verification-skill`. 2. **Run it as it is** and record the result; don't decide drift vs bug yet. 3. **Read every change to covered code** from the sync commit, including renamed, split or moved functions and new code touching guarded state. Classify each change as: *No effect* · *The verification no longer describes the code* · *The promise changed on purpose* (cite evidence: doc comment, tests, changelog, commit message) · *The promise may be broken*. 4. **Update from the code, not from the result.** Change a property only for a deliberate promise change (write down old wording, new wording, evidence). Keep bounds unless the change makes them wrong; report any reduction. 5. **Rerun and judge.** Pass: break the new code the way the property guards against and confirm the check catches it. Fail: replay the counterexample against the real code step by step. A step that cannot happen means the verification is wrong (fix it). If every step can happen it is a **bug**: name the introducing commit, give the steps and the harm in one sentence. 6. **Update the verify skill** (covered code, commands, bounds, assumptions, sync commit), then follow it once. ## Key Parameters | Item | Value | |---|---| | Per-check outcomes (maintain) | `in sync`, `updated`, `bug`, `blocked`; a check can be both updated and bug | | Default for ordering questions | TLA+ model checker | | Coverage record | covered files/functions per check + sync commit | | Sync commit rule | move forward only after confirming the verification describes the code at the new commit; never for a blocked check | | Edit scope (maintain) | models, harnesses, property files, the verify skill; never product code unless the user asks | | Change separation | verification updates go in a change of their own, separate from any product fix | ## When To Use - Concurrency, retries, leases, state machines, parsers, or unsafe code where tests don't reach the breaking case and a bug is costly. - `/maintain-formal-verification-skill` after merges, refactors or edits that touched verified code without rechecking it. - For user-path behavior use [[concepts/verification-skills]]; for measured numbers use [[concepts/benchmarks-and-numbers]]. ## Risks & Pitfalls - **A stale pass looks like a proof.** When code changes and the verification doesn't, the check can keep passing on a description of code that no longer exists. The maintain report must say so when a check that passed before the update fails after it: the old pass was on a stale description. - **Never weaken the property or model** to make it pass. - **A check you've never seen fail proves nothing**: both skills require a demonstrated failing break. - **Bounded scope**: "A pass covers the model or the bound, not the whole system." - **Don't commit repro tests to product code** during maintain; attach them to the report as evidence. ## Related Concepts - [[concepts/verification-skills]] · [[concepts/shipping-prs-and-watch-pr]] · [[concepts/design-before-code]] · [[summaries/skill-catalog]] ## Sources - raw/github_doc-pstack-skills-create-formal-verification-skill-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/create-formal-verification-skill/SKILL.md) - raw/github_doc-pstack-skills-maintain-formal-verification-skill-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/maintain-formal-verification-skill/SKILL.md) - raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/06-verify-and-ship.md) --- title: "Installation and Model Setup (/setup-pstack)" type: concept tags: [pstack, install, setup-pstack, models, reasoning-budget, configuration] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-skills-setup-pstack-skill-md.md", "raw/github_doc-pstack-docs-guide-01-setup-md.md", "raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-docs-harness-claude-code-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_issue-pstack-335-pstack-default-task-model-slugs-are-unresolvable-in-current-.md"] --- # Installation and Model Setup (/setup-pstack) ## Definition Installing pstack adds its skills and agents; `/setup-pstack` then configures which model each pstack role uses and at what reasoning budget. It detects available models and writes an always-applied rule, `~/.cursor/rules/pstack-models.mdc`, that every pstack skill reads and that overrides skill defaults. Per `/poteto-help`, `/setup-pstack` is the only pstack skill that loads from the user's words; the others load when typed or when `/poteto-mode` runs them. ## How It Works **Install commands (verbatim):** - Cursor chat: `/add-plugin pstack` (or from Customize in the sidebar, per `/poteto-help`). - Claude Code: `/plugin marketplace add cursor/plugins`, then `/plugin install pstack@cursor-plugins`. Installing changes nothing until you invoke a skill. **`/setup-pstack` steps** (from its SKILL.md): 1. **Detect** model slugs you can pass to a `Task` subagent in this session (the dependable source); prefer a Cursor models API/CLI if one exists; otherwise ask you to paste slugs. It never writes a real slug it hasn't confirmed. `inherit-parent` and `auto` are always valid. 2. **Load current state** from an existing rule (its `# budget` line and role values), else defaults. Lines for retired roles (e.g. `how critics`) are dropped. 3. **Budget, map, confirm.** Ask for a budget with these exact labels: `unlimited — max reasoning`, `large — xhigh reasoning`, `medium — high reasoning`, `small — medium reasoning`. The budget sets the effort token of every real slug to `max`, `xhigh`, `high`, or `medium` (ladder `max` > `xhigh` > `high` > `medium` > `low`). If the result isn't a detected slug, it uses the same family's highest detected effort at or below the target, else marks the role as needing a choice. Then it shows every role and asks to accept or change. 4. **Validate** every real slug against the detected set. 5. **Write** the rule with `alwaysApply: true`, a `# budget` line, and one line per role, overwriting the whole file so reruns stay idempotent. 6. **Confirm** it applies to new sessions. 7. **Offer once** to generate a verification skill via `/create-verification-skill` if the project has no `verify-*` skill or harness. 8. **Offer once** to generate a formal verification skill via `/create-formal-verification-skill` if none exists. ## Key Parameters **Default rule (budget `large (xhigh)`):** | Role | Default | |---|---| | `feature, refactoring`, `bug-fix`, `perf-issue`, `hillclimb` | `grok-4.7-xhigh-fast` | | `judgment and prose`, `hardest tasks` | `claude-opus-5-5-xhigh` | | `how explorer` / `how explainer` | `grok-4.7-xhigh-fast` / `claude-opus-5-5-xhigh` | | `why investigators` / `why synthesizer` | `grok-4.7-xhigh-fast` / `claude-opus-5-5-xhigh` | | `reflect tooling` / `reflect judgment, divergent, synthesizer` | `grok-4.7-xhigh-fast` / `claude-opus-5-5-xhigh` | | `arena runners`, `arena cross-judge pool`, `architect runners`, `interrogate reviewers` | `claude-opus-5-5-xhigh, grok-4.7-xhigh-fast` (lists) | | `swarm workers` | `grok-4.7-xhigh-fast` | **Budget effects on defaults:** `unlimited` turns `claude-opus-5-5-xhigh` into `claude-opus-5-5-max`; Grok tops out at `xhigh`, so `grok-4.7-xhigh-fast` stays. `large` keeps both. `small` gives `claude-opus-5-5-medium` and `grok-4.7-medium-fast`. **Aliases:** `inherit-parent` or `auto` means the role runs on the parent chat model (Task `model` omitted) — how Auto users stay on Auto. Neither is a model slug. **Panels:** for list roles, one subagent runs per entry (aliases included), so list length sets panel size. `arena cross-judge pool` picks one entry whose family differs from the parent's when possible. `swarm workers` is the default for every `/swarm` worker unless a race assigns models per arm. **Rule file locations:** Cursor `~/.cursor/rules/pstack-models.mdc`; Claude Code `~/.claude/rules/pstack-models.md` (no frontmatter, written as ` ` such as `opus xhigh`; `grok-4.7-xhigh-fast` maps to `inherit-parent`). ## When To Use - Once after install, before the first task. - To cut cost: a smaller budget, cheaper models in code roles (guide 01 suggests a strong main-chat model with cheaper, faster code models), `auto`/`inherit-parent`, or shorter panel lists. - After a pstack default changes (see pitfalls). - When `/poteto-help` notices no rule exists and the question is about setup, cost, or which models run. ## Risks & Pitfalls - **Rule applies to new sessions only.** Start a new chat after setup; `/poteto-help` lists "a new model choice had no effect" as this mistake. - **Stale pinned defaults.** A rule written before a default changed still pins the old default. Delete those role lines or the whole file, then rerun. A rerun keeps any role whose model differs from the default; to restore one default, delete that role's line. - **Unspawnable slugs.** Issue #335 (open as of fetch 2026-10-21) reports that baked-in defaults could not be spawned on a fresh Cursor install because the `Task` allow-list exposed only one effort tier per family. A 0.15.6-era comment found `grok-4.7-xhigh-fast` resolved but `claude-opus-5-5-max` and `gpt-5.6-sol-max` failed with `Invalid model selection … Allowed model slugs:`. A commenter (deanrie) called the allow-list limit "a known, tracked product gap". That test used the then-default `claude-opus-5-5-max`; nobody tested the current default `claude-opus-5-5-xhigh` directly, but the issue body reports that Task "still does not expose `-max` / `-xhigh` even when those models are selected in the picker", so expect it to be rejected on stock Cursor. Analysis: step 1's "detect, never write an unconfirmed slug" rule is the guard; `poteto-mode` says if Task rejects an adjusted slug, fall back to the role's line or default and say so. - The formal verification offer is not for every project: guide 01 says say yes when code has concurrency, retries, a state machine, or a parser, and otherwise say no and run it later if that changes. ## Related Concepts - [[syntheses/getting-started]] — full first-run walkthrough - [[concepts/poteto-mode]] — how roles are consumed at spawn time - [[syntheses/pstack-on-claude-code]] — Claude Code differences - [[concepts/verification-skills]] and [[concepts/formal-verification]] — the two setup offers - [[summaries/known-issues]] ## Sources - raw/github_doc-pstack-skills-setup-pstack-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/setup-pstack/SKILL.md - raw/github_doc-pstack-docs-guide-01-setup-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/01-setup.md - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-docs-harness-claude-code-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/harness/claude-code.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - raw/github_issue-pstack-335-pstack-default-task-model-slugs-are-unresolvable-in-current-.md — https://github.com/cursor/plugins/issues/335 --- title: "Make It Yours: /automate-me, /reflect, /correct, /figure-it-out, Authoring Skills" type: concept tags: [automate-me, reflect, correct, figure-it-out, authoring-a-skill, eval, create-skill, forking, customization] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-docs-guide-09-make-it-yours-md.md", "raw/github_doc-pstack-skills-automate-me-skill-md.md", "raw/github_doc-pstack-skills-reflect-skill-md.md", "raw/github_doc-pstack-skills-reflect-references-judgment-reviewer-md.md", "raw/github_doc-pstack-skills-reflect-references-tooling-reviewer-md.md", "raw/github_doc-pstack-skills-reflect-references-divergent-reviewer-md.md", "raw/github_doc-pstack-skills-reflect-references-synthesizer-md.md", "raw/github_doc-pstack-skills-correct-skill-md.md", "raw/github_doc-pstack-skills-figure-it-out-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-authoring-a-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-eval-md.md", "raw/github_doc-pstack-readme-md.md", "raw/github_issue-pstack-367-pstack-disable-model-invocation-skills-still-have-use-only-w.md", "raw/github_issue-pstack-531-ci-and-validator-cover-manifests-only-skills-hooks-mcp-json-.md"] --- # Make It Yours: /automate-me, /reflect, /correct, /figure-it-out, Authoring Skills ## Definition Guide chapter 09: "poteto-mode is one person's style." The playbooks, routing, and model roles work just as well with yours. This layer has six parts: generate a personal mode (`/automate-me`), capture a session's lessons (`/reflect`), change the repo so a mistake class can't recur (`/correct`), design a playbook when none fits (`/figure-it-out`), author a focused skill (Authoring playbook), and test a skill change blind (Eval playbook). The README invites: "fork it. improve it. make it yours. PRs are welcome!" pstack is MIT-licensed. The guide's advice is to start smaller than you think. Prompt plainly, watch where agents fail, and add a skill or check "when the same failure shows up twice." ## How It Works ### /automate-me: your own `-mode` skill 0. Look for an existing `.cursor/skills/**/*-mode/SKILL.md` or `~/.cursor/skills/*-mode/SKILL.md`. If found, confirm with `AskQuestion`: update (default) or start fresh. Update mode mines only history since `git log -1 --format=%cI `. 1. Mine **only the active workspace's** `agent-transcripts/`, with parallel subagents over slices (e.g. the last 2 to 4 weeks in 3 slices). Signals: response preferences, delegation, verification posture, code and prose discipline, process conventions, meta preferences. A pattern seen in 2+ slices is high-confidence; lone signals usually get dropped. 2. Ask with `AskQuestion` (one or two questions, 4 to 6 options, `allow_multiple: true`), then one free-form question. 3. Cluster into sections (Response style, Autonomy, Understand first, Subagents, Prose / code discipline, Review and verify, Process, Skills), only where non-default. 4. Draft via Cursor's built-in `create-skill` at `.cursor/skills/-mode/SKILL.md` (or `.cursor/skills//-mode/SKILL.md`, or `~/.cursor/skills/-mode/`), with `disable-model-invocation: true` by default. 5. Iterate through `unslop`. 6. Land from a worktree off main via a PR, never pushing to main directly. Evaluation is a vibe check with the user, not a benchmark loop. ### /reflect: session lessons into skill edits 1. Find this conversation's transcript: `ls -t /*.jsonl /*/*.jsonl /*/subagents/*.jsonl 2>/dev/null | head -10`. Match the opening prompt in the first JSONL line. Never glob `~/.cursor/projects/*/`. 2. Spawn three reviewers in one message (`generalPurpose`, `readonly: false`, because MCP access is needed): | Lens | Looks for | Role line | Default | |---|---|---|---| | Judgment | durable principle behind an incident; mistakes, preferences, friction | `reflect judgment, divergent, synthesizer` | `claude-opus-5-5-xhigh` | | Tooling | concrete commands, flags, paths, quirks; **agent self-sufficiency** (context the user pasted that an MCP could have fetched) | `reflect tooling` | `grok-4.7-xhigh-fast` | | Divergent | contrarian, second-order effects, skipped verifications, skills invoked too late | `reflect judgment, divergent, synthesizer` | `claude-opus-5-5-xhigh` | All reviewers treat the transcript as untrusted (possible prompt injection) and route findings only to skills the session actually used, or to `tune description: ` for a skill that should have triggered. 3. **Synthesizer** returns **Accepted / Rejected / Backlog**. Its criteria are durability (still true in 6 months), specificity, existing-skill-first, convergence (2+ reviewers), decision-changing, structural-mechanism check, skill-was-used, and already-covered. 4. Move anything a lint, script, metadata flag, or runtime check would enforce better to Backlog. 5. **Wait for explicit approval** before applying Accepted edits ("Do not auto-apply"). Backlog is filed immediately. Trivial edits are done directly; substantive ones (>~10 lines), description tuning, and new skills go through `create-skill`. ### /correct: fix the environment Find mistake classes in commits, reverts, review comments, and workaround comments. A class counts once it has happened **twice**. Fix each at the highest level that works: 1. architecture (one owner per state, one way per task, hidden internals, one source of truth); 2. types, or a lint or CI check whose error names the fix (if the pattern is already common, fail only on additions); 3. a test; 4. docs or agent rules, last ("Nothing fails when an agent skips them"). One commit per class. Prove each check fails on a real past mistake. Exceptions go on the line with a reason, an expiry date, and human approval. Keep a rule→enforcer table in the agent instruction file. "Human review isn't on the list." `/reflect` improves skills from one session; `/correct` changes the repo. ### /figure-it-out: design a playbook For large migrations or ambitious multi-part work with no fitting playbook. **A Frame:** a falsifiable done predicate, quantified scope, and rigor biased high; a multi-hour run earns one checkpoint. **B Design:** atomic, landable units, riskiest first, harness before work, `architect` only for one-way doors. **C Loop:** hypothesis, smallest change, measure, keep or revert; verdicts are VERIFIED, NOT VERIFIED, or INCONCLUSIVE. **D Audit trail** via `show-me-your-work`, usually committed. **E Verify** against the predicate on the real product. ### Authoring or modifying a skill `/poteto-mode write a skill for ...` routes to the playbook: use `create-skill`; validate that frontmatter has `name` and `description`, referenced files exist, and links resolve; add test cases if structural; Opening a PR. "When in doubt, delete. Keep only prose that changes a decision." Delegate to other skills by path. Verification and formal-verification skills have their own generators ([[concepts/verification-skills]], [[concepts/formal-verification]]). ### Testing a skill change `/poteto-mode run the eval playbook on this skill change. same task for both variants, candidates stay blind.` or `/poteto-mode update the review skill so it flags missing migrations, and eval the change.` The Eval playbook blinds candidates (no "eval"/"candidate" words, sanitized dirs, one neutral-label judge) and grades chain-following from files actually read. Details: [[concepts/benchmarks-and-numbers]]. ## Key Parameters | Item | Value | |---|---| | Mode skill path | `.cursor/skills/-mode/SKILL.md` (project) or `~/.cursor/skills/-mode/` | | Re-run prompt | `/automate-me update my mode skill with everything since its last edit` | | Reflect prompt | `/reflect that took way too long. capture what we learned so the next run doesn't repeat it.` | | Correct prompt | `/correct agents keep calling the database client directly instead of going through the repository layer` (no argument = find classes from history) | | Mistake-class threshold | happened twice | | Claude Code copy | after changing pstack, run `node scripts/generate-pstack-harness-trees.mjs` from the repo root and commit; CI fails while the generated copy is stale | ## When To Use - Want agents to work your way → `/automate-me`. - A task that taught you something → `/reflect` right after. - Correcting agents for the same thing repeatedly → `/correct` (pair with `/architect` when the fix is a new boundary). - No playbook fits a big job → `/figure-it-out`. - Adopting someone else's skill → eval it on your work before keeping it. ## Risks & Pitfalls - **Editing a skill mid-task.** "Fix it in its own PR and keep the task moving." A tangled skill edit is invisible to review and can't be evaluated. - **Overfitting.** "One weird session is an anecdote, not a rule." A fix written from one bad session tends to overfit, and over many edits the skill drifts; asking for the eval up front catches that. - **Docs-only fixes.** Agent rules are the weakest enforcement level. - **CI won't validate your skill edits.** Issue #531 (open as of fetch 2026-10-21) reports that the repo's `validate-plugins.yml` only triggers on `.cursor-plugin/marketplace.json`, `**/plugin.json`, and `schemas/**`, so a PR touching only a `SKILL.md`, agents, or scripts ran no CI. The validator also did not parse SKILL.md frontmatter, and the `pstack/skills/poteto-mode/scripts` test suite (`bun test orch watch-pr`) is never run by CI. PR #582 (dropping the `paths:` filter and adding path-existence checks) was proposed, per the thread. Do the Authoring playbook's validation step yourself. - **Stale descriptions on slash-only skills.** Issue #367 (open as of fetch 2026-10-21): descriptions phrased as "Use only when the user..." conflict with `disable-model-invocation: true`. A reply by deanrie said those descriptions are leftovers, that the description goes into the slash menu rather than the model's context, and that PR #392 rewrites them into "what it does, use for /name" form. - **Forks for Claude Code** must regenerate the harness copy or CI fails (see [[syntheses/pstack-on-claude-code]]). ## Related Concepts [[concepts/poteto-mode]], [[concepts/decision-logs]], [[concepts/code-review-with-interrogate]] (how `/reflect`'s panel differs), [[concepts/technical-writing-and-unslop]], [[concepts/installation-and-model-setup]], [[summaries/skill-catalog]]. ## Sources - raw/github_doc-pstack-docs-guide-09-make-it-yours-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/09-make-it-yours.md) - raw/github_doc-pstack-skills-automate-me-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/automate-me/SKILL.md) - raw/github_doc-pstack-skills-reflect-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/reflect/SKILL.md) - raw/github_doc-pstack-skills-reflect-references-judgment-reviewer-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/reflect/references/judgment-reviewer.md) - raw/github_doc-pstack-skills-reflect-references-tooling-reviewer-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/reflect/references/tooling-reviewer.md) - raw/github_doc-pstack-skills-reflect-references-divergent-reviewer-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/reflect/references/divergent-reviewer.md) - raw/github_doc-pstack-skills-reflect-references-synthesizer-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/reflect/references/synthesizer.md) - raw/github_doc-pstack-skills-correct-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/correct/SKILL.md) - raw/github_doc-pstack-skills-figure-it-out-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/figure-it-out/SKILL.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-authoring-a-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/authoring-a-skill.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-eval-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/eval.md) - raw/github_doc-pstack-readme-md.md (https://github.com/cursor/plugins/blob/main/pstack/README.md) - raw/github_issue-pstack-367-pstack-disable-model-invocation-skills-still-have-use-only-w.md (https://github.com/cursor/plugins/issues/367) - raw/github_issue-pstack-531-ci-and-validator-cover-manifests-only-skills-hooks-mcp-json-.md (https://github.com/cursor/plugins/issues/531) --- title: "Orchestration and Multi-Phase Plans (Orchestrate, orch, check-plan.mjs)" type: concept tags: [orchestrate, orch, multi-phase-plan, check-plan, autopilot-stack, coordinator, frontier, ledger] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-orch-orch-ts.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-bootstrap-ts.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-multi-phase-plan-md.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-check-plan-mjs.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-stack-md.md", "raw/github_doc-pstack-docs-guide-07-overnight-md.md", "raw/github_doc-pstack-skills-swarm-skill-md.md", "raw/github_doc-pstack-skills-arena-skill-md.md", "raw/github_issue-pstack-730-pstack-orch-stale-lock-takeover-can-be-lost-unlink-then-crea.md", "raw/github_issue-pstack-523-pstack-competing-open-prs-for-the-same-issue-require-manual-.md"] --- # Orchestration and Multi-Phase Plans ## Definition Two `/poteto-mode` playbooks handle work bigger than one PR: - **Multi-phase or multi-PR plan** (`playbooks/multi-phase-plan.md`): writes a checklist plan an owner runs box by box. "The plan is the deliverable. Do not implement." It is validated by `scripts/check-plan.mjs`. - **Orchestrate** (`playbooks/orchestrate.md`): a standing coordinator chat that owns a whole program (multi-day, many stacked PRs, dozens to hundreds of subagents, the human checking in about twice a day). "You own the program, never the code." Its bookkeeping CLI is `scripts/orch/orch.ts`. `/swarm` ("Fan out N parallel workers, drain them, and return one report") and `/arena` (N candidates, pick a base, graft the best of the losers) are separate skills these playbooks call into; see [[summaries/skill-catalog]] and [[syntheses/which-skill-when]]. ## How It Works ### Multi-phase plan (7 steps) 1. Skip the plan for a one- or two-file change with an obvious approach. 2. Settle open questions by prototype (`playbooks/prototype.md`); keep branch, SHA, screenshots for Appendix A. 3. Explore in subagents with `subagent_type: "poteto-agent"`. 4. Fill the skeleton: one section per PR, name the execution playbook (Autopilot-full vs Autopilot-stack; a standing program takes Orchestrate). Default location: the agent store's `docs/`. 5. Write with `/technical-writing`, then `/unslop`; no long dashes, no mid-sentence colons. 6. Run `node pstack/skills/poteto-mode/scripts/check-plan.mjs ` and fix every line it prints. 7. Hand back the plan path and the script output, then stop until the operator's explicit go. The verification rule, which opens every verify block verbatim: "Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked." The live block is ten swarm lanes at the PR head on the `swarm workers` model (default `grok-4.7-xhigh-fast`), lane 1 being the regression lane against trunk. The audit tick is armed as `/loop 1h`. ### What check-plan.mjs enforces Usage: `node check-plan.mjs ` (no argument: prints usage, exit 2). Exit 1 if any problem, else 0. It prints one line per PR section (`boxes=N` and per-sub-block counts), then ` PR sections, problems`, then each problem as `file:line: message` on stderr. Checks (outside code fences): - Prose: no long dash (U+2013/U+2014), no curly quotes, no mid-sentence colon (`: ` followed by text). - An H1; intro under ten lines; `## How to read this` containing "One box is one unit of work", "names the evidence", "Check a box only when its evidence exists", "playbooks/", and the rule. - `## Program checklist` with H3s in order: Arm the program, Spawn owners, PR mechanics, Verdict and merge, Boot recipe; containing `git show origin/main:`, `/loop 1h`, `status message`. - Each PR section between the checklist and `## Close the program` has bold sub-blocks exactly in order: `Depends on.`, `Files.`, `Build.`, `You see.`, `Verify, unit.`, `Verify, live.`, `Verify, perf.`, `Review gate.`, `Merge.`; the three verify blocks open with the rule; live says "Ten lanes on `` at the PR head" and has lanes 1 to 10, each with `Save` and `Pass when`; perf boxes are exactly Metric, Probe, Baseline, Rule; a review gate is either `None.` with no boxes or mentions screenshot, video, operator. - After Close, only `## Appendix...` sections, including one with "Prototype evidence". ### Orchestrate Roles: **coordinator** (local, never edits code, drains the inbox, may mechanically land verified units on cheap-git repos), optional **sub-coordinators** (one per track, nesting to depth 3, roughly ten in-flight children as a rolling window), **workers/verifiers** (`environment: "cloud"` by default; verifier on a different model family). Steps: Frame (countable done predicate; if one agent could finish, run Autonomous run instead; stop spawning by roughly 70% of the budget), Install the runtime, Pilot, Scale, Drain, Land (continuous), Close. Every brief carries GOAL, SCOPE, CONTEXT, ACCEPTANCE, VERIFY, TIMEBOX, FORBIDDEN, REPORT, STANDING; missing fields are a refuse-to-spawn condition (a one-command unit may collapse the template to a paragraph that still names goal, scope, the verify command and the report shape). Store `orchestrate//`: `preferences.md` (standing orders, pasted verbatim into every spawn and every resume), `overview.md`, `units.tsv`, `frontier.json`, `ledger.tsv`, `inbox/`, `gates.md`, `decisions.tsv` (via show-me-your-work, see [[concepts/decision-logs]]), `status.md` (derived, never hand-written). ## Key Parameters ### orch CLI (from `orch.ts`) Run with bun (`bun scripts/orch/orch.ts`); `bootstrap.ts` runs `bun install --frozen-lockfile` and re-execs whenever `commander` is missing or the install key hashed from `package.json` + `bun.lock` has changed (see [[concepts/poteto-mode]]). Global: `--store ` (or `ORCH_STORE`, required), `--json`, `--force` (steal an existing store lock). | Command | Notes | |---|---| | `orch init` | initialize the store | | `orch unit add --track [--brief ]` | | | `orch unit set --state [--branch] [--pr] [--sha]` | | | `orch unit get ` / `unit list [--state] [--track]` / `unit counts` | list shows 4 rows, then `... N more; use --json` | | `orch ledger record --evidence [--verifier ]` | | | `orch ledger check ` / `ledger summary` | | | `orch inbox push [--report ]` | | | `orch inbox drain [--peek]` / `inbox count` | | | `orch gate park --question --options --default` / `gate list` / `gate resolve --answer` | | | `orch frontier set [--repo ] [--forge gh\|origin] [--prs ]` | `--repo` or `ORCH_REPO` required; `--forge` default `gh` | | `orch frontier show` | `generation=... prs=... lowest-unmerged=...` | | `orch status` | renders `status.md`; prints three lines: `counts:`, `changed:`, `gates open:` | | `orch standing show` / `standing add ` | | Exit codes: 0 success, 2 not found, 1 other or usage errors. Ledger verdicts (per playbook): `live-ui-verified | unit-test-verified | type-check-only | verifier-blocked | verifier-failed`, keyed by PR plus head SHA; a new head SHA voids the row. ## When To Use - **Multi-phase plan**: several PRs needing an auditable plan before execution; skip for 1-2 obvious files. - **Orchestrate**: "Route here when the work outlives any single agent." Guide 07 prompt: `/poteto-mode orchestrate the store migration. own it until every package is converted and merged. i'll check in twice a day.` Guide 07 pairs it with a Cursor Project (persistent coordinator thread, cloud subagents). - **Autopilot-stack** (executes a plan as one base-chained stack; the root is the only topology writer; owners report STACK-READY): pick it over Autopilot-full when the operator wants review before landing, work is coupled, or merge authority is withheld. Compared in [[syntheses/overnight-and-autonomous-runs]]. - One task to a predicate: Autonomous run. A contested decomposition: run `/arena` before the pilot. ## Risks & Pitfalls - **Stale-lock takeover race (issue #730, open as of fetch 2026-10-21).** In `store.ts`, `acquireLock` takes over a dead holder's lock by `unlink` then `create`; two processes seeing the same dead pid can both end up holding it and one writer's update is lost. A commenter (deanrie) confirmed it on `main` and described an internal fix sketch (a second `wx` takeover file). Analysis: until fixed, avoid running two `orch` processes against one store after a crash, and be careful with `--force`. - **Frontier SHAs come from local branches (same issue #730).** `frontier set` records each PR's SHA from the local branch ref, not the PR head, so a stale local branch silently records the wrong verification identity. The playbook already says head SHAs come from local branch refs, so resolve the frontier from the stacker's clone. Analysis: verify with `orch ledger check` against the real PR head. - **Competing PRs for one issue (issue #523, open as of fetch 2026-10-21).** Babysit and Shipping take one PR or stack; nothing compares N candidate PRs for the same issue. Manual comparison is required. - Never resume an agent to check on it (a resume restarts an idle agent); probe read-only. Transcript mtime is not liveness. - Never resume-chain a brief; respawn fresh. Blocking batches pay the slowest child. - `check-plan.mjs` is mechanical: it enforces structure, not whether lanes are meaningful. ## Related Concepts - [[syntheses/overnight-and-autonomous-runs]] · [[concepts/shipping-prs-and-watch-pr]] · [[concepts/decision-logs]] · [[concepts/worktrees]] · [[concepts/verification-skills]] · [[concepts/poteto-mode]] ## Sources - raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/orchestrate.md) - raw/github_doc-pstack-skills-poteto-mode-scripts-orch-orch-ts.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/orch/orch.ts) - raw/github_doc-pstack-skills-poteto-mode-scripts-bootstrap-ts.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/bootstrap.ts) - raw/github_doc-pstack-skills-poteto-mode-playbooks-multi-phase-plan-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md) - raw/github_doc-pstack-skills-poteto-mode-scripts-check-plan-mjs.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/check-plan.mjs) - raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-stack-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/autopilot-stack.md) - raw/github_doc-pstack-docs-guide-07-overnight-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/07-overnight.md) - raw/github_doc-pstack-skills-swarm-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/swarm/SKILL.md) - raw/github_doc-pstack-skills-arena-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/arena/SKILL.md) - raw/github_issue-pstack-730-pstack-orch-stale-lock-takeover-can-be-lost-unlink-then-crea.md (https://github.com/cursor/plugins/issues/730) - raw/github_issue-pstack-523-pstack-competing-open-prs-for-the-same-issue-require-manual-.md (https://github.com/cursor/plugins/issues/523) --- title: "poteto-mode" type: concept tags: [pstack, poteto-mode, playbooks, routing, subagents, principles, todo-list] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-docs-guide-02-poteto-mode-md.md", "raw/github_doc-pstack-agents-poteto-agent-md.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-bootstrap-ts.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-orch-orch-ts.md", "raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-babysit-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-multi-phase-plan-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-worktree-cleanup-md.md", "raw/github_doc-pstack-docs-guide-01-setup-md.md", "raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md"] --- # poteto-mode ## Definition `poteto-mode` is pstack's front door: "poteto's agent style for concise, detailed responses, deliberate subagents, unslopped prose, simple code, and verified work." You give `/poteto-mode` a goal; it matches one of 23 playbooks, copies the playbook's steps into a todo list, and calls other pstack skills as steps need them. Its frontmatter sets `disable-model-invocation: true`, so it runs when typed (or kept on as a Custom Mode), not on its own. ## How It Works **1. Read principles, then route.** The skill embeds an inline Principles index (24 entries in five groups: Core, Architecture, Verification, Delegation, Meta), each naming *when* it applies. The agent must read the leaf `principle-` SKILL.md for any principle it applies, and in its reply name each principle that shaped a decision and what it changed, citing only leaves it read this session. **2. Match a playbook and open the todo list.** The first todo items are the matched playbook's steps, copied verbatim from `playbooks/.md`, before any task-specific todos. A step the agent chooses not to do stays with a one-line `skip: <reason>`. Large or cross-cutting work, work the user will review after stepping away, or anything no playbook fits routes to the `figure-it-out` skill; a standing multi-day program routes to the Orchestrate playbook. The full list is in [[summaries/playbook-catalog]]. Opening a PR is invoked at the end of every other playbook. **3. Fire triggers.** "Non-negotiables" route situations to skills: nontrivial change → `how`; code crossing a function boundary → `architect`; parallel fan-out → `swarm` (or `arena` for bakeoffs); contested design → `interrogate`; any prose, including the reply → `unslop`; docs/PR descriptions/commit messages → `technical-writing`; before commit → `/deslop` (from `cursor-team-kit`); before review → `no-comments`; measured numbers → `benchmark-checklist`; PR-status requests → Babysit playbook (not Cursor's built-in babysit); landing a green stack → Shipping playbook; long or away-from-keyboard work → a `show-me-your-work` decision trail. An `AskQuestion` on an observable fork ("which approach") should instead be settled by a Prototype. **4. Delegate through `poteto-agent`.** Any subagent spawned inside a playbook step uses `subagent_type: "poteto-agent"`. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`, `swarm`) set their own `subagent_type`; don't override them. See [[entities/poteto-agent-and-comment-sicko]]. **5. Write the reply** per "Writing the reply" (see Key Parameters), ending with a PR link as `https://github.com/<owner>/<repo>/pull/<number>` where relevant. **Run-in-chat ownership.** The chat that receives `/poteto-mode` owns the playbook, the todo list, and every subagent spawn. Never spawn a `poteto-agent` to run the playbook itself. Bundled skills live at `../<name>/SKILL.md` relative to the skill file, so the absolute path of `poteto-mode`'s SKILL.md goes into every `poteto-agent` prompt. **Scripts and `bootstrap.ts`.** `skills/poteto-mode/scripts/` holds tooling the playbooks call: `watch-pr/watch-pr` (Babysit/Shipping), `orch/orch.ts` (Orchestrate bookkeeping via `bun scripts/orch/orch.ts`), `check-plan.mjs` (Multi-phase plan), and `worktree-audit.sh` (Worktree cleanup). `bootstrap.ts` exports `ensureDependenciesInstalled()`, which `orch.ts` calls before importing `commander`. It hashes `package.json` + `bun.lock` into an install key; if `commander` is missing or the key in `node_modules/.poteto-mode-tools-install-key` differs, it runs `bun install --frozen-lockfile` in the scripts directory, writes the key, and re-executes the script. ## Key Parameters **Model split (Subagents section).** Every `Task` call defaults to `run_in_background: true`, agent mode (readonly strips MCP), file pointers rather than inlined context, and an explicit model per role. Defaults: `grok-4.7-xhigh-fast` for code, `claude-opus-5-5-xhigh` for prose and judgment. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to the strongest judgment model; trivial mechanical edits go to the fast code model. Role lines from `/setup-pstack` override these; code playbooks read `feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`; hardest changes read `hardest tasks`; prose reads `judgment and prose`. **Effort tuning per spawn.** Start from the role's line, raise one step (up to max) for the hardest work, lower one step for judgment and two or more for routine work. Use `-fast` only when urgent (CI or trunk red, a person blocked now). Verification stays on the `swarm workers` model. Keep the family so panels stay diverse. If Task rejects an adjusted slug, don't try another; use the role's line or default and say so. **Fresh subagents by default.** Fix rounds, follow-ups, retries, and next queue items go to a fresh subagent with consolidated scope. Resume only when the work strictly needs state living in that agent (checkout, uncommitted changes, a running dev server/simulator/watcher). **Autonomy.** Reversible work and external actions proceed without asking. Always pause for irreversible writes: force-push to shared branches, deploys, data deletion, customer messages. "Don't stop" / "going to bed" / "run until done" / "be fully autonomous" mean keep going. "No is an acceptable answer": candor over sycophancy. **Reply style.** Short declarative sentences; no long-dash character; no mid-sentence colon connector; frame impact for the consumer and the maintainer; never fabricate links; every claim labelled measured, inferred, or guess. Comments are kept only for a non-obvious *why*. ## When To Use Any non-trivial task needing rigor. Pick it from the `/` menu before typing. Option+Enter (Mac) / Alt+Enter (Windows) makes it a Custom Mode that stays on every turn (Agents Window and CLI); plain Enter attaches it to one message. The README says it works well with Cursor's `/loop` for long runs. Skip it for small, obvious edits (guide 01). ## Risks & Pitfalls - Mid-task subject changes: without "new task", a mode mid-Feature tends to treat your question as the next feature step (guide 02). - Listing skills in your prompt reorders or drops playbook steps. - Substituting `generalPurpose` for `poteto-agent` skips the full skill read and drifts (README). - Issue #527 (closed 2026-10-12, completed) reported that `disable-model-invocation: true` on leaf skills hid them from the Skill tool and the agent's skill list, so the hub could only reach them by file path. Current SKILL.md states the `../<name>/SKILL.md` layout; verify on older installs. - Issue #726 (open as of 2026-10-21) reports that in 18 audited Claude Code runs no principle leaf was read; see [[syntheses/pstack-on-claude-code]]. ## Related Concepts - [[summaries/playbook-catalog]], [[summaries/principles-catalog]] - [[concepts/prompting-pstack]] - [[concepts/installation-and-model-setup]] - [[concepts/orchestration-and-multi-phase-plans]], [[concepts/shipping-prs-and-watch-pr]] - [[entities/poteto-agent-and-comment-sicko]] ## Sources - raw/github_doc-pstack-skills-poteto-mode-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-docs-guide-02-poteto-mode-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/02-poteto-mode.md - raw/github_doc-pstack-agents-poteto-agent-md.md — https://github.com/cursor/plugins/blob/main/pstack/agents/poteto-agent.md - raw/github_doc-pstack-skills-poteto-mode-scripts-bootstrap-ts.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/bootstrap.ts - raw/github_doc-pstack-skills-poteto-mode-scripts-orch-orch-ts.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/orch/orch.ts - raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md — https://github.com/cursor/plugins/issues/527 - raw/github_doc-pstack-skills-poteto-mode-playbooks-babysit-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/babysit.md - raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/orchestrate.md - raw/github_doc-pstack-skills-poteto-mode-playbooks-multi-phase-plan-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/multi-phase-plan.md - raw/github_doc-pstack-skills-poteto-mode-playbooks-worktree-cleanup-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/worktree-cleanup.md - raw/github_doc-pstack-docs-guide-01-setup-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/01-setup.md - raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md — https://github.com/cursor/plugins/issues/726 <!-- ===== pstack/wiki/concepts/prompting-pstack.md ===== --> --- title: "Prompting pstack" type: concept tags: [pstack, prompting, poteto-help, sharpen, in-your-own-words, bro, ketchup] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-docs-guide-02-poteto-mode-md.md", "raw/github_doc-pstack-docs-guide-readme-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_doc-pstack-skills-poteto-help-references-prompting-md.md", "raw/github_doc-pstack-skills-poteto-help-references-recipes-md.md", "raw/github_doc-pstack-skills-in-your-own-words-skill-md.md", "raw/github_doc-pstack-skills-sharpen-skill-md.md", "raw/github_doc-pstack-skills-bro-skill-md.md", "raw/github_doc-pstack-skills-ketchup-skill-md.md", "raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md", "raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md"] --- # Prompting pstack ## Definition pstack prompts state **intent and a check for done**; the playbook supplies the steps. "Say the goal, not the ceremony": a few plain sentences beat a spec. Five small skills support prompting and comprehension: `/poteto-help` (find your way), `/in-your-own-words` (restate the goal), `/sharpen` (deepen a prompt), `/bro` (plain-language restatement), and `/ketchup` (catch up on this chat). All five set `disable-model-invocation: true`, so they run only when typed. ## How It Works **What goes in** (guide 02 and `references/prompting.md`), each fitting in a sentence: 1. **The goal** — what's wrong or what you want. 2. **The done check** — must be able to pass or fail. "Make it better" and a duration are not checks. 3. **The proof to show** — real command output, a video of the flow, the stored value, a before-and-after number. 4. **What you already know** — symptom, repro step, log line, link. 5. **The real constraints** — "repro first", "don't change any code yet", "zero behavior change", "let me review before proceeding". All five at once: ```text /poteto-mode the csv export drops its last row since yesterday's deploy. failing job id is 4812. repro first, then fix. done means the 60k-row fixture exports every row. show me the row counts before and after. ``` **What to leave out:** the how (leave room for a better path); a list of skills or steps (a hand-written order drops or reorders steps; name a skill only to override one choice); your theory of the cause, until the agent has restated the problem (a stated guess narrows the search). **Follow up short.** Once the chat holds the task, `/poteto-mode do it`, `continue`, and `keep going until done` are whole prompts. Start with "new task" when the subject changes so the mode re-matches a playbook. **Steer in one line.** Restate the goal ("i said the goal is to repro. i did not ask for a fix yet.") or name a principle ("apply prove it works. show me the real output, not the build log."). A principle name is meant to work because the agent already read the rule (per `references/prompting.md`); issue #726 reports Claude Code runs often skip those reads, so the name may point at a rule the agent only saw in the inline index. ## Key Parameters | Skill | What it does | Example | |---|---|---| | `/poteto-help` | Answers a pstack question, hands you one prompt to send, links the source file. Doesn't start work for a help question (a run spends real tokens). A request for work ("use pstack to fix this bug") is not a help question; it reads `poteto-mode` and does the work. If the need is unclear, asks one multiple-choice question (Get set up / Start a task / Pick a skill / Fix a run / Make pstack my own). If no model rule exists and it matters (new user, setup or cost question, model-dependent answer), may ask at most once per chat whether to run `/setup-pstack` | `/poteto-help which skill should i use to review this branch?` | | `/in-your-own-words` | Restates what the agent thinks your goals are and the problem you're solving; no playbook | `/in-your-own-words <long or messy ask>` | | `/sharpen` | Says what a top professional would do that you didn't ask for, the rawest material they'd start from, their methods and tools, and what (other than you or the agent) would show the result is right; then rewrites your prompt, leaving your choices open. Doesn't do the task | `/sharpen write a migration guide for the v2 config format.` | | `/bro` | Restates the last message in plain human language, no jargon | `/bro` | | `/ketchup` | Read-only catch-up on what changed in this chat since your last message, pictures first, then every item waiting on you with link, user impact, evidence, risk, and its pick. Never cuts items to meet a word count | `/ketchup` | `/poteto-help`'s close calls: `/recall` rebuilds context across recent chats, `/ketchup` covers only this chat since your last message, and resuming a specific chat or branch is the Session pickup playbook. ## When To Use - **Noisy report or long thread:** make restatement the first step — `/poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet.` — or `/in-your-own-words` for the restatement alone. A misreading costs one message instead of one wrong fix. - **Unsure the prompt is aimed right:** `/sharpen` it, read the rewrite, then send it (for example with `/poteto-mode`). - **Fresh chat on old work:** `/recall` first; before unfamiliar code, `/how` and `/why`. - **Lost in jargon:** `/bro`. **Back from a break mid-chat:** `/ketchup`. - **Before stepping away:** say "im going to bed", give `/loop` a predicate, ask for a fresh worktree off a named base, pre-answer stops ("don't ask me before committing"), ask for a decision log, and give an exit ("if you're truly stuck after a few hours, stop and write up why"). ## Risks & Pitfalls - Enumerating skills in the prompt is the guide's named pitfall. - A duration ("work on it for an hour") is not a check; `/poteto-help` notes an overnight run "moved but finished nothing" when `/loop` had no pass/fail predicate. - Without "new task", a follow-up question can be treated as the next step of the last playbook. - A reply claiming success from a green build: ask for the real command, flow, stored value, or profile (prove-it-works). - `/poteto-help` itself warns that its map defers to the skill files; when they disagree, trust the file. ## Related Concepts - [[concepts/poteto-mode]] - [[syntheses/getting-started]] - [[syntheses/recipes-and-pitfalls]] - [[syntheses/which-skill-when]] - [[concepts/understanding-code]] - [[syntheses/overnight-and-autonomous-runs]] ## Sources - raw/github_doc-pstack-docs-guide-02-poteto-mode-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/02-poteto-mode.md - raw/github_doc-pstack-docs-guide-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/README.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - raw/github_doc-pstack-skills-poteto-help-references-prompting-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/references/prompting.md - raw/github_doc-pstack-skills-poteto-help-references-recipes-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/references/recipes.md - raw/github_doc-pstack-skills-in-your-own-words-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/in-your-own-words/SKILL.md - raw/github_doc-pstack-skills-sharpen-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/sharpen/SKILL.md - raw/github_doc-pstack-skills-bro-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/bro/SKILL.md - raw/github_doc-pstack-skills-ketchup-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/ketchup/SKILL.md - raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/10-recipes-and-pitfalls.md - raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md — https://github.com/cursor/plugins/issues/726 <!-- ===== pstack/wiki/concepts/shipping-prs-and-watch-pr.md ===== --> --- title: "Shipping PRs: Opening a PR, Babysit, Shipping, and the watch-pr CLI" type: concept tags: [pull-requests, babysit, shipping, watch-pr, bugbot, stacks, forge, origin, gh] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-opening-a-pr-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-shipping-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-babysit-md.md", "raw/github_doc-pstack-skills-poteto-mode-references-bugbot-triage-md.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-watch-pr-cli-ts.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-watch-pr-policy-ts.md", "raw/github_issue-pstack-750-pstack-watch-pr-status-only-retries-for-minutes-on-a-repo-wi.md", "raw/github_issue-pstack-731-pstack-watch-pr-blocked-merge-state-with-green-ci-reports-re.md", "raw/github_issue-pstack-343-fix-pstack-treat-an-empty-check-rollup-as-no-checks.md", "raw/github_issue-pstack-471-watch-pr-review-threads-are-fetched-without-pagination-first.md", "raw/github_commits-pstack-log.md"] --- # Shipping PRs and watch-pr ## Definition pstack splits "get the code merged" into three `/poteto-mode` playbooks plus one bundled script: | Stage | Playbook | Prompt (guide 06) | Ends at | |---|---|---|---| | Open | Opening a PR (`playbooks/opening-a-pr.md`) | `/poteto-mode open the pr. small ordered commits, evidence in the description.` | PR URL posted | | Get green | Babysit (`playbooks/babysit.md`) | `/poteto-mode babysit this pr. get it green.` | merge-ready (never merges) | | Land | Shipping (`playbooks/shipping.md`) | `/poteto-mode land the stack.` | the verified ceiling merged | `scripts/watch-pr/watch-pr` is the GitHub-only status watcher that Babysit and Shipping poll. ## How It Works ### Opening a PR Invoked at the end of every other playbook. Work from a git worktree off main (see [[concepts/worktrees]]); rebase into small ordered commits, each a future landable PR. Run `/deslop` (from `cursor-team-kit`) over the diff before commit and `/no-comments` before review; write titles, bodies and commits with `/technical-writing`, then `/unslop` (see [[concepts/technical-writing-and-unslop]]). - **Title:** Conventional Commits `type(scope): subject`, no trailing period, e.g. `fix(pstack): retarget opening-a-pr babysit trigger`. - **Body** (`##` headings in order, drop empty ones): `## Why`, `## What changed`, `## Scope` (always), `## Tradeoffs`, `## Blast Radius`, `## Verification`. Keep the squash commit under about 40 lines. - **Forge:** `gh` is the default; if `command -v origin` succeeds and Origin resolves the repo, prefer `origin pr ...`. Never require Graphite (`gt`). A built-in PR tool, when present, is used for create/edit/retarget/ready. - **Stacks:** child PR `gh pr create --base <parent-branch>` or `origin pr create --status open --base <parent-branch>`; retarget with `gh pr edit <pr> --base <parent-branch>`. - **Readiness:** open every PR ready, never draft (`draft: false` with a PR tool, `--status open` with Origin, omit `--draft` with `gh`). - **No auto-babysit:** opening a PR does not start a babysit; post the URL and keep building. Exception: Autopilot-full/Autopilot-stack owners (see [[syntheses/overnight-and-autonomous-runs]]). ### Babysit Replaces Cursor's built-in babysit skill for these requests. Steps: (1) declare a **mode** and resolve the forge; (2) work only the **merge frontier** (lowest unmerged PR); (3) one babysitter per stack; (4) never mutate stack topology (no retarget, rebase, stack-wide submit, force-push; report rebase-shaped work to the owner); (5) order **conflicts, then review threads, then CI**, batching fixes into one push wave (a conflict is reported, not resolved); (6) trust the forge's verdict, run under `/loop` in dynamic mode, rearm the watcher after every push wave; (7) classify CI before retrigger (flake gets one fresh build, never a job retry; check stale base with `git merge-base --is-ancestor`); (8) triage Bugbot skeptically; (9) stop at the human's line (approval is a wait; babysitting never authorizes merging). | Mode | Use for | |---|---| | `drive` (default) | "babysit this", "get it green", "merge-ready" | | `background` | a plan still executing; triage without blocking | | `threads-only` | "address the bugbot comments" | | `check` | "check on X", "is it green"; also small or docs-only PRs | ### Bugbot triage (`references/bugbot-triage.md`) Classify each thread `fix` (fix in the lowest owning PR, reply with SHA, resolve), `dismiss` (documented low-risk pattern, reply with reason) or `ask`. "When in doubt, ask." Never auto-skip security, privacy, auth, billing, data-retention, high-severity, migration/schema/idempotency/concurrency findings. Learned patterns carry `Confidence: candidate | recurring | strong`. From the third Bugbot pass, Babysit leans toward dismissing documented patterns (still escalating risky areas). Reply on GitHub via `gh api --method POST "repos/<owner>/<repo>/pulls/<pr>/comments/<comment-id>/replies" --input <payload.json>`; never interpolate comment text into a shell command. ### Shipping 1. Verify each PR independently: one verifier per PR (a Cursor cloud agent using a control skill such as `control-ui`/`control-cli`) posts `PASS`, `PASS+NOTES` or `FAIL`. Only a non-author verdict counts; green CI and bot approval are not verdicts. 2. Land only the contiguous verified run from the bottom; the top is the ceiling. 3. Re-check verdicts with `git patch-id` at the verdict SHA vs current head. 4. Land bottom-up: `gh pr merge <pr> --squash` or `origin pr merge <pr>`; read back with `gh pr view <pr> --json state,mergedAt,baseRefName`; retarget the next child to trunk and push `--force-with-lease`. 5. Leave the stack alone; on GitHub watch with `scripts/watch-pr/watch-pr --queued-stack --stack-prs <bottom-to-top>` under `/loop` until `COMPLETE`. 6. Stop at the ceiling. ## Key Parameters ### watch-pr flags (from `cli.ts`) | Flag | Default | Meaning | |---|---|---| | `--owner <owner>` / `--repo <repo>` | resolved from context | GitHub repo | | `--pr <number>` | resolved | PR number (a leading `#` is accepted) | | `--stack` | `false` | watch the connected open stack; conflicts with `--queued-stack` | | `--queued-stack` | `false` | watch the captured stack until all PRs merge | | `--stack-prs <n,...>` | none | frozen bottom-to-top queue; requires `--queued-stack`; no duplicates | | `--interval <seconds>` | `60` | poll interval | | `--sweep-interval <seconds>` | `300` | whole-stack sweep interval | | `--timeout <seconds>` | `0` | deadline; `0` disables it | | `--max-query-errors <count>` | `5` | consecutive query-error budget | | `--status-only` | `false` | print one status table and exit 0 | | `--allow-draft` | `false` | do not treat a draft as a merge gate | | `--pretty` | `false` | human text instead of JSON (NDJSON while polling) | ### Verdicts and exit codes (from `policy.ts` / `cli.ts`) | Verdict | Terminal | Exit | |---|---|---| | `READY` (single or stack mode) | yes | 0 | | `STATUS` (`--status-only`) | yes | 0 | | `COMPLETE` (queued) | yes | 0 | | `BLOCKER` merge-conflicts / review-threads / failing-checks / merge-gate | yes | 2 / 3 / 4 / 6 | | `TIMEOUT` | yes | 5 | | `BLOCKER` status-query (error budget exhausted or non-retryable) | yes | 7 | | `WAITING`, `RETRY`, `ADVANCE`, `QUEUE`, and `STATUS` while polling (stack, whole-stack sweep) | no (progress) | - | | argument parse error | - | 64 | Blocker precedence per PR is conflicts, threads, failing CI, then merge gate (draft, `CHANGES_REQUESTED`, closed). Query-error backoff is `min(max(interval, 60) * 2^(failures-1), 300)` seconds. Queued mode never emits `READY`; a blocker-free frontier is `WAITING` with reason `merge-queue`, which Babysit reports as merge-ready. On Origin the watcher is not used. ## When To Use - Opening a PR: automatically at the end of any playbook. - Babysit: once a phase or whole stack is built, not per PR. Status only: `/poteto-mode check on pr 123. anything outstanding?` - Shipping: only on an explicit request to merge, land or ship. ## Risks & Pitfalls - **No-checks repos stall `--status-only` (issue #750, open as of fetch 2026-10-21).** When both `gh pr checks` and the GraphQL rollup are empty, the watcher throws a retryable error and `--status-only` goes through the full retry budget, printing `RETRY: GitHub status query failed; retrying in 60s`; the reporter saw retries after 60, 120 and 240 s on pstack 0.15.25. A downstream fork's fix adds a `ci-none` state; not merged upstream at fetch time. Workaround (analysis): pass `--max-query-errors 1` for a fast failure, or read `gh pr view` directly. - **Same root cause, earlier report (issue #343, closed `not_planned` as of fetch 2026-10-21):** polling mode retried until `TIMEOUT` on a `MERGEABLE`/`CLEAN` PR with an empty rollup. #750 says the fork's fix leaves polling mode unchanged, because "A head that was just pushed has no checks yet either", so treating no checks as ready while polling would report `READY` too early. - **`READY` does not mean approved (issue #731, open as of fetch 2026-10-21).** `assessGitHubMerge` treats `mergeStateStatus: "BLOCKED"` with a non-failing rollup as allowed, and `gateReason` blocks only `CHANGES_REQUESTED`, so a PR missing a required review can be `ready`. A commenter (deanrie) called this intentional (required review is the human's step) and flagged it to the owners as a product question. - **Review threads past the first 100 were invisible (issue #471, closed `completed` as of fetch 2026-10-21).** The `reviewThreads(first: 100)` query had no pagination, so an unresolved thread beyond the first page did not block readiness. The commit log lists `fix(watch-pr): paginate review threads instead of reading only the first 100 (#484)` on 2026-10-12 (the issue was closed the same day; a commenter had recommended #484 over #460); analysis: installs older than that commit presumably still have the bug. The issue also notes that comments past the first 10 per thread are dropped, "though that matters less" (only thread-level resolution feeds the decision). - **A merge command can report success when it only queued**; always read the PR back. A requested auto-merge is not a merge. - **A chain rebase moves every PR above it to a new SHA without failing a check**; compare `git patch-id` before trusting an old verdict. - Upstack fixes while the frontier is red restart checks; go back down. ## Related Concepts - [[concepts/verification-skills]] · [[concepts/worktrees]] · [[concepts/orchestration-and-multi-phase-plans]] · [[concepts/code-review-with-interrogate]] · [[syntheses/overnight-and-autonomous-runs]] · [[summaries/known-issues]] ## Sources - raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/06-verify-and-ship.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-opening-a-pr-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/opening-a-pr.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-shipping-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/shipping.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-babysit-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/babysit.md) - raw/github_doc-pstack-skills-poteto-mode-references-bugbot-triage-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/references/bugbot-triage.md) - raw/github_doc-pstack-skills-poteto-mode-scripts-watch-pr-cli-ts.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/watch-pr/cli.ts) - raw/github_doc-pstack-skills-poteto-mode-scripts-watch-pr-policy-ts.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/watch-pr/policy.ts) - raw/github_issue-pstack-750-pstack-watch-pr-status-only-retries-for-minutes-on-a-repo-wi.md (https://github.com/cursor/plugins/issues/750) - raw/github_issue-pstack-731-pstack-watch-pr-blocked-merge-state-with-green-ci-reports-re.md (https://github.com/cursor/plugins/issues/731) - raw/github_issue-pstack-343-fix-pstack-treat-an-empty-check-rollup-as-no-checks.md (https://github.com/cursor/plugins/issues/343) - raw/github_issue-pstack-471-watch-pr-review-threads-are-fetched-without-pagination-first.md (https://github.com/cursor/plugins/issues/471) - raw/github_commits-pstack-log.md (https://github.com/cursor/plugins/commits/main/pstack) <!-- ===== pstack/wiki/concepts/technical-writing-and-unslop.md ===== --> --- title: "Technical Writing, /unslop, and /bro" type: concept tags: [technical-writing, unslop, bro, diataxis, google-style, ste, global-english, prose, pr-descriptions] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-skills-technical-writing-skill-md.md", "raw/github_doc-pstack-skills-unslop-skill-md.md", "raw/github_doc-pstack-skills-bro-skill-md.md", "raw/github_doc-pstack-docs-guide-09-make-it-yours-md.md", "raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md", "raw/github_doc-pstack-docs-guide-05-build-and-clean-md.md", "raw/github_doc-pstack-docs-guide-04-design-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-opening-a-pr-md.md", "raw/github_doc-pstack-readme-md.md", "raw/github_issue-pstack-630-feat-pstack-add-more-slop-patterns-to-unslop-skill.md", "raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md"] --- # Technical Writing, /unslop, and /bro ## Definition pstack has three prose skills: - **`/technical-writing`**: a layered documentation standard (README: "Diátaxis + Google developer style + STE + Global English") for docs, RFCs, readmes, PR descriptions, and commit messages. The goal: "Write so a tired engineer understands on the first read." - **`/unslop`**: "Cut AI tells from any writing." It works from a numbered catalog of slop patterns that other skills cite. - **`/bro`**: "Restate the last message in plain human language, with no jargon." The whole skill is one instruction: restate it more simply and concisely, "like one human talking to another." Division of labor (guide 05): `/deslop` (from `cursor-team-kit`, not pstack) cleans slop out of code, `/unslop` cleans it out of prose, and `/no-comments` hands comments to a separate reviewer. ## How It Works ### /technical-writing: three top rules, then four layers **Above the layers:** cut every word that does no work ("In order to" → "to"); use the short everyday word ("use", not "utilize"); and when a rule makes a sentence worse, fix the sentence another way or leave it alone. "The codebase is the word list": write the real symbol, file, flag, or command. Don't invent jargon. Propose new offenders as an addition to `unslop`'s abstract-metaphor rule in your reply, with the diff, but don't edit that skill. **Vary the rhythm.** Mix sentence lengths. Have a view where the mode allows it. Be specific ("a column rename fails the build", not "schema changes can cause issues"). **Layer 1: Diátaxis (pick the mode first).** One document, one mode: | Informs | Serves learning | Serves work | |---|---|---| | Action | **tutorial** ("we", visible result every step, say what they'll build) | **how-to** (assume competence, name it by the task: "How to calibrate the radar array") | | Understanding | **explanation** (one bounded topic, opinion allowed only here) | **reference** (dry, complete, no hedging, mirror the code's structure) | Don't mix modes. Split and link. **Layer 2: Google developer style.** Address "you" in the present tense. Name the actor (active voice). Write instructions as commands. Put the condition first ("To delete the document, click Delete."), common case first. Never write "simply", "easy", or "quickly" in a procedure, and no "please". Use descriptive link text, never "click here". Headings carry the point, in sentence case, one h1, no skipped levels. Numbered lists for sequences. Code in code font, UI in bold, serial commas, no "etc.". **Layer 3: STE (Simplified Technical English).** One instruction per sentence. Split instructions over about 20 words and other sentences over about 25. Put the warning before the step. Keep "the" and "a". One meaning per word and one word per action ("start", not "initiate"). Procedures are direct commands, never passive. Avoid "-ing" words where you can. **Layer 4: Global English.** Keep "only" and "not" next to the word they modify. Break up noun strings. Every "it" or "this" points at one thing. Don't drop verbs. Keep "that". Use periods, not semicolons. Replace an em dash with a new sentence. No "(s)" plurals, no slashes ("a, b, or both"). One name per thing. No idioms, Latin abbreviations, or metaphors. **Repo specifics.** Apply `unslop` to every doc. PR descriptions and commit messages get every layer except Diátaxis. A PR body is a briefing readable in under a minute: no swarm logs, SHA lists, or metric tables; link them instead. Product UI strings follow your product's copy guidelines instead. Indent code snippets with tabs, and include the command that regenerates any count or tree claim. ### /unslop pattern catalog Rule numbers are stable ids ("A removed rule leaves a gap"; numbers 1, 2, 4, 6, and 21 are absent from the current file). | # | Pattern | |---|---| | 3 | Superficial -ing phrases ("highlighting...", "ensuring...") | | 5 | Vague attributions ("Experts believe") | | 7 | AI vocabulary: Additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape (abstract), pivotal, showcase, tapestry (abstract), testament, underscore, vibrant | | 8 | Fancy "is": "serves as", "stands as", "boasts", "features" | | 9 | "Not just X, but Y." | | 10 | Forced rule of three | | 11 | Synonym cycling | | 12 | False ranges ("from X to Y") | | 13 | Em dashes: avoid entirely (no en dashes or hyphen substitutes either) | | 14 | Colon as mid-sentence connector | | 15 | Boldface overuse | | 16 | Inline-header lists ("**Performance:** Performance improved..."). A bold lead-in ending in a period followed by new detail is fine. | | 17 | Title case headings → sentence case | | 18 | Decorative emojis | | 19 | Curly quotes → straight | | 20 | Chatbot phrases ("I hope this helps!", "Let me know if...") | | 22 | Sycophantic tone | | 23 | Filler phrases | | 24 | Excessive hedging | | 25 | Generic conclusions | | 26 | Abstract metaphor nouns: substrate, wedge, vector, locus, vantage, nexus, primitive (noun), harness (metaphor), surface ("API surface"), bedrock, scaffolding (metaphor), modality, paradigm, gold-plating, ratchet (metaphor), evacuate, endgame, north star, flywheel | | 27 | Say what it does, not how it feels. If the sentence fits another project's docs unchanged, cut it. | | 28 | Shorten or split dense sentences | | 29 | Active voice | | 30 | Cut adverbs, use a stronger verb or the number | | 31 | Plain word ("utilize"/"leverage" → "use") | | 32 | Mannered prose (aphorisms, personified code, figurative verbs) | | 33 | Over-compression (arrows, dropped articles, symbol-speak) | ## Key Parameters - **Invocation:** all three set `disable-model-invocation: true`. Type `/technical-writing`, `/unslop`, or `/bro`. - **Terse prompts work:** `/unslop the readme changes, no emdashes`, `unslop that, tighten it`, `/unslop that, no emdashes`. README shorthand: `can we unslop and tighten the new changes?` - **Review prompt:** `/technical-writing review the readme changes`. - **PR conventions (Opening a PR playbook):** titles follow Conventional Commits `type(scope): subject` with no trailing period, e.g. `fix(pstack): retarget opening-a-pr babysit trigger`. Bodies use `/technical-writing` (all layers except Diátaxis, plus STE vocabulary rules), then `/unslop`, and keep the squash commit under about 40 lines. ## When To Use - Writing or reviewing a doc, RFC, README, PR, or commit message → `/technical-writing`. Name it up front when you ask for a doc, so "a tutorial stays a tutorial" (guide 04, via [[concepts/design-before-code]]). - Any agent prose that reads machine-written → `/unslop`. Many skills (`/teach`, `/recall`, `/blast-radius`, the Investigation playbook) already write through it. - A reply that is thorough but you still don't know what it said → `/bro`. ## Risks & Pitfalls - **Rules applied mechanically.** "A sentence that follows every rule and sounds like a machine wrote it has failed." The rhythm section exists for this. - **Process narration is not covered yet.** Issue #630 (open as of fetch 2026-10-21) asks `unslop` to catch "Rather than / Instead of" contrasts and "Let me... / I'll..." status narration. A commenter (deanrie) confirmed no rule covers them (rule 9 and rule 20 are the closest) and suggested a single "Process narration" rule at the next free number. Whether it lands is the owner's call. - **Renumbering breaks citations.** Other skills cite rule numbers, so new rules take the next free number. - **Mixing Diátaxis modes** (reference tables in a tutorial, arguing in a how-to). - **`unslop` invocation history.** Issue #527 notes `unslop` was among the first skills given `disable-model-invocation: true`, and commenters asked why, since it "Must always apply". See [[summaries/known-issues]]. ## Related Concepts [[concepts/build-and-clean]] (`/deslop`, `/no-comments`), [[concepts/shipping-prs-and-watch-pr]] (PR prose), [[concepts/understanding-code]] (`/teach` writes through unslop), [[concepts/prompting-pstack]], [[summaries/skill-catalog]]. ## Sources - raw/github_doc-pstack-skills-technical-writing-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/technical-writing/SKILL.md) - raw/github_doc-pstack-skills-unslop-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/unslop/SKILL.md) - raw/github_doc-pstack-skills-bro-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/bro/SKILL.md) - raw/github_doc-pstack-docs-guide-09-make-it-yours-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/09-make-it-yours.md) - raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/10-recipes-and-pitfalls.md) - raw/github_doc-pstack-docs-guide-05-build-and-clean-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/05-build-and-clean.md) - raw/github_doc-pstack-docs-guide-04-design-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/04-design.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-opening-a-pr-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/opening-a-pr.md) - raw/github_doc-pstack-readme-md.md (https://github.com/cursor/plugins/blob/main/pstack/README.md) - raw/github_issue-pstack-630-feat-pstack-add-more-slop-patterns-to-unslop-skill.md (https://github.com/cursor/plugins/issues/630) - raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md (https://github.com/cursor/plugins/issues/527) <!-- ===== pstack/wiki/concepts/understanding-code.md ===== --> --- title: "Understanding Code: /how, /why, /teach, /recall" type: concept tags: [how, why, teach, recall, investigation, onboarding, epistemics, subagents] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-docs-guide-03-understand-md.md", "raw/github_doc-pstack-skills-how-skill-md.md", "raw/github_doc-pstack-skills-how-references-explorer-prompt-md.md", "raw/github_doc-pstack-skills-how-references-explainer-prompt-md.md", "raw/github_doc-pstack-skills-why-skill-md.md", "raw/github_doc-pstack-skills-why-references-epistemics-md.md", "raw/github_doc-pstack-skills-why-references-investigator-prompt-md.md", "raw/github_doc-pstack-skills-why-references-synthesizer-prompt-md.md", "raw/github_doc-pstack-skills-why-references-source-playbook-md.md", "raw/github_doc-pstack-skills-why-references-sources-incident-postmortem-md.md", "raw/github_doc-pstack-skills-why-references-sources-slack-md.md", "raw/github_doc-pstack-skills-teach-skill-md.md", "raw/github_doc-pstack-skills-recall-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-investigation-md.md", "raw/github_issue-pstack-393-pstack-route-comprehension-gaps-to-teach.md", "raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md"] --- # Understanding Code: /how, /why, /teach, /recall ## Definition pstack's comprehension layer (guide chapter 03, "Understand the code before changing it") is four read-mostly skills that make the agent build and state a checkable model of code before it edits anything: | Skill | Answers | Output | |---|---|---| | `/how` | What the code does now (runtime flow, placement, "which package owns this") | Overview / Key Concepts / How It Works / Where Things Live / Gotchas | | `/why` | What forces shaped the code (rationale, regressions, postmortems, data-backed thresholds) | Confidence-tiered, cited report | | `/teach` | Both, woven into a plain explanation for a person | A conversational explanation built up diagram by diagram | | `/recall` | Where *your own* recent work on a topic stands | A tight state brief (capsule, threads, problems, next move) | All four set `disable-model-invocation: true`, so they run when you type the slash command. ## How It Works ### /how 1. **Assess complexity.** Simple (one module, narrow question): no explorers; one explainer explores and explains in a single pass. Complex (multi-file subsystem, cross-cutting feature): fan out. "When in doubt, take the simple path." 2. **Explore (complex only).** Split the question into 2 to 4 angles; spawn all explorers in one message. Each returns Components Found, Flow, Files Read, Boundaries, Non-Obvious Things, Open Questions. 3. **Synthesize.** One explainer merges the findings, resolving contradictions by checking the code itself (read-only Read/Grep/Glob). It may add a mermaid or ASCII diagram only when it clarifies. 4. **Present** with light edits only; do not substantially rewrite. Every spawn is a Task subagent with `subagent_type: generalPurpose` and `readonly: true`. ### /why 1. Pin the target and question; if vague, state a best-guess interpretation and proceed. 2. **Code anchor**, built inline before spawning: `git blame -L <start>,<end> <file>`, `git log --follow -p -- <file>`, `git log --oneline -20 -- <file>`, `git log -1 --format=%B <commit>`, then `gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews`. 3. **Discover MCPs** and map each to one of seven evidence categories: source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse. Spawn **one investigator per category** (each owns exactly one MCP), all in one message. Source control is always available via git and `gh`. Example playbooks: code-archaeology (git/`gh`), Linear, Notion, Slack, Datadog, Sentry, Databricks; add `incident-postmortem.md` when the code looks defensive (null checks, retries, timeouts, rate limits, feature flags, egress guards, OOM handlers). 4. **Synthesize** with one synthesizer that follows `references/epistemics.md` and spot-checks citations. 5. **Present** without rewriting the confidence language. Output sections: The Question, The Code in Question, What We Found, What We Can Reasonably Infer, Competing Hypotheses, What We Don't Know, Sources Consulted (one line per investigator, including empty or skipped ones), Confidence Summary. If the question precedes a change, it adds a **Preserve / Change / Avoid / Risk** constraint set. **Epistemics.** Every claim sits in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. Confidence words ("because", "was designed to", "fixes") need an adjacent citation. Inferred claims are hedged ("appears to", "likely"). Words to avoid: "obviously", "clearly", "of course", "just", "I think". Code is never evidence for its own intent. A hypothesis embedded in the user's question is a candidate to test, not to confirm (the "sycophancy trap"). A null result is a finding. ### /teach Runs `how` and `why` as real skill invocations, in parallel (or just one for a small change; `why` kept narrow by default because its full sweep is slow), then explains: plain definition first, tie it to the case, smallest complete answer, deeper on request. For three or more moving parts, it draws a *series* of diagrams, each adding one part, never one all-at-once diagram. Spatial ideas get a generated whiteboard-style image. No quizzes, no "pacing theater". Written through `unslop`; keeps `why`'s hedges intact. ### /recall Mines your own chat transcripts at `~/.cursor/projects/<slug>/agent-transcripts/<uuid>/<uuid>.jsonl` with parallel subagents on a fast, cheap model (ordered by `ls -t`, never by UUID), and by default also sweeps the shared record via `why`'s source investigators ("what's been tried and didn't hold"). It verifies PRs and branches against live state with `git` and `gh`. Default window: last 7 days, active workspace only. Brief contract: **Capsule** (at most 5 bullets), **Threads** (each tagged exactly one of `[merged #N]`, `[open PR #N]`, `[in flight <branch>]`, `[verified, uncommitted]`, `[reverted #N]`, `[planned, not started]`), **Problems** (at most 5), **Next move** (one action). ### Investigation playbook `/poteto-mode ... don't change any code yet` routes to the read-only Investigation playbook. It runs `how`, plus `why` for motivation questions. Its throughput checkpoint is one line: `throughput checkpoint: n/a, read-only investigation`. It returns `how`-shaped output, or a recommendation with a trade-offs table when choosing between options. No PR, no babysit, no `architect` unless the investigation precedes a code change; in that case it hands back to the user to re-route to Bug fix or Feature (the guide: start the fix as a new task). ## Key Parameters | Setting | Where | Default | |---|---|---| | `how explorer` model | `pstack-models.mdc` rule | `grok-4.7-xhigh-fast` | | `how explainer` model | `pstack-models.mdc` | `claude-opus-5-5-xhigh` | | `why investigators` model | `pstack-models.mdc` | `grok-4.7-xhigh-fast` | | `why synthesizer` model | `pstack-models.mdc` | `claude-opus-5-5-xhigh` | | `/how` explorers | complex path only | 2 to 4 | | `/why` spawn mode | every spawn | `generalPurpose`, `readonly: false` | | `/recall` window | scope | last 7 days, active workspace | A model value of `auto` or `inherit-parent` means leave `model` unset. If the Task tool rejects a slug, the skill falls back to the default and says so. ## When To Use - "How does X work / where should this live?" → `/how`. - "Why is it like this / does the reason still hold?" → `/why`. Prompting `do why first then how` works well when history probably explains the mess. - You need to really understand a change or the agent's own choice → `/teach`. "Convince me it fixes the cause and not the symptom" turns it into an argument you can test. - Starting new work on an old topic → `/recall` first, then hand over the new input. To resume **one specific chat**, use the Session pickup playbook, not `/recall`. Turning habits into a skill is `/automate-me` (see [[concepts/make-it-yours]]). - Unclear cause, want findings not a fix → the Investigation playbook via [[concepts/poteto-mode]]. ## Risks & Pitfalls - **`/why` must not run in readonly/Ask mode.** That strips MCP access and disables the MCP-backed investigators and the synthesizer's citation spot-checks. - **Recency bias.** Treating the newest commit as authoritative; the current shape is often an accretion of earlier decisions. - **Skipping comprehension.** The guide warns that an agent that edits without a traced model "tends to fix the symptom at the first plausible spot." - **Skipped investigators** need a written justification (no MCP available, or the source is *provably* irrelevant). Slack auth failure means stop and report the gap, not invent findings. - **Routing gaps from `disable-model-invocation`.** Issue #527 (closed, completed, as of fetch 2026-10-21) reported that the flag hid `how` and other routed leaves from `/poteto-mode`'s Skill tool calls. Issue #393 (closed, completed, as of fetch 2026-10-21) noted `/teach` was explicit-only, with no route from comprehension signals ("which layer owns this?") during an architecture checkpoint. - `/recall` never reads another project's transcripts unasked, and never quietly narrows "all" into "recent N". ## Related Concepts - [[concepts/design-before-code]]: `/architect` runs `/how` and `/why` as its grounding phase. - [[concepts/poteto-mode]]: routes investigations and session pickup. - [[concepts/technical-writing-and-unslop]]: `/teach`, `/recall`, and the Investigation reply are written through `unslop`. - [[concepts/decision-logs]], [[syntheses/which-skill-when]], [[summaries/skill-catalog]]. ## Sources - raw/github_doc-pstack-docs-guide-03-understand-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/03-understand.md) - raw/github_doc-pstack-skills-how-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/how/SKILL.md) - raw/github_doc-pstack-skills-how-references-explorer-prompt-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/how/references/explorer-prompt.md) - raw/github_doc-pstack-skills-how-references-explainer-prompt-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/how/references/explainer-prompt.md) - raw/github_doc-pstack-skills-why-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/why/SKILL.md) - raw/github_doc-pstack-skills-why-references-epistemics-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/why/references/epistemics.md) - raw/github_doc-pstack-skills-why-references-investigator-prompt-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/why/references/investigator-prompt.md) - raw/github_doc-pstack-skills-why-references-synthesizer-prompt-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/why/references/synthesizer-prompt.md) - raw/github_doc-pstack-skills-why-references-source-playbook-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/why/references/source-playbook.md) - raw/github_doc-pstack-skills-why-references-sources-incident-postmortem-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/why/references/sources/incident-postmortem.md) - raw/github_doc-pstack-skills-why-references-sources-slack-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/why/references/sources/slack.md) - raw/github_doc-pstack-skills-teach-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/teach/SKILL.md) - raw/github_doc-pstack-skills-recall-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/recall/SKILL.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-investigation-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/investigation.md) - raw/github_issue-pstack-393-pstack-route-comprehension-gaps-to-teach.md (https://github.com/cursor/plugins/issues/393) - raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md (https://github.com/cursor/plugins/issues/527) <!-- ===== pstack/wiki/concepts/verification-skills.md ===== --> --- title: "Verification Skills (/create-verification-skill, /maintain-verification-skill)" type: concept tags: [verification, prove-it-works, feature-map, create-verification-skill, maintain-verification-skill, evidence] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-skills-create-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-create-verification-skill-references-feature-m.md", "raw/github_doc-pstack-skills-create-verification-skill-references-feature-m-2.md", "raw/github_doc-pstack-skills-create-verification-skill-references-feature-m-3.md", "raw/github_doc-pstack-skills-maintain-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-principle-prove-it-works-skill-md.md", "raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md", "raw/github_issue-pstack-457-pstack-create-verification-skill-enumerates-surfaces-by-huma.md"] --- # Verification Skills ## Definition A **verification skill** is a project-local skill that lets any agent drive your real app the way a user does and capture evidence that a behavior works. pstack ships two user-invoked skills for it (both `disable-model-invocation: true`, so you type them): - **`/create-verification-skill`** generates `.cursor/skills/verify-<app>/` (a `SKILL.md` plus a `features/` map) for any language, framework or platform. - **`/maintain-verification-skill`** is the periodic upkeep pass that keeps that skill and its feature map honest as the app changes. They are the working form of the **Prove It Works** principle: verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or "it compiles." That principle prefers a deterministic script you can re-run over a one-time eyeball, and says to commit such a trail only for large or complex work (the `show-me-your-work` skill, see [[concepts/decision-logs]]). ## How It Works ### /create-verification-skill (5 steps) 1. **Interview the repo, not the user.** Answer from the codebase: *Surface* (web UI, CLI/TUI, desktop, API, mobile, library), *Run* (the repo's own dev command, ports, env vars, seed data, auth), *Drive* (existing harnesses first: Playwright/Cypress specs, expect scripts, PTY helpers, curl-able endpoints, a debug port; only then browser/CDP, a tmux/PTY harness, or plain HTTP), *Observe* (screenshots, transcripts, response bodies, logs, exit codes, DB state), *Isolate* (can two instances run side by side?). Ask the user only what can't be observed. If the checkout doesn't build or start, fix or report that first. 2. **Generate the skill** with frontmatter `name: verify-<app>` and a `description` (without frontmatter the skill never registers), and these sections: - **Launch**: exact command, readiness signal ("Ready means usable"), must reach a usable state from an empty data dir including migrations and seed data; include teardown. - **Doctor**: one read-only "is this instance worth driving?" check. - **Drive**: real selectors/commands from the repo; prefer stable handles (ARIA labels, data attributes, prompt strings, route paths) over coordinates and tab order. - **Evidence**: what to capture and where; real user path, the action and the resulting state, side effects; verify what a dry-run actually skips by observing it. - **Cleanup**: kill what you started, never by process name; proof artifacts survive. - **Helpers**: shipped scripts are executable and their invocation is shown in the skill body. 3. **Seed the feature map**: `features/README.md` plus one file per user-facing feature (aim for the top 3-5 to start). 4. **Prove the generated skill** end to end once: launch, doctor, drive ONE mapped feature, capture evidence, clean up, then confirm the evidence still exists. "A generated skill that was never executed is a draft, not a deliverable." 5. **Offer the maintenance loop** (`/maintain-verification-skill`); suggest a cadence only if asked. ### Feature-map file contract The shipped example (`references/feature-map-example/`) maps a fictional "Notes" app driven by a `control-notes` harness. Each feature file has an H1, one paragraph of user-visible behavior, then exactly four H2s in order: | H2 | Contents | |---|---| | `Sub-features` | short IDs, one line each (e.g. `create-save`, `search-empty`) | | `How to get to it (user POV)` | every user entry point (toolbar button, keyboard shortcut, CLI command) | | `Driving it with <harness>` | `Preconditions:` then labeled bullets pairing each action with an exact command and observable result | | `Gotchas` | traps that can waste or invalidate a verification run | The example README also sets proof rules: UI proof = ARIA snapshot + screenshot with the app identity visible; CLI proof = command, stdout, stderr, exit code; mutation proof = a read-only second view of the stored value; "Do not report a skipped entry point as verified through a different path." ### /maintain-verification-skill Pick one outcome: **clean** (no branch, no PR), **changed** (one PR of proven doc, harness, or map corrections), **blocked** (say exactly what blocked it). Pass: 0 locate the target (usually `.cursor/skills/verify-*/`; several → ask; none → point at `/create-verification-skill`), 1 index hygiene, 2 source wave (one read-only subagent per feature file, launched concurrently; children never drive or edit), 3 reconcile, 4 live pass (required even when source looks clean; the coordinator owns all driving), 5 triage (doc drift → fix; harness gap → fix; product gap → report, keep out of the PR), 6 ship or stop. Run notes stay in a scratch location, uncommitted. ## Key Parameters | Item | Value | |---|---| | Output location | `.cursor/skills/verify-<app>/SKILL.md`, `.cursor/skills/verify-<app>/features/README.md` | | Required sections | Launch, Doctor, Drive, Evidence, Cleanup, Helpers | | Initial feature count | aim for top 3-5 features | | Pre-handoff proof | drive ONE mapped feature | | Maintain outcomes | `clean`, `changed`, `blocked` | | Unreachable feature | `verified-unreachable` only with the concrete prerequisite and the route attempted | | Maintain edit scope | only the verification skill's own directory; never product code | | Maintain cadence | guide 06: "at least once a day, ideally from a scheduled automation" (the skill itself suggests a cadence only if asked) | Example prompts from guide 06: ```text /poteto-mode build the bulk-archive action. use /verify-<app> to verify your changes and show me a video and screenshots as proof. /poteto-mode repro this with /verify-<app>. if it repros on main, fix it and show me a video as proof. ``` ## When To Use - The project has no scripted way to prove UI/CLI/service behavior, or agents keep writing throwaway click-through scripts. Guide 06 then suggests building a small control CLI: a few composable commands, `--dry-run` on anything destructive, rich `--help`, machine-readable output such as JSON. - Treat it as infrastructure: commit it so every person and agent drives the app the same way. - Once it works, a `/swarm` can split a full pass by feature-map entry (see [[concepts/orchestration-and-multi-phase-plans]]). - For bugs on paths nobody drives (overlapping retries, lease expiry), use [[concepts/formal-verification]]. ## Risks & Pitfalls - **Never weaken a journey to make it pass.** If seed data lacks a precondition, the journey reports a failure and the reason goes in `Gotchas`. - **A cleanup that eats the proof fails step 4.** Evidence must survive teardown at a named location. - **Shared instances.** If two instances can't run side by side, the generated skill should say so; refusing to double-drive beats corrupting the user's session. - **Stand-in environments.** If proven in a stand-in (a container instead of a fresh VM), list every setup step the stand-in did that the target won't; those stay unverified. - **Product regressions are not doc drift.** Maintain reports them; it never hides them with a doc edit. - **Human-first surface bias (issue #457, `closed` / `not_planned` as of fetch 2026-10-21).** A reporter found the "pick the primary one and note the rest" wording produced a browser-first map; re-inventorying by client class (MCP clients, SDK callers, hooks, webhook senders, device agents) took their surface count from 72 to 171. The proposed wording change was not adopted. Analysis: if your app has non-human clients, ask for them explicitly so they get feature files. ## Related Concepts - [[concepts/formal-verification]]: proving properties tests rarely reach - [[concepts/shipping-prs-and-watch-pr]]: Shipping verifies each PR live before landing - [[concepts/decision-logs]]: committing an auditable proof trail - [[concepts/benchmarks-and-numbers]], [[concepts/poteto-mode]], [[syntheses/overnight-and-autonomous-runs]] ## Sources - raw/github_doc-pstack-skills-create-verification-skill-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/create-verification-skill/SKILL.md) - raw/github_doc-pstack-skills-create-verification-skill-references-feature-m.md (https://github.com/cursor/plugins/blob/main/pstack/skills/create-verification-skill/references/feature-map-example/README.md) - raw/github_doc-pstack-skills-create-verification-skill-references-feature-m-2.md (https://github.com/cursor/plugins/blob/main/pstack/skills/create-verification-skill/references/feature-map-example/create-note.md) - raw/github_doc-pstack-skills-create-verification-skill-references-feature-m-3.md (https://github.com/cursor/plugins/blob/main/pstack/skills/create-verification-skill/references/feature-map-example/search.md) - raw/github_doc-pstack-skills-maintain-verification-skill-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/maintain-verification-skill/SKILL.md) - raw/github_doc-pstack-skills-principle-prove-it-works-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/principle-prove-it-works/SKILL.md) - raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/06-verify-and-ship.md) - raw/github_issue-pstack-457-pstack-create-verification-skill-enumerates-surfaces-by-huma.md (https://github.com/cursor/plugins/issues/457) <!-- ===== pstack/wiki/concepts/worktrees.md ===== --> --- title: "Worktrees and Cleanup (worktree-cleanup playbook, worktree-audit.sh)" type: concept tags: [worktrees, git, cleanup, disk-space, worktree-audit, data-loss] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-skills-poteto-mode-playbooks-worktree-cleanup-md.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-worktree-audit-sh.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-opening-a-pr-md.md", "raw/github_issue-pstack-449-pstack-worktree-cleanup-treats-untracked-and-ignored-files-a.md", "raw/github_issue-pstack-470-worktree-audit-sh-closed-unmerged-prs-and-unpushed-commits-a.md", "raw/github_issue-pstack-567-worktree-audit-sh-merged-is-checked-against-a-hardcoded-orig.md", "raw/github_commits-pstack-log.md"] --- # Worktrees and Cleanup ## Definition pstack does all PR work in **git worktrees**: the Opening a PR playbook says "Work from a git worktree off main. Subagents inherit it." Agents, arenas and repro runs leave many worktrees behind, so `/poteto-mode` has a **Worktree and simulator cleanup** playbook (`playbooks/worktree-cleanup.md`) backed by a read-only audit script, `scripts/worktree-audit.sh`. The playbook calls itself "the one playbook that deletes user state with no code review to catch a slip". ## How It Works ### Worktree rules while building (Opening a PR) - Multiple `Task` calls on the same branch each get their own worktree, or run `git fetch && git reset --hard origin/<branch>` between them. - Dirty branch with unrelated work: patch out, fresh worktree, apply. Snarled worktree: reset from main, redo minimally. - One writer per worktree or branch (Orchestrate; see [[concepts/orchestration-and-multi-phase-plans]]). ### The cleanup playbook (6 steps) 1. **Snapshot and audit.** Record `df -h /`, then run `scripts/worktree-audit.sh [-b <pr-base-ref>] [repo-path]`. Paths come from `git worktree list`, never hand-typed (worktrees can live at `.cursor/worktrees/myrepo/x`). The transcript scan is slow, so background it. 2. **The bucket is advice, not permission.** Get the pinned and active chat set from the user or sidebar; the playbook notes the script 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 doubtful, fan out subagents to read transcripts. Arena and repro trees spawned by a pinned chat are in use even if their names never appear in the sidebar. 4. **Pause on irreversible loss.** `wip:N` = N tracked uncommitted edits: show the diff, get a decision. `scratch:N` = untracked files the playbook calls "safe to drop, but name the files" (see Risks). Clean, merged, not-in-use proceeds; `wip` and in-use pause. 5. **Prune the confirmed set:** `git worktree remove --force <path>`; if the dir survives on ignored build artifacts, `rm -rf` it, then `git worktree prune`. Confirm with `df -h /` and re-list. Branch refs survive. 6. **Simulators and other reclaimers:** `xcrun simctl --set testing delete all`, `xcrun simctl delete unavailable`, `xcrun simctl runtime list` then `runtime delete <id>`; also Xcode `DerivedData` and `iOS DeviceSupport`, `~/Library/Application Support/Cursor` (`state.vscdb.backup`, `snapshots/roots/<root>`), package caches (pnpm, uv, brew, yarn). Clear only caches the user hasn't said to keep. Reply: `df -h /` before and after, worktrees pruned, a one-line reason for each held back. ### What worktree-audit.sh does Usage `worktree-audit.sh [-b|--base <ref>] [repo-path]`; `-h|--help` prints the header. Described in its header as read-only ("Never deletes anything"), though it does run a best-effort `git fetch` of the base (see issue #470). It skips the main worktree and prints `# base: <ref>` then a TSV sorted by size: `SIZE AGE MERGED DIRTY REMOTE PR LAST_CHAT BUCKET WORKTREE` | Column | How it is computed | |---|---| | `MERGED` | `YES` if HEAD is an ancestor of the base (`git merge-base --is-ancestor`), else `no`; misses squash merges, so PR state is the real signal | | `DIRTY` | from `git status --porcelain`: `clean`, `wip:N` (tracked edits), or `scratch:N` (only `??` untracked lines); no `--ignored`, so ignored files are invisible | | `REMOTE` | `detached`, `pushed`, `ahead<N>`, or `no-remote` | | `PR` | `#<n>/<state>` from `origin pr list` if the Origin CLI works, else `gh pr list --author "@me" --state all --limit 1000`; `-` if none | | `LAST_CHAT` | newest transcript under `~/.cursor/projects/<slug>/agent-transcripts` mentioning the path (uses `rg`, BSD `stat -f`/`date -r`) | Bucket logic, in order: `wip:*` → `hold-wip`; PR `open` or `draft` → `hold-open-pr`; chat within 4 days → `verify-recent-chat`; merged or has any PR → `safe`; otherwise `review`. ## Key Parameters | Item | Value | |---|---| | Base ref default | `origin/HEAD`, then `origin/main`, then `origin/master` (warns `no -b given`) | | `-b` | pass `-b origin/<branch>` when PRs target a branch other than the remote default | | Base fetch | best-effort `git fetch origin +refs/heads/<b>:refs/remotes/origin/<b>`, run only when the base starts with `origin/` | | Recent-chat window | 4 days | | Exit codes | 2 for bad option or `-b` without a ref; 1 for not a repo or base ref missing | | Dependencies | `git`, `jq`, `rg`, `du`; `gh` or `origin` for PR state | The commit log records `fix(pstack): worktree-audit checks MERGED against the default branch, not origin/main (#574)` on 2026-10-12. ## When To Use - Disk is filling up with agent worktrees and simulator clones: `/poteto-mode` routes cleanup requests to this playbook (see [[concepts/poteto-mode]]). - Run the audit alone any time; it never deletes. - After overnight runs that spawn many trees ([[syntheses/overnight-and-autonomous-runs]]). ## Risks & Pitfalls - **Data-loss hazard: untracked and ignored files are treated as disposable (issue #449, open as of fetch 2026-10-21).** The reporter points out that untracked/ignored files (run artifacts, evidence dirs, local indexes, `.env` files, notes) are often the most valuable thing in an agent worktree and can't be recovered from the branch, yet step 4 pauses only on `wip:N` and step 5 uses `--force` and `rm -rf`. A commenter, deanrie (who refers decisions to "the pstack maintainer"), reproduced it and found it worse: ignored files aren't detected at all because `git status` runs without `--ignored`, so a worktree with ignored `build/` and `run.log` plus one untracked file showed as `scratch:1` / `review`. He also noted a plain `git worktree remove` is not a sufficient stop either, because Git silently deletes a worktree containing only ignored files. A fix, PR #459 (reclassify as `wip`, check `status --untracked-files=all --ignored=matching`, drop `--force`/`rm -rf`/`prune`), was flagged for merge; the playbook and script fetched on 2026-10-21 still contain the old behavior and #459 does not appear in the fetched commit log. **Until it lands (analysis, not from the sources): list untracked and ignored files yourself (`git -C <wt> status --untracked-files=all --ignored=matching`) and treat any as irreversible loss; do not use `--force` or `rm -rf` on unreviewed trees.** - **Data-loss hazard: closed-unmerged PRs and unpushed commits are bucketed `safe` (issue #470, open as of fetch 2026-10-21).** The `safe` test is `[ "$merged" = YES ] || [ "$pr" != "-" ]`, so a PR in *any* state, including `#N/CLOSED` (closed without merging), makes a worktree `safe`, even though its commits may exist nowhere else. The `REMOTE` column (`ahead<N>`, `no-remote`, `detached`) is computed but never read by the bucket logic. The reporter's repro: `ahead1 #42/CLOSED safe`. The issue also notes the header says "Read-only" while the script runs `git fetch` (writing remote-tracking refs and `FETCH_HEAD`). deanrie reproduced all three and pointed to fix PR #492 (`safe` only on base ancestry or a MERGED PR, `CLOSED` falls to `review`, a new `hold-unpushed` bucket). The script fetched on 2026-10-21 still has the old bucket logic. **Until it lands (analysis, not from the sources): never trust `safe` without checking the `PR` state is `merged` and `REMOTE` is `pushed`.** - **`safe` can be wrong** even beyond #470; the playbook says the pinned-chat set overrides it. - **Hardcoded base (issue #567, closed `completed` as of fetch 2026-10-21).** Older versions checked `MERGED` against a literal `origin/main`, had no way to set the base, and passed `-h` to `cd`. The fetched script has the proposed fix: `-b|--base`, base auto-detection from `origin/HEAD`, a `# base:` header line, and `-h|--help` (matching commit #574 on 2026-10-12). If you run an older pstack, the `MERGED` column may be wrong for repos whose PRs target a non-default branch. - **Squash merges** show `MERGED=no`; read the `PR` column instead. - **Wrong base:** without `-b`, `MERGED` uses the remote default branch, not necessarily the PR target. - **macOS-isms:** the transcript lookup uses `stat -f '%m %N'` and `date -r`, BSD forms; on GNU systems (analysis) the `LAST_CHAT` column is likely to come out as `-`, which weakens the `verify-recent-chat` signal. ## Related Concepts - [[concepts/shipping-prs-and-watch-pr]] · [[concepts/orchestration-and-multi-phase-plans]] · [[syntheses/recipes-and-pitfalls]] · [[summaries/known-issues]] · [[summaries/playbook-catalog]] ## Sources - raw/github_doc-pstack-skills-poteto-mode-playbooks-worktree-cleanup-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/worktree-cleanup.md) - raw/github_doc-pstack-skills-poteto-mode-scripts-worktree-audit-sh.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/worktree-audit.sh) - raw/github_doc-pstack-skills-poteto-mode-playbooks-opening-a-pr-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/opening-a-pr.md) - raw/github_issue-pstack-449-pstack-worktree-cleanup-treats-untracked-and-ignored-files-a.md (https://github.com/cursor/plugins/issues/449) - raw/github_issue-pstack-470-worktree-audit-sh-closed-unmerged-prs-and-unpushed-commits-a.md (https://github.com/cursor/plugins/issues/470) - raw/github_issue-pstack-567-worktree-audit-sh-merged-is-checked-against-a-hardcoded-orig.md (https://github.com/cursor/plugins/issues/567) - raw/github_commits-pstack-log.md (https://github.com/cursor/plugins/commits/main/pstack) <!-- ===== pstack/wiki/entities/benny-automation.md ===== --> --- title: "Benny Automation Pack (Slack issue triage and repro)" type: entity tags: [benny, automations, slack, triage, reproduce, cursor-automations, control-adapter, draft-pr] created: 2026-10-21 updated: 2026-10-21 confidence: high sources: ["raw/github_doc-pstack-automations-benny-readme-md.md", "raw/github_doc-pstack-automations-benny-for-agents-md.md", "raw/github_doc-pstack-automations-benny-skills-setup-benny-skill-md.md", "raw/github_doc-pstack-automations-benny-skills-triage-issue-reports-skill-m.md", "raw/github_doc-pstack-automations-benny-skills-triage-issue-reports-referen.md", "raw/github_doc-pstack-automations-benny-skills-reproduce-and-fix-issues-ski.md", "raw/github_doc-pstack-automations-benny-skills-reproduce-and-fix-issues-ref.md", "raw/github_doc-pstack-automations-benny-skills-reproduce-and-fix-issues-ref-2.md", "raw/github_doc-pstack-automations-benny-skills-reproduce-and-fix-issues-ref-3.md", "raw/github_doc-pstack-automations-benny-templates-configuration-example-yam.md", "raw/github_doc-pstack-automations-benny-templates-triage-automation-prompt-.md", "raw/github_doc-pstack-automations-benny-templates-reproduce-automation-prom.md", "raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-docs-harness-claude-code-md.md", "raw/github_doc-pstack-docs-guide-07-overnight-md.md"] --- # Benny Automation Pack ## Overview **Benny** is a dormant automation pack shipped inside pstack at `pstack/automations/benny/`. It gives you two Cursor Automations for a Slack issue channel: 1. **`benny-triage`** triages each new top-level report and posts one verdict in its thread. 2. **`benny-reproduce`** waits for a bug/performance verdict, reproduces the symptom twice through the real UI with evidence, verifies existing fixes, and may open a bounded **draft** pull request. Its files "are dormant setup and automation sources. they do not appear as slash skills." The `SKILL.md` files (`setup-benny`, `triage-issue-reports`, `reproduce-and-fix-issues`) all carry `disable-model-invocation: true` and are read directly by path, not registered in the plugin manifest. The README states "benny runs on cursor automations, so it is cursor-only"; the Claude Code adapter skips Cursor Automations with a `Skipped in Claude Code:` line (see [[syntheses/pstack-on-claude-code]]). Guide 07 presents it as the example of loops that start themselves ([[syntheses/overnight-and-autonomous-runs]]). ## Characteristics ### Shared rules - Source channel and root thread coordinates are frozen (`SOURCE_CHANNEL_ID`, `SOURCE_THREAD_TS` = `trigger.thread_ts` or else `trigger.ts`) and immutable for the run. - **Never post a root message in the source channel.** The coordinator is the only Slack poster; every child prompt must forbid `SendSlackMessage`, `PostToSlack`, `chat.postMessage` and all other Slack writes. - Utility and debug bots are evidence, not fix ownership. - Fail closed if channel coordinates, tracker access, the control adapter or the feature map are missing or uncertain. - Draft PRs only. Never merge or deploy. ### Triage (`triage-issue-reports`) Freeze coordinates → read the whole thread and attachments → trace cause with pstack's `how` (and `why` for regressions) → classify as **Bug**, **Performance**, **Feature request**, **Question or feedback**, or **Reroute** → apply the optional routing map → dedupe in the tracker → create an issue only for a clear, live, net-new bug/performance item → post exactly one verdict ending in one marker → watch one follow-up window. The tracker is an adapter (Linear is one valid example; GitHub Issues works if it implements the contract). If a created issue's verdict post fails, the adapter's compensation action must cancel, close or delete it. Marker contract: ```text [benny:bug] [benny:bug] tracker=https://tracker.example/issue/123 [benny:performance] [benny:performance] tracker=https://tracker.example/issue/123 [benny:other] ``` **Routing map** (`routing.example.md`): `routes` with `match` (`product_areas`, `code_paths`, `error_signatures`), `destination` (`slack_channel`, `tracker_team`), `owners`, `allow_feature_owner_ping`; plus `fallback` and `ping_policy` (default `"off"`; allow `configured-feature-owner`, `confirmed-regression-author`). A keyword match alone is not enough; reroutes never cross-post. ### Reproduce and fix (`reproduce-and-fix-issues`) Accepts a verdict only from `slack.triage_identity_user_id`, as a reply in the thread, with exactly one marker; proceeds only on `bug`/`performance`. Gates: stop if a person claims the fix; switch to **verify mode** (`references/verify-existing-fix.md`) if an open PR or merged commit plausibly fixes it. The optional operations channel's one root status message is the only allowed root post. Repro requires the exact discriminating symptom **twice** through real UI, media review confirming it, and a rejection window before any fix. A bounded fix uses `tdd` when a cheap test exists, must show before-and-after evidence twice on the patched build, smokes the blast radius, then opens a draft PR. Verify mode outcomes: **Confirmed**, **Insufficient fix**, **Inconclusive**; it never opens a competing PR. **Control-adapter contract** (`references/control-adapter.md`): seven capabilities: bring up, drive UI, drive mapped features and states, inspect state (read-only), screenshot, recording, cleanup. Never inject the symptom; prefer roles/labels, never generated CSS/StyleX classes or DOM position. A nine-step setup check must pass before enabling repro. **Feature map** (`feature-map.example.md`): per feature, how a user gets there, how the adapter drives it, stable selectors, states to exercise, preconditions, evidence and cross-check, gotchas (similar in spirit to [[concepts/verification-skills]] maps). ## How to Use 1. Point Cursor at `pstack/automations/benny/FOR_AGENTS.md` and name the target repository. Don't look for a `/benny` slash skill. 2. Setup merges the whole pack into `<target-repository>/.cursor/automations/benny/`, preserving destination-only files and reviewing diffs rather than overwriting. 3. Enable pstack in the target's `.cursor/settings.json` (preserving other settings and JSONC comments): ```json { "plugins": { "pstack": { "enabled": true } } } ``` 4. A fresh agent in the target repo must resolve from project scope: `how`, `why`, `tdd`, `unslop`, `principle-separate-before-serializing-shared-state`, `principle-minimize-reader-load`, `principle-guard-the-context-window`, `principle-sequence-verifiable-units`, `principle-fix-root-causes`, `principle-prove-it-works`. Session or user-scoped skills don't count. 5. Copy config, feature map and routing map **outside** the pack, e.g. `.cursor/benny/configuration.yaml`, `.cursor/benny/feature-map.md`, `.cursor/benny/routing.md`. Use only model slugs available in your Cursor model picker. 6. Commit `.cursor/settings.json`, `.cursor/automations/benny/` and secret-free config before enabling either automation. 7. First-time creation: built-in `/automate` once for triage, finish its editor handoff, then once for repro. Live prompts must say "Read and follow `.cursor/automations/benny/skills/triage-issue-reports/SKILL.md`" (or `reproduce-and-fix-issues/SKILL.md`), never a plugin cache path. Existing automations: `/automate` is creation-only; edit them in the Automations editor. 8. Run the seven-point thread-safety test with a harmless report before enabling normal traffic. ### configuration.example.yaml keys ```text schema_version: 1 automations: { triage_name: "benny-triage", reproduce_name: "benny-reproduce" } slack: source_channel_id, operations_channel_id, triage_identity_user_id, read_action, thread_post_action, file_download_action, operations_edit_action, prefer_cursor_actions: true, optional_bot_token_env: "BENNY_SLACK_BOT_TOKEN", allow_source_root_posts: false, allow_worker_slack_writes: false repository: url, default_branch: "main", pull_request_action, pull_request_url_format: "https://github.com/{owner}/{repo}/pull/{number}", draft_only: true tracker: type: "linear", adapter_skill_name, team, project, labels: { bug, performance, intake, needs_repro }, status, source_link_title: "Slack report", require_compensation_action: true routing: map_path: ".cursor/benny/routing.md", owner_pings_default: false, allow_feature_owner_ping: false, allow_confirmed_regression_author_ping: false control: skill_name: "control-target-app", feature_map_path: ".cursor/benny/feature-map.md", environment, artifact_directory: "/tmp/benny-artifacts", artifact_retention_hours: 24 verdict_markers: bug: "[benny:bug]", performance: "[benny:performance]", other: "[benny:other]", tracker_attribute: "tracker" status_emoji: seen, reproducing, reproduced, could_not_reproduce, blocked, fixing, fix_failed, pull_request_opened budgets: poll_seconds: 45, verdict_wait_minutes: 45, triage_follow_up_minutes: 10, triage_total_minutes: 30, repro_minutes: 60, rejection_window_minutes: 10, fix_minutes: 90, operations_follow_up_minutes: 45 models: triage, reproduce, code, media_review ``` (Condensed listing; the real file is block-style YAML with placeholder values.) Keep `BENNY_SLACK_BOT_TOKEN` in a secret manager or environment, never in YAML. ## Related Entities - [[entities/pstack]]: the plugin that ships the pack - [[concepts/verification-skills]]: feature-map and evidence conventions - [[concepts/shipping-prs-and-watch-pr]]: draft PRs and review flow - [[syntheses/overnight-and-autonomous-runs]], [[syntheses/pstack-on-claude-code]] ## Sources - raw/github_doc-pstack-automations-benny-readme-md.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/README.md) - raw/github_doc-pstack-automations-benny-for-agents-md.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/FOR_AGENTS.md) - raw/github_doc-pstack-automations-benny-skills-setup-benny-skill-md.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/skills/setup-benny/SKILL.md) - raw/github_doc-pstack-automations-benny-skills-triage-issue-reports-skill-m.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/skills/triage-issue-reports/SKILL.md) - raw/github_doc-pstack-automations-benny-skills-triage-issue-reports-referen.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/skills/triage-issue-reports/references/routing.example.md) - raw/github_doc-pstack-automations-benny-skills-reproduce-and-fix-issues-ski.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/skills/reproduce-and-fix-issues/SKILL.md) - raw/github_doc-pstack-automations-benny-skills-reproduce-and-fix-issues-ref.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/skills/reproduce-and-fix-issues/references/control-adapter.md) - raw/github_doc-pstack-automations-benny-skills-reproduce-and-fix-issues-ref-2.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/skills/reproduce-and-fix-issues/references/feature-map.example.md) - raw/github_doc-pstack-automations-benny-skills-reproduce-and-fix-issues-ref-3.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/skills/reproduce-and-fix-issues/references/verify-existing-fix.md) - raw/github_doc-pstack-automations-benny-templates-configuration-example-yam.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/templates/configuration.example.yaml) - raw/github_doc-pstack-automations-benny-templates-triage-automation-prompt-.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/templates/triage-automation-prompt.md) - raw/github_doc-pstack-automations-benny-templates-reproduce-automation-prom.md (https://github.com/cursor/plugins/blob/main/pstack/automations/benny/templates/reproduce-automation-prompt.md) - raw/github_doc-pstack-readme-md.md (https://github.com/cursor/plugins/blob/main/pstack/README.md) - raw/github_doc-pstack-docs-harness-claude-code-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/harness/claude-code.md) - raw/github_doc-pstack-docs-guide-07-overnight-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/07-overnight.md) <!-- ===== pstack/wiki/entities/poteto-agent-and-comment-sicko.md ===== --> --- title: "poteto-agent and Comment Sicko (subagents)" type: entity tags: [pstack, subagents, poteto-agent, comment-sicko, no-comments, delegation] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-agents-poteto-agent-md.md", "raw/github_doc-pstack-agents-comment-sicko-md.md", "raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-docs-harness-claude-code-md.md", "raw/github_issue-pstack-483-pstack-comment-sicko-agent-name-has-a-space-and-grok-rejects.md", "raw/github_issue-pstack-357-pstack-poteto-agent-description-routes-poteto-mode-into-a-ne.md"] --- # poteto-agent and Comment Sicko (subagents) ## Overview pstack ships two subagent definitions in `agents/`: - **`poteto-agent`** (`agents/poteto-agent.md`) — the wrapper for delegates spawned during a `/poteto-mode` run: code-writing delegates and ad-hoc helpers. - **Comment Sicko** (`agents/comment-sicko.md`, frontmatter `name: comment-sicko`) — a comment reviewer that the README calls "read-only" and whose own file describes it as "a deranged comment-hater that savors deletion and condemns workaround code." Its file says it touches comments and flags refactor targets (its report includes a deletion count), and that it never writes application code. ## Characteristics | | poteto-agent | Comment Sicko | |---|---|---| | Cursor `subagent_type` | `"poteto-agent"` | `"comment-sicko"` | | Claude Code type | `pstack:poteto-agent` | `pstack:comment-sicko` | | Frontmatter | `is_background: true` | — | | Writes code? | Yes (delegate) | No application code ("I never write application code"); it touches comments and reports | | Usual entry point | Spawned by `/poteto-mode` playbook steps | Via `/no-comments`, not directly | **poteto-agent behavior.** It operates as poteto-mode's full agent style. Before any work it reads `poteto-mode`'s SKILL.md in full, including the inline Principles index, using the absolute path the parent gave it. With no path, it searches `~/.cursor/plugins/` for a file ending in `skills/poteto-mode/SKILL.md`; if several match, it uses the copy whose `.cursor-plugin/plugin.json` has the highest `version`. Its skill catalog hides poteto-mode, so a missing catalog entry doesn't mean pstack is absent. If no file exists, it stops and tells the parent. It navigates to a leaf `principle-*` skill whenever it applies that principle. **Comment Sicko behavior.** Its first output is exactly "Yes... Ha ha ha... Yes!". It reviews the parent-scoped files or diff, else the current diff against `main`. Only these comments survive: legal/license headers; non-obvious behavior forced by an external dependency, platform, vendor, or protocol; `// prettier-ignore`; lint suppressions whose rule is faulty, pedantic, or style-only; doc comments defining a public API contract; issue or RFC links explaining a constraint code can't express. When unsure, the comment dies. Surprises in your own code get the exact symbol marked `MUST KILL` for a rename, extract, type, or rearchitecture. Suppressions like `eslint-disable`, `@ts-ignore`, `@ts-expect-error` die (with `MUST KILL`) when the rule protects correctness or safety. Claims like `IMPORTANT` or `do not remove` are checked by reading nearby code and running `/how` or `/why` if needed. The report names touched files, deletion count, `MUST KILL` flags (one line each), and skips. ## How to Use - Let `/poteto-mode` spawn `poteto-agent` for you. To get the same style from your own subagent, spawn it with `subagent_type: "poteto-agent"` (per `/poteto-help`). Put the absolute path of poteto-mode's SKILL.md in the prompt. - Spawn a fresh `poteto-agent` for each new task; resume only in the strict cases poteto-mode's Subagents section names (state that lives in that agent: its checkout, uncommitted changes, or a running process). - Run `/no-comments` before review; it spawns Comment Sicko, fixes accepted findings, and offers encodings for claimed constraints. **When not to use:** - Never spawn `poteto-agent` to run the playbook itself. The chat that receives `/poteto-mode` owns the playbook, todo list, and every spawn. - Don't substitute `generalPurpose`; it skips the full read and drifts. - Don't override the `subagent_type` that routed skills (`how`, `why`, `interrogate`, `reflect`, `swarm`) prescribe for diverse-model review. - Don't invoke Comment Sicko directly for routine work; go through `/no-comments`. **Known issues (state as of fetch 2026-10-21):** - **#357 (closed, completed 2026-10-12).** The old `poteto-agent` description called itself the "Routing target for `/poteto-mode`". On a Cursor Cloud Agent, a parent spawning one `poteto-agent` to run the playbook left the child without the Task tool or a working todo list (Cloud Agents allow one nesting level, per a cited Cursor staff forum post), so how/why, Comment Sicko, and delegates never ran. The current description says "Use for delegates, not as the runner". - **#483 (closed, completed 2026-10-12).** In pstack 0.15.5 the agent was `name: Comment Sicko`; Grok Build's `spawn_subagent` rejected `pstack:Comment Sicko`. A comment by deanrie (who writes from the Cursor side; not the pstack maintainer) said the space was fine on Cursor and the failure was in Grok Build's resolver, and pointed to PR #486, which renames it to `comment-sicko`. The current file has `name: comment-sicko`. ## Related Entities - [[entities/pstack]] - [[concepts/poteto-mode]] — Subagents section and model split - [[concepts/build-and-clean]] — where `/no-comments` fits - [[syntheses/pstack-on-claude-code]] — `pstack:` prefixed types - [[summaries/known-issues]] ## Sources - raw/github_doc-pstack-agents-poteto-agent-md.md — https://github.com/cursor/plugins/blob/main/pstack/agents/poteto-agent.md - raw/github_doc-pstack-agents-comment-sicko-md.md — https://github.com/cursor/plugins/blob/main/pstack/agents/comment-sicko.md - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-skills-poteto-mode-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md - raw/github_doc-pstack-docs-harness-claude-code-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/harness/claude-code.md - raw/github_issue-pstack-483-pstack-comment-sicko-agent-name-has-a-space-and-grok-rejects.md — https://github.com/cursor/plugins/issues/483 - raw/github_issue-pstack-357-pstack-poteto-agent-description-routes-poteto-mode-into-a-ne.md — https://github.com/cursor/plugins/issues/357 <!-- ===== pstack/wiki/entities/pstack.md ===== --> --- title: "pstack (plugin)" type: entity tags: [pstack, plugin, cursor, manifest, version, license] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-plugin-json.md", "raw/github_doc-pstack-cursor-plugin-plugin-json.md", "raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-docs-harness-claude-code-md.md", "raw/github_commits-pstack-log.md", "raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md"] --- # pstack (plugin) ## Overview pstack is a Cursor plugin of rigorous agent-engineering skills, published in the `cursor/plugins` repository under the `pstack/` folder. Its manifest description: "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence." The author in both manifests is Lauren Tan; the README is written by poteto, who describes working at Meta, Netflix, and Cursor and on the React core team (React Compiler). ## Characteristics **Manifest facts** (as the raw files state them, fetched 2026-10-21): | Field | `pstack/plugin.json` | `pstack/.cursor-plugin/plugin.json` | |---|---|---| | `name` | `pstack` | `pstack` (plus `displayName`: `pstack`) | | `version` | `0.15.29` | `0.15.29` | | `author.name` | Lauren Tan | Lauren Tan | | `license` | MIT | MIT | | `homepage` | `https://github.com/cursor/plugins/tree/main/pstack` | same | | `repository` | `https://github.com/cursor/plugins` | same | | `$schema` | `https://agent-plugins.org/schemas/1.0.0/plugin.schema.json` | — | | `keywords` | `pstack`, `poteto-mode`, `workflow`, `principles`, `agent-style`, `subagents`, `unslop` | same | | Extra fields | — | `logo: assets/logo.png`, `category: developer-tools`, `tags: [workflow, principles, review, planning]`, `skills: ./skills/`, `agents: ./agents/` | Both manifests agree on version `0.15.29`. The commit log's newest version-bump commit is "bump to 0.15.28" (#724, 2026-10-19); the log does not show a 0.15.29 bump commit, but issue #734 also references "the local 0.15.29 source". See [[summaries/release-history]]. **Directory layout** (from the manifests, README, and adapter): - `skills/` — every skill, one folder each with `SKILL.md` (plus `references/` where present). `skills/poteto-mode/` also holds `playbooks/` (23 playbooks) and `scripts/` (playbook tooling; see [[concepts/poteto-mode]]). The 24 principles are `skills/principle-*`. - `agents/` — `poteto-agent.md` and `comment-sicko.md`. - `automations/benny/` — the dormant benny pack; setup starts from `FOR_AGENTS.md`. - `docs/guide/` — guide pages 01–10 plus README; `docs/harness/claude-code.md` — the Claude Code adapter. - `README.md`, `plugin.json`, `.cursor-plugin/plugin.json`, `assets/logo.png`. The README tables list 32 skills and 24 principles; issue #734's Codex measurement counted 56 pstack skills. **Harness copy.** Claude Code installs a generated copy from `harness/pstack/` at the repository root (not `pstack/`). After changing pstack, run `node scripts/generate-pstack-harness-trees.mjs` from the repository root and commit the result; CI fails while the generated copy is out of date. **Release cadence.** The commit log shows frequent patch bumps (for example 0.15.25 on 2026-10-14, 0.15.26 and 0.15.27 on 2026-10-18, 0.15.28 on 2026-10-19). Details in [[summaries/release-history]]. ## How to Use - Cursor: `/add-plugin pstack`. - Claude Code: `/plugin marketplace add cursor/plugins`, then `/plugin install pstack@cursor-plugins`; commands become `/pstack:<name>`. - Then `/setup-pstack` and `/poteto-mode` ([[syntheses/getting-started]]). - Install `cursor-team-kit` alongside for `/deslop`, `control-cli`, and `control-ui`. - The README invites forks and PRs: "fork it. improve it. make it yours." ## Related Entities - [[entities/poteto-agent-and-comment-sicko]] — the bundled subagents - [[entities/benny-automation]] — the bundled automation pack - [[syntheses/overview]], [[summaries/skill-catalog]], [[summaries/known-issues]] - [[syntheses/pstack-on-claude-code]] ## Sources - raw/github_doc-pstack-plugin-json.md — https://github.com/cursor/plugins/blob/main/pstack/plugin.json - raw/github_doc-pstack-cursor-plugin-plugin-json.md — https://github.com/cursor/plugins/blob/main/pstack/.cursor-plugin/plugin.json - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-docs-harness-claude-code-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/harness/claude-code.md - raw/github_commits-pstack-log.md — https://github.com/cursor/plugins/commits/main/pstack - raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md — https://github.com/cursor/plugins/issues/734 <!-- ===== pstack/wiki/log.md ===== --> --- title: "Activity Log" type: log --- # Activity Log Append-only record of all wiki changes. ## Format Each entry follows this format: ``` ### YYYY-MM-DD HH:MM — [Action Type] - **Source/Trigger**: what initiated the action - **Pages created**: list of new pages - **Pages updated**: list of updated pages - **Notes**: any contradictions flagged, decisions made ``` --- ### 2026-04-08 00:00 — Setup - **Source/Trigger**: Repository initialized - **Pages created**: index.md, log.md, dashboard.md, analytics.md, flashcards.md - **Pages updated**: none - **Notes**: Empty knowledge base ready for first source ingestion ### 2026-10-21 — Initial build - **Source/Trigger**: new topic wiki on pstack (cursor/plugins/pstack, MIT), gathered from the plugin directory plus 25 hand-captured pstack issues and the pstack commit log - **Pages created**: 30 (6 syntheses · 16 concepts · 3 entities · 5 summaries); see [[index]] - **Pages updated**: none - **Notes**: Version: both manifests say 0.15.29 but the newest bump commit in the log is 0.15.28 (#724). Issue states are as of fetch 2026-10-21; several open issues (#237, #701, #474) describe problems the fetched files no longer show, and pages say so. Open data-loss hazards in worktree tooling (#449, #470) are flagged on the worktrees page. <!-- ===== pstack/wiki/summaries/known-issues.md ===== --> --- title: "Known Issues" type: summary tags: [pstack, issues, bugs, workarounds, data-loss, watch-pr, harness] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_issue-pstack-237-pstack-poteto-mode-name-breaks-the-documented-identifier-con.md", "raw/github_issue-pstack-335-pstack-default-task-model-slugs-are-unresolvable-in-current-.md", "raw/github_issue-pstack-343-fix-pstack-treat-an-empty-check-rollup-as-no-checks.md", "raw/github_issue-pstack-357-pstack-poteto-agent-description-routes-poteto-mode-into-a-ne.md", "raw/github_issue-pstack-367-pstack-disable-model-invocation-skills-still-have-use-only-w.md", "raw/github_issue-pstack-393-pstack-route-comprehension-gaps-to-teach.md", "raw/github_issue-pstack-446-pstack-is-grok-build-a-supported-target-xai-official-marketp.md", "raw/github_issue-pstack-449-pstack-worktree-cleanup-treats-untracked-and-ignored-files-a.md", "raw/github_issue-pstack-457-pstack-create-verification-skill-enumerates-surfaces-by-huma.md", "raw/github_issue-pstack-483-pstack-comment-sicko-agent-name-has-a-space-and-grok-rejects.md", "raw/github_issue-pstack-523-pstack-competing-open-prs-for-the-same-issue-require-manual-.md", "raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md", "raw/github_issue-pstack-601-pstack-claude-code-and-codex-mapping-for-cursor-specific-ins.md", "raw/github_issue-pstack-630-feat-pstack-add-more-slop-patterns-to-unslop-skill.md", "raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md", "raw/github_issue-pstack-730-pstack-orch-stale-lock-takeover-can-be-lost-unlink-then-crea.md", "raw/github_issue-pstack-731-pstack-watch-pr-blocked-merge-state-with-green-ci-reports-re.md", "raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md", "raw/github_issue-pstack-750-pstack-watch-pr-status-only-retries-for-minutes-on-a-repo-wi.md", "raw/github_commits-pstack-log.md", "raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-agents-comment-sicko-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-worktree-cleanup-md.md", "raw/github_issue-pstack-470-worktree-audit-sh-closed-unmerged-prs-and-unpushed-commits-a.md", "raw/github_issue-pstack-471-watch-pr-review-threads-are-fetched-without-pagination-first.md", "raw/github_issue-pstack-474-principle-test-behavior-not-implementation-listed-matchers-d.md", "raw/github_issue-pstack-531-ci-and-validator-cover-manifests-only-skills-hooks-mcp-json-.md", "raw/github_issue-pstack-567-worktree-audit-sh-merged-is-checked-against-a-hardcoded-orig.md", "raw/github_issue-pstack-701-poteto-mode-claude-code.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-worktree-audit-sh.md", "raw/github_doc-pstack-skills-principle-test-behavior-not-implementation-ski.md"] --- # Known Issues All 25 pstack issues in the corpus. Each row gives the number, the title (abridged), the **state as of fetch 2026-10-21** (from the issue frontmatter), the problem in a phrase, any workaround the thread offers, and the wiki page that covers the area. Grouped by severity, with data-loss and correctness hazards first. A closed issue may still describe behavior you meet on older installed versions. Replies in most threads come from "deanrie", a Cursor-side responder who repeatedly refers questions to "the pstack maintainer"/"the owner"; they are not the maintainer, so decisions are described as pending unless a merged commit shows otherwise. ## Key Points ### 1. Data-loss and correctness hazards | # | Title | State | Problem | Workaround / status in thread | Page | |---|---|---|---|---|---| | 449 | worktree-cleanup treats untracked and ignored files as disposable (`--force`, `rm -rf`) | open | The audit script calls untracked files "disposable untracked scratch". The playbook runs `git worktree remove --force` then `rm -rf`. A Cursor-side commenter (deanrie, who says the PR is flagged "to the pstack maintainer") adds that ignored files aren't detected at all (`git status` runs without `--ignored`), and that a plain `git worktree remove` silently deletes a worktree that holds only ignored files | The reporter routes cleanup to their own retirement procedure, and a Cursor-side commenter (deanrie) endorses that until PR #459 lands. #459 adds a `status --untracked-files=all --ignored=matching` check and drops `--force`/`rm -rf`/`prune`. The fetched playbook still contains `--force` and `rm -rf` | [[concepts/worktrees]] | | 470 | worktree-audit.sh: closed-unmerged PRs and unpushed commits are bucketed as safe; script fetches despite read-only header | open | Any non-open PR state, including `#N/CLOSED`, puts a worktree in `safe`. The `ahead`/`no-remote`/`detached` remote state is computed but never used. The script also runs a fetch despite its "read-only" header | deanrie reproduced it (not the maintainer). PR #492 adds a `hold-unpushed` bucket, makes `CLOSED` fall through to `review`, and corrects the header. In the fetched `worktree-audit.sh` the `safe` branch still reads `[ "$pr" != "-" ]`. Until it lands, check the REMOTE and PR columns yourself before pruning | [[concepts/worktrees]] | | 567 | worktree-audit.sh: MERGED checked against a hardcoded `origin/main` | closed (completed, 2026-10-12) | In repos whose PRs target another branch, `MERGED` showed `no` and the `safe` bucket was built on it | Closed the day commit `cf9a111` (#574) landed ("worktree-audit checks MERGED against the default branch, not origin/main"). That is likely the fix, but the issue doesn't name it. The fetched script takes `-b <ref>` and falls back to origin/HEAD, then origin/main, then origin/master. Pass `-b origin/<branch>` when PRs target another branch | [[concepts/worktrees]] | | 730 | orch stale-lock takeover can be lost (unlink-then-create TOCTOU); frontier SHAs use local branches | open | In `skills/poteto-mode/scripts/orch/store.ts`, `acquireLock`'s takeover is `unlink` then `create`, so two processes can both "hold" the lock and one update is lost. Separately, frontier SHAs come from local branches, not PR heads | None for users. deanrie confirmed it on main and sketched a fix: a second `wx` file `<lock>.takeover` plus a two-taker test, "PR to follow" | [[concepts/orchestration-and-multi-phase-plans]] | | 731 | watch-pr: BLOCKED merge state with green CI reports ready | open | `assessGitHubMerge` treats `mergeStateStatus: "BLOCKED"` with a passing rollup as allowed, so a PR blocked on a missing required review classifies as `ready` | deanrie says this is intentional as written: `ready` means "nothing in CI stands in the way", and required reviews are the human's step. Read `ready` as CI-clean only. The question went to the owners as a product call | [[concepts/shipping-prs-and-watch-pr]] | ### 2. watch-pr stalls and blind spots | # | Title | State | Problem | Workaround | Page | |---|---|---|---|---|---| | 750 | watch-pr `--status-only` retries for minutes on a repo with no checks | open | An empty `gh pr checks` plus an empty GraphQL rollup throws a retryable `ChecksUnavailable`. Babysit's check mode stalls through 60/120/240 s backoffs | A downstream fork (MaxFabian25/pstack-harness-adaptations PRs #2 and #5) adds a `ci-none` state and a one-error budget for `--status-only`. Polling mode is deliberately unchanged | [[concepts/shipping-prs-and-watch-pr]] | | 471 | watch-pr: review threads fetched without pagination (first 100 only) | closed (completed, 2026-10-12) | On a PR with 100+ review threads, an unresolved thread past the first page was invisible to the readiness decision | Fixed by commit `ff8f83d` (#484, paginates review threads). Comments past the first 10 per thread are still not read, which the reporter and deanrie say matters less | [[concepts/shipping-prs-and-watch-pr]] | | 343 | fix: treat an empty check rollup as no checks | closed (not_planned, 2026-09-09) | Same symptom: `RETRY: GitHub status query failed` … `TIMEOUT` on a `MERGEABLE`/`CLEAN` PR with no checks | None given. Analysis: the same symptom is what #750 reports again for `--status-only` (that issue is open) | [[concepts/shipping-prs-and-watch-pr]] | ### 3. Skill or agent fails to load or invoke | # | Title | State | Problem | Workaround / status | Page | |---|---|---|---|---|---| | 237 | poteto-mode `name` breaks the identifier constraint | open | `name: Poteto Mode` didn't match the folder. It fails silently on Kiro, fails `skills-ref`, and in Claude Code shows `/pstack:Poteto Mode`, which can't be sent | Commenters renamed `name:` to the folder name locally. Commit `a968159` "name every skill after its folder (#702)" landed 2026-10-17, and the fetched poteto-mode SKILL.md now reads `name: poteto-mode`. The issue was still open at fetch | [[concepts/poteto-mode]] | | 701 | Poteto Mode Claude Code | open | In Claude Code the skill shows up as `/pstack:Poteto Mode` and fails with `Unknown command: /Poteto`. Sometimes it shows as `/pstack:poteto-mode` | deanrie's comment says "`/pstack:poteto-mode` is the form that resolves", pending #619/#696. **Conflict:** that comment says SKILL.md declares `name: Poteto Mode`, but the fetched SKILL.md declares `name: poteto-mode` after commit #702 (2026-10-17). The issue was filed the same day, so older installs may still show the bad name | [[syntheses/pstack-on-claude-code]] | | 483 | Comment Sicko agent name has a space and Grok rejects the spawn | closed (completed, 2026-10-12) | Grok Build's `spawn_subagent` can't resolve `pstack:Comment Sicko`, so `/no-comments` can't start its reviewer | Fixed by #486. The fetched agent file has `name: comment-sicko` | [[entities/poteto-agent-and-comment-sicko]] | | 357 | poteto-agent description routes /poteto-mode into a nested runner | closed (completed, 2026-10-12) | On Cloud Agents only one subagent level is allowed. A spawned `poteto-agent` running the playbook has no Task tool and no working todo list | Likely fixed by #575 (commit 2bd5dd4 "make the /poteto-mode chat the runner, poteto-agent a delegate"; the thread does not name the fix, and the PR #358 in the thread was reported conflicting). poteto-mode now says "Never spawn a `poteto-agent` to run the playbook itself." | [[entities/poteto-agent-and-comment-sicko]] | | 527 | disable-model-invocation hides /poteto-mode's routed skills | closed (completed, 2026-10-12) | Flagged leaf skills were missing from the agent's skill list and rejected by the Skill tool. The hub couldn't find them | Likely commit #577 "tell agents where bundled leaf skills live" (closed the same day; the issue does not name it). poteto-mode now says "Bundled skills live at `../<name>/SKILL.md`" | [[concepts/poteto-mode]] | | 726 | in Claude Code, poteto-mode cites principles without reading their SKILL.md | open | Audit: 0 of 18 runs read a principle file, and 1 read the Claude Code adapter | A one-line patch moved reads to 7/72 runs. Listing principles inside each playbook reached 68/72 (commenter's omp/Sonnet experiment, not retested on Claude Code). The owner decides (deanrie: "Which variant ships is the owner's call") | [[syntheses/pstack-on-claude-code]] | | 335 | default Task model slugs are unresolvable in current Cursor | open | Defaults like `claude-opus-5-5-max` and `gpt-5.6-sol-max` fail with `Invalid model selection … Allowed model slugs:` because the Task allow-list exposes one effort tier per family | Pick the closest Task-valid slug from the error list, as the `interrogate` skill advises, e.g. a `-medium`/`-high` tier. deanrie (Cursor-side commenter) calls the Cursor side "a known, tracked product gap" and leaves the `-medium` downgrade call "to the maintainer" | [[concepts/installation-and-model-setup]] | | 367 | disable-model-invocation skills still have "Use only when user…" text | open | Descriptions such as `tdd`'s still read as routing rules though the skill only runs on its slash command | deanrie says the description goes to the slash menu, not the model's context, so there is no hidden token cost. PR #392 rewrites them (reported conflicting, needs a rebase); unslop's leftover is fixed in #514 | [[summaries/skill-catalog]] | ### 4. Non-Cursor harness support (requests and questions) | # | Title | State | Gist | Page | |---|---|---|---|---| | 446 | is Grok Build a supported target? | open | xAI's marketplace lists pstack unmodified. `Task` spawning, same-run `/loop` and `.mdc` rules are Cursor-specific. deanrie (not the maintainer) says no README position yet and has flagged it to the maintainer | [[syntheses/pstack-on-claude-code]] | | 601 | Claude Code and Codex mapping for Cursor-specific instructions | open | External adaptation at MaxFabian25/pstack-harness-adaptations: a `harnesses.md` map, cross-family panel seats, and Codex custom agents. No upstream PR | [[syntheses/pstack-on-claude-code]] | | 734 | support Codex installation and native agents | open | A commenter measured that `codex plugin marketplace add cursor/plugins` then `codex plugin add pstack@cursor-plugins` installs today (Codex CLI 0.163.0, pstack 0.15.29). Codex ignores `disable-model-invocation`; an `agents/openai.yaml` with `allow_implicit_invocation: false` restores typed-only behavior | [[concepts/installation-and-model-setup]] | ### 5. Guidance errors, repo hygiene, and feature requests | # | Title | State | Gist | Page | |---|---|---|---|---| | 393 | route comprehension gaps to teach | closed (completed, 2026-09-18) | Route "what does this represent?" signals during design to `/teach` | [[concepts/understanding-code]] | | 457 | create-verification-skill enumerates surfaces by human entry point | closed (not_planned, 2026-09-29) | "pick the primary one and note the rest" yields single-surface maps that miss programmatic clients | [[concepts/verification-skills]] | | 474 | principle-test-behavior-not-implementation: listed matchers do not all pass when imports return undefined | open | The skill listed `toBeDefined`, `toBeTruthy`, `toEqual([])` etc. as passing when imports return `undefined`. They fail or throw | A commenter says #633 (2026-10-14) removed the matcher list. The fetched principle file no longer names those matchers. Likely resolved but still open at fetch | [[summaries/principles-catalog]] | | 531 | CI and validator cover manifests only | open | `validate-plugins.yml` triggers only on manifest/schema paths, so `SKILL.md`, agents and scripts changes run no CI. pstack's `bun test orch watch-pr` suites never run in CI | PR #582 broadens paths and adds path-existence checks. Frontmatter parsing, a lockfile and a test job are still open. Run the script tests locally | [[entities/pstack]] | | 523 | competing open PRs for the same issue need manual comparison | open | `babysit`/`shipping` take one PR or stack, so there is no N-candidates compare | [[concepts/shipping-prs-and-watch-pr]] | | 630 | add more slop patterns to unslop | open | Process narration ("Let me…", "rather than…") isn't covered. deanrie suggests one new "Process narration" rule | [[concepts/technical-writing-and-unslop]] | ## Relevant Concepts - [[syntheses/recipes-and-pitfalls]] — troubleshooting table built from these issues - [[summaries/release-history]] — commits that closed #357, #483, #527 - [[concepts/shipping-prs-and-watch-pr]] — watch-pr behavior behind #343/#731/#750 - [[concepts/worktrees]] — the #449/#470 hazards in context ## Source Metadata - Issue files `raw/github_issue-pstack-<n>-*.md` for #237, #335, #343, #357, #367, #393, #446, #449, #457, #470, #471, #474, #483, #523, #527, #531, #567, #601, #630, #701, #726, #730, #731, #734, #750 — https://github.com/cursor/plugins/issues/<n> - raw/github_commits-pstack-log.md — https://github.com/cursor/plugins/commits/main/pstack - raw/github_doc-pstack-skills-poteto-mode-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md - raw/github_doc-pstack-agents-comment-sicko-md.md — https://github.com/cursor/plugins/blob/main/pstack/agents/comment-sicko.md - raw/github_doc-pstack-skills-poteto-mode-playbooks-worktree-cleanup-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/worktree-cleanup.md - raw/github_doc-pstack-skills-poteto-mode-scripts-worktree-audit-sh.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/worktree-audit.sh - raw/github_doc-pstack-skills-principle-test-behavior-not-implementation-ski.md — https://github.com/cursor/plugins/blob/main/pstack/skills/principle-test-behavior-not-implementation/SKILL.md - States are as of fetch 2026-10-21. <!-- ===== pstack/wiki/summaries/playbook-catalog.md ===== --> --- title: "Playbook Catalog" type: summary tags: [pstack, poteto-mode, playbooks, catalog, routing] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-authoring-a-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autonomous-run-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-full-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-stack-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-babysit-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-bug-fix-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-eval-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-feature-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-hillclimb-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-investigation-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-multi-phase-plan-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-opening-a-pr-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-pause-safely-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-perf-issue-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-prototype-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-refactoring-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-runtime-forensics-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-session-pickup-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-shipping-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-trace-forensics-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-visual-parity-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-worktree-cleanup-md.md", "raw/github_issue-pstack-449-pstack-worktree-cleanup-treats-untracked-and-ignored-files-a.md"] --- # Playbook Catalog The playbooks inside `/poteto-mode`, one row each. **Count verified: 23.** The README says "twenty-three playbooks", and raw has 23 files under `skills/poteto-mode/playbooks/`. ## Key Points ### How a playbook gets chosen - Playbooks are step lists inside `/poteto-mode`. They are not skills and have no slash command (poteto-help). You describe the task and the mode matches one. - When a playbook matches, poteto-mode opens a todo list whose first items are that playbook's steps, "copied in verbatim". A step it skips stays in the list as `skip: <reason>`. - Files live at `playbooks/<title>.md`, with the title in kebab case. - Some phrases name a playbook directly (poteto-help). "babysit this pr" or "check on pr 123" → Babysit. "land the stack" → Shipping. "take over this branch" → Session pickup. "pause safely" → Pause safely. "full autopilot on this queue" → Autopilot-full. "stack them, don't ship" → Autopilot-stack. "run the eval playbook" → Eval. - Without `/poteto-mode`, a phrase like "babysit this pr" can start Cursor's own built-in babysit skill instead. - **Routing overrides** (poteto-mode SKILL.md): - A large or cross-cutting effort, or work the user steps away from, routes to the `figure-it-out` skill, even when a narrower playbook such as Feature fits. - `figure-it-out` is also the fallback when no bundled playbook fits. - A standing, multi-day program routes to Orchestrate instead. ### Catalog | Playbook (file) | Chosen when | Key steps in a phrase | Wiki page | |---|---|---|---| | Investigation (`investigation.md`) | Read-only question: how does X work, why was Y built this way, "are we sure", X or Y | `how` (+ `why` for motivation) → how-shaped output or tradeoffs table → unslop | [[concepts/understanding-code]] | | Bug fix (`bug-fix.md`) | A reported defect to reproduce, root-cause, fix with runtime evidence | Repro yourself on the same surface → binary-search the cause (`how`/`why`) → delegate the fix → verify on the same surface → failing repro staged before the fix in history (the `tdd` cadence is skipped when a test would be expensive) | [[concepts/build-and-clean]] | | Perf issue (`perf-issue.md`) | A measured slowness to improve against a baseline | Baseline trace vetted with `benchmark-checklist` → `how` → fix from the trace → compare artifacts → cite the measurement in the PR | [[concepts/benchmarks-and-numbers]] | | Hillclimb (`hillclimb.md`) | Sustained improvement of one metric against a target (not a one-off fix) | Build and freeze a sensitive harness → `decision.tsv` log → one hypothesis per iteration → push past plateaus → one commit per accepted win | [[concepts/benchmarks-and-numbers]] | | Runtime forensics (`runtime-forensics.md`) | Live symptom (leak, idle-CPU spin, glitch). The deliverable is a diagnosis, not a fix | Capture live profile/heap/trace → reduce to the smoking gun → prove the mechanism via CDP → map to source | [[concepts/benchmarks-and-numbers]] | | Trace forensics (`trace-forensics.md`) | A captured artifact (cpuprofile, trace, spindump, heap snapshot) handed over after the fact | Load into sqlite → narrow to the hot path or retainer chain → attribute to source → confirm with a paired capture if one exists | [[concepts/benchmarks-and-numbers]] | | Feature (`feature.md`) | New or changed behavior, built from a named data shape | `how` → `architect` → throughput checkpoint (4 todos) → delegate code → verify → small ordered commits → `interrogate` if contested | [[concepts/build-and-clean]] | | Refactoring (`refactoring.md`) | Behavior-preserving change to structure (rename, extract, inline, dedupe, move) | Pin behavior with a characterization test → name the target shape → subtract first → small green steps → prove equivalence → keep it only if reader load drops | [[concepts/build-and-clean]] | | Prototype (`prototype.md`) | A throwaway sketch to make a design decision, or to settle an empirical fork instead of asking the human | Scope the decision → build in a scratch dir → variants behind one switcher → screenshot or observe → recommend, then hand off to Feature | [[concepts/design-before-code]] | | Visual parity (`visual-parity.md`) | Pixel-exact UI equivalence, or migrating a styling system | Baseline harness first → no harness/baseline tampering → one component at a time in worktrees → image diff must be zero | [[concepts/verification-skills]] | | Authoring or modifying a skill (`authoring-a-skill.md`) | Writing or editing a SKILL.md | Cursor's built-in `create-skill` → validate frontmatter and links → tests if structural → Opening a PR | [[concepts/make-it-yours]] | | Eval (`eval.md`) | Testing how a skill, structure or prompt change affects agent behavior | Hidden rubric → sanitized dirs → one organic prompt → N candidates (arena Phase B) → blinded judge → verify from transcripts | [[concepts/make-it-yours]] | | Babysit (`babysit.md`) | Any PR-status request: "babysit this", "get it green", "check on PR X" | Declare a mode (`drive`/`background`/`threads-only`/check) → work the lowest unmerged PR → conflicts, then threads, then CI → status via `scripts/watch-pr/watch-pr` → never merges unasked | [[concepts/shipping-prs-and-watch-pr]] | | Shipping (`shipping.md`) | Asked to land or ship a green stack | Independent per-PR verdict → land only the contiguous verified run from the root → re-check `git patch-id` → merge bottom-up one at a time → stop at the ceiling | [[concepts/shipping-prs-and-watch-pr]] | | Autonomous run (`autonomous-run.md`) | A long task to drive to done without stopping ("run until done", "/loop until X") | Checkable exit predicate → wake mechanism via `/loop` → smallest change per iteration → show-me-your-work checkpoint each iteration → never relax the predicate | [[syntheses/overnight-and-autonomous-runs]] | | Orchestrate (`orchestrate.md`) | A standing project for one coordinator chat: multi-day, many stacked PRs, many subagents | Frame a countable predicate → `orch init` → pilot one unit → scale a rolling window → drain → land continuously → close | [[concepts/orchestration-and-multi-phase-plans]] | | Autopilot-full (`autopilot-full.md`) | A queue of independent PRs run to merged with full autonomy | One owner per PR off trunk → swarm-verify at the code-ready head → owner merges only what was verified → stand down on stop → reply via `ketchup` | [[concepts/orchestration-and-multi-phase-plans]] | | Autopilot-stack (`autopilot-stack.md`) | Build and verify a queue as one linear stack the operator lands ("stack them, don't ship") | Autopilot-full owners minus landing (report STACK-READY) → the root is the only topology writer → deliver the chain, hands off | [[concepts/orchestration-and-multi-phase-plans]] | | Session pickup (`session-pickup.md`) | Resume or take over a prior agent's work (transcript, cloud-agent URL, pushed branch) | Locate the trail in `agent-transcripts/` → reconstruct state → diff done vs pending → route to the matching playbook → verify inherited claims | [[syntheses/overnight-and-autonomous-runs]] | | Pause safely (`pause-safely.md`) | Explicit pause, going offline, Cursor restart, or imminent compaction. Never on "keep going" | Stop at a safe boundary → no irreversible action → `wip:` commit → resume note written off-context | [[syntheses/overnight-and-autonomous-runs]] | | Multi-phase or multi-PR plan (`multi-phase-plan.md`) | Work spanning phases or stacked PRs. The plan is the deliverable; no implementation | Skip it for 1–2 obvious files → settle open questions by prototype → fill the skeleton → `/technical-writing` + `/unslop` → `node pstack/skills/poteto-mode/scripts/check-plan.mjs <plan.md>` → hand back | [[concepts/orchestration-and-multi-phase-plans]] | | Worktree and simulator cleanup (`worktree-cleanup.md`) | Reclaim disk: "clean up worktrees", "free up space", "delete old simulators" | `df -h /` + `scripts/worktree-audit.sh` → cross-check pinned/active chats → pause on `wip:N` → `git worktree remove --force` → `xcrun simctl` cleanup | [[concepts/worktrees]] | | Opening a PR (`opening-a-pr.md`) | Invoked at the end of every other playbook | Worktree off main → small ordered commits → `/deslop` + `/no-comments` → Conventional Commits title → briefing-style body → open ready, never draft | [[concepts/shipping-prs-and-watch-pr]] | ### Notable distinctions stated in the sources - **Hillclimb vs Perf issue.** Perf issue is a one-off fix. Hillclimb is the loop. - **Orchestrate vs Autonomous run.** Autonomous run drives one task to a predicate. If one agent could finish the work inside the session's budget, it routes to Autonomous run, "however program-shaped the phrasing sounds". - **Autopilot-full vs Autopilot-stack.** Use Autopilot-full when PRs are independent and landing authority is granted. Use Autopilot-stack when the operator wants review before landing, the work is coupled, or merge authority is withheld. - **Babysit vs Shipping.** Babysit never merges. Only an explicit merge, land or ship request does, and that request routes to Shipping. ### Hazard flag Worktree cleanup step 5 runs `git worktree remove --force <path>`, then `rm -rf` if the directory survives. Step 4 calls `scratch:N` (untracked files) "safe to drop". Issue #449 (open as of 2026-10-21) reports that this treats untracked and ignored files as disposable. A comment by deanrie says ignored files aren't detected at all, and points to PR #459 as the fix. See [[summaries/known-issues]]. ## Relevant Concepts - [[concepts/poteto-mode]] — how the mode matches and runs playbooks - [[summaries/skill-catalog]] — the skills the playbook steps call - [[summaries/principles-catalog]] — principles the steps cite - [[syntheses/which-skill-when]] — choosing between playbooks and direct skills ## Source Metadata - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-skills-poteto-mode-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - The 23 playbook files `raw/github_doc-pstack-skills-poteto-mode-playbooks-<name>-md.md` — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/<name>.md (authoring-a-skill, autonomous-run, autopilot-full, autopilot-stack, babysit, bug-fix, eval, feature, hillclimb, investigation, multi-phase-plan, opening-a-pr, orchestrate, pause-safely, perf-issue, prototype, refactoring, runtime-forensics, session-pickup, shipping, trace-forensics, visual-parity, worktree-cleanup) - raw/github_issue-pstack-449-pstack-worktree-cleanup-treats-untracked-and-ignored-files-a.md — https://github.com/cursor/plugins/issues/449 - Fetched 2026-10-21. <!-- ===== pstack/wiki/summaries/principles-catalog.md ===== --> --- title: "Principles Catalog" type: summary tags: [pstack, principles, catalog, steering, poteto-mode] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-docs-guide-08-principles-md.md", "raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_doc-pstack-skills-principle-attack-the-premise-skill-md.md", "raw/github_doc-pstack-skills-principle-boundary-discipline-skill-md.md", "raw/github_doc-pstack-skills-principle-build-the-lever-skill-md.md", "raw/github_doc-pstack-skills-principle-encode-lessons-in-structure-skill-md.md", "raw/github_doc-pstack-skills-principle-exhaust-the-design-space-skill-md.md", "raw/github_doc-pstack-skills-principle-experience-first-skill-md.md", "raw/github_doc-pstack-skills-principle-explain-the-number-skill-md.md", "raw/github_doc-pstack-skills-principle-fix-root-causes-skill-md.md", "raw/github_doc-pstack-skills-principle-foundational-thinking-skill-md.md", "raw/github_doc-pstack-skills-principle-guard-the-context-window-skill-md.md", "raw/github_doc-pstack-skills-principle-laziness-protocol-skill-md.md", "raw/github_doc-pstack-skills-principle-make-operations-idempotent-skill-md.md", "raw/github_doc-pstack-skills-principle-migrate-callers-then-delete-legacy-a.md", "raw/github_doc-pstack-skills-principle-minimize-reader-load-skill-md.md", "raw/github_doc-pstack-skills-principle-model-the-domain-skill-md.md", "raw/github_doc-pstack-skills-principle-never-block-on-the-human-skill-md.md", "raw/github_doc-pstack-skills-principle-outcome-oriented-execution-skill-md.md", "raw/github_doc-pstack-skills-principle-prove-it-works-skill-md.md", "raw/github_doc-pstack-skills-principle-redesign-from-first-principles-skill.md", "raw/github_doc-pstack-skills-principle-separate-before-serializing-shared-s.md", "raw/github_doc-pstack-skills-principle-sequence-verifiable-units-skill-md.md", "raw/github_doc-pstack-skills-principle-subtract-before-you-add-skill-md.md", "raw/github_doc-pstack-skills-principle-test-behavior-not-implementation-ski.md", "raw/github_doc-pstack-skills-principle-type-system-discipline-skill-md.md", "raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md"] --- # Principles Catalog pstack ships 24 principles. Each is a short skill named `principle-<name>` that holds one rule. `/poteto-mode` keeps an inline index of them, grouped Core / Architecture / Verification / Delegation / Meta. It names each principle it applied in its reply, along with the decision that principle changed. ## Key Points ### Catalog (rule text abridged from the README table, cross-checked against each SKILL.md `description`) | # | Principle (skill name) | Group | Rule | |---|---|---|---| | 1 | laziness-protocol | core | Bias toward deletion and the smallest change that solves the problem. | | 2 | foundational-thinking | core | Before writing logic, choose core types and data structures; get them right so downstream code becomes obvious. | | 3 | redesign-from-first-principles | core | Redesign as if the new requirement had been a foundational assumption from day one, instead of bolting it on. | | 4 | attack-the-premise | core | When 2+ fixes sharing one premise failed the same gate, write the premise down and test it directly before another fix. | | 5 | subtract-before-you-add | core | Remove dead weight, redundant validators, and stub references first, then build on the simpler base. | | 6 | minimize-reader-load | core | Count layers and hidden state; collapse one-caller wrappers and shrink mutable scope. | | 7 | outcome-oriented-execution | core | In phased rewrites/migrations, converge on the target architecture; no throwaway compatibility code. | | 8 | experience-first | core | User delight over implementation convenience; fewer polished features over more rough ones. | | 9 | exhaust-the-design-space | core | Build 2-3 competing prototypes and compare side by side before committing. | | 10 | build-the-lever | core | For any non-trivial work, build the tool (codemod, script, generator, or skill) that does or proves it; the reviewer reruns it. | | 11 | model-the-domain | architecture | Encode the domain in a structure instead of scattered conditionals. | | 12 | boundary-discipline | architecture | Guards at system boundaries (CLI, config, network, external APIs); trust internal types; pure business logic. | | 13 | type-system-discipline | architecture | Make illegal states unrepresentable, brand primitives, parse at boundaries, exhaust variants, derive from authoritative schemas. | | 14 | make-operations-idempotent | architecture | Converge to the same end state regardless of partial prior runs. | | 15 | migrate-callers-then-delete-legacy-apis | architecture | Migrate callers and delete the old API in the same wave; no compatibility layers. | | 16 | separate-before-serializing-shared-state | architecture | Eliminate the sharing first; serialize only when one shared writer is a real invariant. | | 17 | prove-it-works | verification | Before declaring done, verify the real artifact, not a proxy, self-report, or "it compiles". | | 18 | fix-root-causes | verification | Trace each symptom to the first place the system went wrong; a guard is a fix only when the state it handles is legitimate. | | 19 | sequence-verifiable-units | verification | Small units that each end in a verifiable state, checked before the next, ordered so the sequence proves itself. | | 20 | test-behavior-not-implementation | verification | Assert what the code's users can observe, so tests break on behavior changes and survive internal ones. | | 21 | explain-the-number | verification | Before trusting or reporting a measured number, find what limits it and rule out that it measured something else. | | 22 | guard-the-context-window | delegation | Route bulk to subagents; keep summaries, not raw payloads, in the main thread. | | 23 | never-block-on-the-human | delegation | Proceed, present, let the human course-correct; confirm only irreversible actions. | | 24 | encode-lessons-in-structure | meta | Encode a repeated rule as a lint, metadata flag, runtime check, or script instead of more text. | Group counts: core 10, architecture 6, verification 5, delegation 2, meta 1. ### Cross-check notes (README vs SKILL.md vs guide 08) - All 24 README rows match a `principle-*` directory, and the SKILL.md `name` values match the folder names. - Wording differs in small ways: - `subtract-before-you-add`: the README says "Remove dead weight", the SKILL.md description says "Remove dead code". - `encode-lessons-in-structure`: the SKILL.md trigger adds "or notice a recurring correction". - For `model-the-domain`, `never-block-on-the-human` and `redesign-from-first-principles`, the SKILL.md `description` gives only the trigger ("Apply when…"). The rule itself is in the skill body and the poteto-mode index. - Guide 08 uses display titles that differ from the slugs. For example, "Sequence Work into Verifiable Units" is the skill `principle-sequence-verifiable-units`. ### Steering with principle names (guide 08) - You don't invoke principles. You **use their names to steer**. Per guide 08, each name points at a complete rule the agent has already read (but see the known gap below), so one phrase redirects work more precisely than a paragraph. - Example steers, verbatim from guide 08: - `use subtract before you add. delete the obsolete adapters first, then design what's left.` - `apply prove it works. run the real import flow and show me the written records.` - `separate before serializing shared state. give each attempt its own worktree, no locks.` - The agent must say which decision the rule changed. Per guide 08, "A principle citation with no decision behind it means the agent named the rule without applying it." - Typing `/principle-<name>` still loads one on demand (poteto-help). - Advice from guide 08: don't memorize the list. Come back when the agent does something a name would have prevented. - Related skills: `/benchmark-checklist` turns explain-the-number into seven questions, and `/correct` applies encode-lessons-in-structure to a whole repo. ### Known gap: cited-but-unread principles All 24 principle skills set `disable-model-invocation: true`, so the only way to load one is to `Read` it by path. poteto-mode says "Cite only principles whose leaf SKILL.md you read this session." Issue #726 (open as of 2026-10-21) reports an audit of 18 Claude Code runs: a principle file was read in 0 of them. A commenter's experiment found that a "chain" variant (each playbook opens with an unconditional list of principles to read, and the skill body cut to one line) raised reads to 68/72 runs, against 0/72 at baseline. That was a single-model test (Sonnet via omp), not Claude Code, and the commenter notes reads are not reply quality. See [[summaries/known-issues]]. ## Relevant Concepts - [[concepts/poteto-mode]] — where the inline index lives - [[concepts/prompting-pstack]] — steering prompts in general - [[summaries/playbook-catalog]] — playbooks that name principles in their steps - [[concepts/benchmarks-and-numbers]] — explain-the-number in practice ## Source Metadata - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-docs-guide-08-principles-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/08-principles.md - raw/github_doc-pstack-skills-poteto-mode-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - The 24 principle files `raw/github_doc-pstack-skills-principle-*` — https://github.com/cursor/plugins/blob/main/pstack/skills/principle-<name>/SKILL.md - raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md — https://github.com/cursor/plugins/issues/726 - Fetched 2026-10-21. <!-- ===== pstack/wiki/summaries/release-history.md ===== --> --- title: "Release History" type: summary tags: [pstack, releases, versions, changelog, commits] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_commits-pstack-log.md", "raw/github_doc-pstack-plugin-json.md", "raw/github_doc-pstack-cursor-plugin-plugin-json.md"] --- # Release History A digest of the pstack commit log. **Scope: only the last 100 commits that touched `pstack/` in `cursor/plugins`, fetched 2026-10-21.** These run from 2026-07-12 (`e42d29f`) to 2026-10-20 (`88d4751`). Anything older is not in the corpus. pstack has no CHANGELOG file in raw. ## Key Points ### Current version Both manifests, `pstack/plugin.json` and `pstack/.cursor-plugin/plugin.json`, state `"version": "0.15.29"`. No commit subject in the 100 says "0.15.29", so the bump commit is not identifiable from the log. Manifest metadata: author "Lauren Tan", license MIT, homepage `https://github.com/cursor/plugins/tree/main/pstack`. ### Versions named literally in commit subjects | Version | Commit | Date | Subject (abridged) | |---|---|---|---| | 0.11.1 | 20bdb6c | 2026-07-12 | bump version to 0.11.1 (#152) | | 0.11.2 | a29f5a8 | 2026-07-12 | bump version to 0.11.2 (#154) | | 0.12.0 | 0b7ef5b | 2026-07-30 | docs: refresh guide for 0.12.0 | | 0.13.0 | b047069 | 2026-08-02 | add autopilot playbooks, /no-comments, Comment Sicko, /technical-writing (#185) | | 0.14.0 | 99559f2 | 2026-08-02 | add bro, babysit/shipping/orchestrate/worktree-cleanup, catch-up ports (#187) | | 0.15.0 | 71ed0d1 | 2026-09-08 | bump to 0.15.0 and sync README/docs counts (#333) | | 0.15.6 | 23e4138 | 2026-10-03 | port explain-the-number, fresh subagents, hourly autopilot tick, PR headings, schema-first cast | | 0.15.20 | 1b6d44f | 2026-10-12 | bump (#581) | | 0.15.21 | 997ffc7 | 2026-10-12 | bump (#584) | | 0.15.22 | 3177dab | 2026-10-13 | bump (#605) | | 0.15.24 | 1e5c90a | 2026-10-14 | bump (#617) | | 0.15.25 | 6ce45c5 | 2026-10-14 | bump (#614) | | 0.15.26 | 0b8e952 | 2026-10-18 | bump (#710) | | 0.15.27 | 0148b78 | 2026-10-18 | bump (#713) | | 0.15.28 | d457567 | 2026-10-19 | bump, sync guide with create-formal-verification-skill (#724) | The numbering has gaps: nothing between 0.15.0 and 0.15.6, nothing between 0.15.6 and 0.15.20, no 0.15.23, and no 0.15.29. Analysis: those bumps probably happened in commits whose subjects don't name the version. So this table is not a complete release list. ### Major additions by date - **2026-07-12**: `create-verification-skill` and `maintain-verification-skill` (#150); `teach` (#153). - **2026-07-22**: public usage tutorial (#164); `inherit-parent` / `auto` model support (#163). - **2026-07-30**: `swarm` skill (b79f8ca). - **2026-08-02**: autopilot playbooks, `/no-comments`, Comment Sicko, `/technical-writing` (0.13.0); `bro` plus the babysit, shipping, orchestrate and worktree-cleanup playbooks (0.14.0). - **2026-08-27**: `make-bot-ui` (#271, #275). - **2026-09-02/03**: plugin logo (#303, #309). - **2026-09-07**: two new principle leaves (#329). - **2026-10-03**: `/correct` (#494); explain-the-number principle port (0.15.6). - **2026-10-05**: `/poteto-help` (#502), made typed-only (#506), prompting references (#507). - **2026-10-10**: `/ketchup` (#539). - **2026-10-12**: Agent Plugins v1 root manifest (#576). - **2026-10-13**: `/in-your-own-words` (#602). - **2026-10-14**: `/sharpen` (#615). - **2026-10-16**: Claude Code install from a generated tree (#637). - **2026-10-18**: `/create-formal-verification-skill` (#709). - **2026-10-19**: `/maintain-formal-verification-skill` (#716). ### Notable removals, defaults and fixes - **Model defaults moved often:** - Panels defaulted to Fable, Sol and Grok (#165, 2026-07-22). Opus 5 joined the panels (#169). - The Grok default went from 4.5 to 4.6 (#210, 2026-08-13). - Defaults moved to Opus 5.5 and Grok 4.7 (#414, 2026-09-23). - "drop Sol, default to Opus xhigh and Grok" (#511, 2026-10-06). - **Invocation.** "disable model invocation for five skills" (#300, 2026-09-01); unslop's "Must always apply." dropped from its description (#572). - **Removals and cuts:** - Graphite dropped from orchestrate (#613). - "cut 19 more instructions Opus 5.5 does not need" (#419). - Token-distilling and section-cutting passes (#538, #571, #634). - The rewritten-prompt ban dropped from sharpen (#712). Sharpen was then restored to the original prompt, returning only the rewrite (#729). - **Issue-linked fixes** (the link to an issue is stated in the issue thread for #483/#486 and #471/#484; for the others it is this page's inference from matching titles): - Comment Sicko agent id renamed so Grok can spawn it (#486). - The `/poteto-mode` chat is the runner and poteto-agent a delegate (#575). - Agents told where bundled leaf skills live (#577). - worktree-audit checks MERGED against the default branch (#574). - watch-pr paginates review threads past the first 100 (#484). - "name every skill after its folder" (#702, 2026-10-17). - "close three gaps in the Claude Code plugin" (#705). - A docs-vs-tree check (#704). ### Cadence (from the 100 commits) | Month (2026) | Commits | |---|---| | July (from 07-12) | 21 | | August | 8 | | September | 15 | | October (to 10-20) | 56 | Analysis: activity sped up sharply in October. Several version bumps landed within a day of each other (0.15.20 and 0.15.21 on 10-12; 0.15.24 and 0.15.25 on 10-14; 0.15.26 and 0.15.27 on 10-18). That pattern points to a release-per-merged-feature habit rather than scheduled releases. It is an inference from commit subjects, not a stated policy. ## Relevant Concepts - [[entities/pstack]] — the plugin itself - [[summaries/known-issues]] — issues whose fixes appear above - [[summaries/skill-catalog]] — the skills as they stand at 0.15.29 - [[concepts/formal-verification]] — the newest skills (2026-10-18/19) ## Source Metadata - raw/github_commits-pstack-log.md — https://github.com/cursor/plugins/commits/main/pstack (last 100 commits touching pstack/, fetched 2026-10-21) - raw/github_doc-pstack-plugin-json.md — https://github.com/cursor/plugins/blob/main/pstack/plugin.json - raw/github_doc-pstack-cursor-plugin-plugin-json.md — https://github.com/cursor/plugins/blob/main/pstack/.cursor-plugin/plugin.json <!-- ===== pstack/wiki/summaries/skill-catalog.md ===== --> --- title: "Skill Catalog" type: summary tags: [pstack, skills, catalog, slash-commands, disable-model-invocation] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-skills-architect-skill-md.md", "raw/github_doc-pstack-skills-arena-skill-md.md", "raw/github_doc-pstack-skills-automate-me-skill-md.md", "raw/github_doc-pstack-skills-benchmark-checklist-skill-md.md", "raw/github_doc-pstack-skills-blast-radius-skill-md.md", "raw/github_doc-pstack-skills-bro-skill-md.md", "raw/github_doc-pstack-skills-correct-skill-md.md", "raw/github_doc-pstack-skills-create-formal-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-create-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-figure-it-out-skill-md.md", "raw/github_doc-pstack-skills-how-skill-md.md", "raw/github_doc-pstack-skills-in-your-own-words-skill-md.md", "raw/github_doc-pstack-skills-interrogate-skill-md.md", "raw/github_doc-pstack-skills-ketchup-skill-md.md", "raw/github_doc-pstack-skills-maintain-formal-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-maintain-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-make-bot-ui-skill-md.md", "raw/github_doc-pstack-skills-no-comments-skill-md.md", "raw/github_doc-pstack-skills-recall-skill-md.md", "raw/github_doc-pstack-skills-reflect-skill-md.md", "raw/github_doc-pstack-skills-setup-pstack-skill-md.md", "raw/github_doc-pstack-skills-sharpen-skill-md.md", "raw/github_doc-pstack-skills-show-me-your-work-skill-md.md", "raw/github_doc-pstack-skills-swarm-skill-md.md", "raw/github_doc-pstack-skills-tdd-skill-md.md", "raw/github_doc-pstack-skills-teach-skill-md.md", "raw/github_doc-pstack-skills-technical-writing-skill-md.md", "raw/github_doc-pstack-skills-typescript-best-practices-skill-md.md", "raw/github_doc-pstack-skills-unslop-skill-md.md", "raw/github_doc-pstack-skills-why-skill-md.md", "raw/github_issue-pstack-367-pstack-disable-model-invocation-skills-still-have-use-only-w.md", "raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md", "raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-full-md.md"] --- # Skill Catalog Every non-principle skill under `pstack/skills/` (32 directories as fetched 2026-10-21), one row each. The 24 `principle-*` skills are in [[summaries/principles-catalog]]; the 23 poteto-mode playbooks are in [[summaries/playbook-catalog]]. ## Key Points ### How invocation works (read this first) - **31 of the 32 skills set `disable-model-invocation: true`** in their SKILL.md frontmatter. Only `setup-pstack` omits it. The poteto-help skill states the consequence: "Only `/setup-pstack` loads from the user's words. The others load when the user types them or when `/poteto-mode` runs them." - A reply by deanrie on issue #367 says the same: once a skill has the flag, "it only runs on its slash command". - `/poteto-mode` runs the others by reading their files. Its SKILL.md states "Bundled skills live at `../<name>/SKILL.md` from this file". The README says `/poteto-mode` "runs most of these for you" and names: `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `unslop`, `no-comments`, `technical-writing`, `tdd`, and the principles. Its Non-negotiables also trigger `benchmark-checklist` and `show-me-your-work`, and its Playbooks section routes large or cross-cutting work to `figure-it-out`. - Issue #527 (closed 2026-10-12) reported that the flag hid routed skills from the hub. It also noted that in Cursor, plugin-delivered skills with the flag can be missing from the `/` palette. - On Codex the flag has no effect. Per a measurement comment by ImSynem on issue #734 (open as of 2026-10-21; Codex CLI 0.163.0), Codex's skill parser never reads `disable-model-invocation`, so all flagged skills appear in its automatic skill list. - In Claude Code every command takes a `pstack:` prefix, for example `/pstack:poteto-mode` (README). ### Catalog "Typed only" = frontmatter has `disable-model-invocation: true`. "README says typed-only" = the README table literally says "runs only when you type …". "Routed" = the README or poteto-mode SKILL.md names it as something `/poteto-mode` runs for you. | Slash command | Purpose (one line) | Typed only (frontmatter) | README says typed-only | Routed by /poteto-mode | Wiki page | |---|---|---|---|---|---| | `/poteto-mode` | Default entry point. Matches the task to a playbook and runs other skills as steps need them | yes | no | n/a (hub) | [[concepts/poteto-mode]] | | `/poteto-help` | Answers "which skill/playbook/principle fits?" and hands back a prompt to type. Doesn't start the work | yes | yes | no | [[concepts/prompting-pstack]] | | `/in-your-own-words` | Agent restates your goal and the problem before work starts | yes | yes | no | [[concepts/prompting-pstack]] | | `/sharpen` | Rewrites a prompt "deeper, not bigger" and returns only the rewrite. Doesn't do the task | yes | yes | no | [[concepts/prompting-pstack]] | | `/how` | Walkthrough of how a subsystem works, plus "where should this live" questions | yes | no | yes | [[concepts/understanding-code]] | | `/why` | Why code was built this way. Queries available MCPs per evidence category in parallel | yes | no | yes | [[concepts/understanding-code]] | | `/teach` | Runs `how` + `why` and weaves one plain explanation, diagram by diagram | yes | no | no | [[concepts/understanding-code]] | | `/recall` | Rebuilds your recent context on a topic from chat history and the shared record | yes | no | no | [[concepts/understanding-code]] | | `/ketchup` | What changed in this chat since your last message, with every waiting item listed | yes | no | autopilot replies use it | [[syntheses/overnight-and-autonomous-runs]] | | `/blast-radius` | What a small change could break outside the diff, with the key safety fact proven by running code | yes | no | no | [[concepts/code-review-with-interrogate]] | | `/architect` | Settles types, signatures and module shape before code that crosses a function boundary | yes | no | yes | [[concepts/design-before-code]] | | `/arena` | N parallel attempts at one brief. Pick a base, graft the best parts | yes | no | yes | [[concepts/design-before-code]] | | `/swarm` | N parallel workers over slices or races, one aggregated report | yes | no | yes | [[concepts/orchestration-and-multi-phase-plans]] | | `/interrogate` | Different models adversarially review a diff, including a code-quality lens | yes | no | yes | [[concepts/code-review-with-interrogate]] | | `/automate-me` | Drafts your own `<your-name>-mode` skill from how you've worked | yes | no | no | [[concepts/make-it-yours]] | | `/make-bot-ui` | Builds a page or dashboard whose buttons wake a Grok Bot over a webhook | yes | no | no | [[entities/pstack]] | | `/setup-pstack` | Picks models per role and a reasoning budget, writes a config rule | **no** (flag absent) | no | no | [[concepts/installation-and-model-setup]] | | `/reflect` | Three parallel reviewers mine the transcript; learnings become skill edits you approve | yes | no | no | [[concepts/make-it-yours]] | | `/correct` | Mines repeated agent mistakes and makes each impossible (architecture, types, lint, test, docs last) | yes | no | no | [[concepts/make-it-yours]] | | `/tdd` | Failing test first, then the fix, when a cheap local test path exists | yes | no | yes | [[concepts/build-and-clean]] | | `/benchmark-checklist` | Vets a measured speedup or regression before you report or act on it | yes | no | yes | [[concepts/benchmarks-and-numbers]] | | `/no-comments` | Spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints | yes | no | yes | [[concepts/build-and-clean]] | | `/typescript-best-practices` | TypeScript rules for `.ts`/`.tsx` work (frontmatter `paths: ["**/*.ts", "**/*.tsx"]`) | yes | no | no | [[concepts/build-and-clean]] | | `/figure-it-out` | Designs an auditable playbook when no bundled one fits | yes | no | yes | [[concepts/orchestration-and-multi-phase-plans]] | | `/show-me-your-work` | Decision trail as a TSV log, one row per decision | yes | no | yes | [[concepts/decision-logs]] | | `/create-verification-skill` | Generates a project-local `verify-<app>` skill with a feature map | yes | no | no | [[concepts/verification-skills]] | | `/maintain-verification-skill` | Re-syncs the verify skill's feature map; at most one PR of proven corrections | yes | no | no | [[concepts/verification-skills]] | | `/create-formal-verification-skill` | Verifies one property tests can't reach with a fitting tool and leaves a recheck skill | yes | no | no | [[concepts/formal-verification]] | | `/maintain-formal-verification-skill` | Updates model/harness/properties after code changes; says drift vs bug per failure | yes | no | no | [[concepts/formal-verification]] | | `/unslop` | Cuts AI tells from any writing | yes | no | yes | [[concepts/technical-writing-and-unslop]] | | `/bro` | Restates the last message in plain language, no jargon | yes | no | no | [[concepts/technical-writing-and-unslop]] | | `/technical-writing` | Layered doc standard (Diátaxis, Google developer style, STE, Global English) | yes | no | yes | [[concepts/technical-writing-and-unslop]] | ### README vs skills/ cross-check - **Counts match.** The README "all skills" table lists 32 skills, and raw has 32 non-principle skill directories with matching names. No skill is missing from either side. - **"Runs only when you type it" wording is incomplete.** The README says this only for `/poteto-help`, `/in-your-own-words` and `/sharpen`. But the frontmatter puts the same flag on 31 skills. The README wording understates how many skills are typed-only. - **Leftover routing-style descriptions.** `tdd` ("Use only when the user explicitly asks…"), `make-bot-ui` ("Use when building…"), `reflect` ("Use when the user says reflect.") and `typescript-best-practices` ("Use when reading or editing any .ts or .tsx file.") still read as model-routing rules despite the flag. Issue #367 (open as of 2026-10-21) tracks this. - **Skills poteto-mode references but pstack does not ship:** `/deslop`, `control-cli` and `control-ui` (in `cursor-team-kit`). `/create-skill` and `/loop` are Cursor built-ins. There is no `/orchestrate` skill; Orchestrate is a playbook. ## Relevant Concepts - [[concepts/poteto-mode]] — the hub that routes to these skills - [[syntheses/which-skill-when]] — decision map and close calls - [[summaries/known-issues]] — invocation-related issues (#367, #527, #734) - [[concepts/installation-and-model-setup]] — `/setup-pstack`, the one model-invocable skill ## Source Metadata - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - raw/github_doc-pstack-skills-poteto-mode-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md - Each skill's SKILL.md (frontmatter checked for `disable-model-invocation`): https://github.com/cursor/plugins/blob/main/pstack/skills/<name>/SKILL.md for architect, arena, automate-me, benchmark-checklist, blast-radius, bro, correct, create-formal-verification-skill, create-verification-skill, figure-it-out, how, in-your-own-words, interrogate, ketchup, maintain-formal-verification-skill, maintain-verification-skill, make-bot-ui, no-comments, recall, reflect, setup-pstack, sharpen, show-me-your-work, swarm, tdd, teach, technical-writing, typescript-best-practices, unslop, why (raw files `raw/github_doc-pstack-skills-<name>-skill-md.md`) - raw/github_issue-pstack-367-pstack-disable-model-invocation-skills-still-have-use-only-w.md — https://github.com/cursor/plugins/issues/367 - raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md — https://github.com/cursor/plugins/issues/527 - raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md — https://github.com/cursor/plugins/issues/734 - raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-full-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/autopilot-full.md (reply "per the **ketchup** skill") - Fetched 2026-10-21. <!-- ===== pstack/wiki/syntheses/getting-started.md ===== --> --- title: "Getting Started with pstack" type: synthesis tags: [pstack, getting-started, setup, poteto-mode, first-task] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-docs-guide-readme-md.md", "raw/github_doc-pstack-docs-guide-01-setup-md.md", "raw/github_doc-pstack-docs-guide-02-poteto-mode-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md"] --- # Getting Started with pstack The README's "get started" is two steps: run `/setup-pstack` and pick a reasoning budget and models, then use `/poteto-mode` whenever you're doing anything that requires rigor. This page walks the first real task end to end, following guide pages 01 and 02. ## Comparison The first-task path, step by step: | Step | What you type | What happens | Watch for | |---|---|---|---| | 1. Install | `/add-plugin pstack` (Cursor chat). Claude Code: `/plugin marketplace add cursor/plugins` then `/plugin install pstack@cursor-plugins` | Cursor confirms the plugin is installed | Installing changes nothing until you invoke a skill | | 2. Pick models | `/setup-pstack` | Detects your models, asks for a reasoning budget, shows each role, asks what you want, writes `~/.cursor/rules/pstack-models.mdc` | The rule applies to **new** sessions only | | 3. Verification offers | Answer yes/no | Offers once to run `/create-verification-skill`, then once to run `/create-formal-verification-skill`, unless the project already has one | Guide recommends "yes" to the verification skill if you're new | | 4. New chat | — | Model rule takes effect | Old chat still uses old choices | | 5. First task | `/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.` | Matches a playbook (Feature, for this prompt) and opens a todo list | Skipped steps stay listed as `skip: <reason>` | | 6. Follow up | `continue`, `keep going until done`, `/poteto-mode do it` | Playbook keeps the structure | Say "new task" when you change subject | | Stuck | `/poteto-help <question>` | Answers, hands you a prompt to send, links the source file | It doesn't start the work | ## Analysis **Setup is "one command plus a short conversation"** (guide 01). `/setup-pstack` asks for one of four budgets (`unlimited`, `large`, `medium`, `small`); the defaults run at `xhigh` reasoning, the same as `large`. You only override roles you care about; a role with no line keeps the skill default. Details are on [[concepts/installation-and-model-setup]]. **Why say yes to the verification skill.** Guide 01 calls it the thing that "pays off the most": an agent that can check its own work keeps going until the check passes, while one that can't hands every result back to you. Saying yes writes `.cursor/skills/verify-<app>/`, a project-local skill that drives your app the way a user does, proven once before handover. The formal verification offer is worth a yes when the code has concurrency, retries, a state machine, or a parser; otherwise say no and run it later. See [[concepts/verification-skills]] and [[concepts/formal-verification]]. **The first prompt: goal plus check.** The guide's "one thing to remember" is to give the agent a goal and a way to check it, in your own words. You don't name a playbook or list skills. In `/poteto-mode the export writes duplicate rows when a retry lands mid-run. repro first, then fix and verify.`, "repro first" plus a checkable outcome is all the routing signal needed; it matches Bug fix. Pick something real but small, described as you would to a colleague. More on wording in [[concepts/prompting-pstack]]. **What you'll see.** `/poteto-mode` reads its Principles section, matches the task (Investigation, Bug fix, Feature, Refactoring, Perf issue, or `figure-it-out` for large or unmatched work), and copies the matched playbook's steps into the todo list verbatim, before any task-specific todos. A step it chooses not to do stays visible with `skip: <reason>`. Replies name the principles that shaped decisions and carry evidence or a measured/inferred/guess label. The [[concepts/poteto-mode]] page covers the mechanics. **Keeping the mode on.** In Cursor, pick `/poteto-mode` from the `/` menu before typing so Cursor attaches it. Plain Enter attaches it to one message and it fades as the chat moves on. Option+Enter (Mac) or Alt+Enter (Windows) makes it a Custom Mode that stays in context every turn until you exit; Custom Modes are available in the Agents Window and the CLI. **Cost.** pstack spends extra tokens on subagents and review panels. To spend less: rerun `/setup-pstack` with a smaller budget or cheaper models, set a role to `auto` or `inherit-parent`, shorten a panel list, and save `/poteto-mode` for work that needs rigor. ## Recommendations - Read the guide pages in order the first time; afterwards each stands alone (guide README). - After `/setup-pstack`, **start a new chat** before your first task. `/poteto-help`'s troubleshooting table lists "a new model choice had no effect" as this exact mistake. - If the mode stops applying after a few turns, you started it with Enter; restart as a Custom Mode or prefix each task with `/poteto-mode`. - Don't enumerate skills in the prompt ("use /how, then /architect…"). The guide calls this a pitfall: a hand-written order tends to drop or reorder playbook steps. - When unsure, `/poteto-help which skill should i use to review this branch?` style questions return a ready-to-send prompt. It runs only when you type it. - Running several agents on one machine? Give each its own worktree or a cloud subagent ([[concepts/worktrees]]). - Next steps: [[concepts/understanding-code]], then [[syntheses/which-skill-when]]. ## Pages Compared - [[concepts/installation-and-model-setup]] - [[concepts/poteto-mode]] - [[concepts/prompting-pstack]] - [[concepts/verification-skills]] - [[syntheses/overview]] - [[syntheses/pstack-on-claude-code]] ## Sources - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-docs-guide-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/README.md - raw/github_doc-pstack-docs-guide-01-setup-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/01-setup.md - raw/github_doc-pstack-docs-guide-02-poteto-mode-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/02-poteto-mode.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md <!-- ===== pstack/wiki/syntheses/overnight-and-autonomous-runs.md ===== --> --- title: "Overnight and Autonomous Runs: Which Playbook When" type: synthesis tags: [overnight, autonomous-run, autopilot-full, autopilot-stack, orchestrate, pause-safely, session-pickup, babysit, loop] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-docs-guide-07-overnight-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autonomous-run-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-full-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-stack-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-pause-safely-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-session-pickup-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-babysit-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md", "raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md"] --- # Overnight and Autonomous Runs Guide 07 ("Run work while you sleep") says leaving an agent alone is safe only with "a checkable finish condition, an isolated worktree or cloud agent, and a decision log you audit in the morning." This page compares the `/poteto-mode` playbooks that make that work. ## Comparison | Playbook | Unit of work | Who merges | Wake / cadence | Ends when | Example prompt (guide 07; Babysit: guide 06) | |---|---|---|---|---|---| | **Autonomous run** | one task, one predicate | the agent commits each iteration that advanced the predicate; no separate merge rule (a predicate can itself be "all N PRs merged") | Cursor `/loop`: event watcher subagent plus long heartbeat, or a fixed-interval heartbeat | predicate met, or a real dead end surfaced | `/poteto-mode im going to bed. migrate every caller ...` + `/loop until done.` | | **Autopilot-full** | queue of *independent* PRs, one owner each, parallel off trunk | each owner merges, only on the root swarm's clean verdict | root arms `/loop 1h` audit on the operator's go | queue merged; operator-named items stop at merge-ready | `/poteto-mode full autopilot on this queue. each item is independent. i want them merged by morning.` | | **Autopilot-stack** | same owner loop, one linear base-chained stack | nobody; the operator lands it | as Autopilot-full | every link reports STACK-READY with a verdict | `/poteto-mode autopilot these five changes but stack them, don't ship. i'll land the stack in the morning.` | | **Orchestrate** | multi-day program, many stacks, coordinator + tracks + cloud workers | stacker / coordinator lands verified units | drain points + frontier watcher via loop | countable done predicate confirmed | `/poteto-mode orchestrate the store migration. own it until every package is converted and merged. i'll check in twice a day.` | | **Babysit** | one PR or stack's merge frontier | never merges | `drive`/`background` under `/loop` in dynamic mode, driven by `watch-pr` output | merge-ready | `/poteto-mode babysit this pr. get it green.` | | **Pause safely** | a clean stop | - | explicit only | `wip:` commit + resume note written | "pause", "about to go offline", "restart Cursor" | | **Session pickup** | resuming a prior run | - | - | routed to the matching playbook | (fresh chat, from the resume note or transcript) | ## Analysis ### The overnight contract Guide 07's template has four parts: goal, finish condition, permissions, escape hatch. ```text /poteto-mode im going to bed. migrate every caller to the new parser in a fresh worktree off <base>. done means zero old callers, all parser fixtures pass, old api deleted. keep a decision log. don't ask me before committing. /loop until done. if you're truly stuck after a few hours, stop and write up why. ``` "im going to bed" is a session override (stop asking, keep going); "done means..." gives every iteration a check; the fresh worktree prevents collisions ([[concepts/worktrees]]); "don't ask me before committing" pre-answers the blocking permission; `/loop` is Cursor's built-in wake mechanism, **not a pstack skill**; the escape hatch beats "eight hours of creative goal reinterpretation". Because the work is reviewed later, `/poteto-mode` routes it through `/figure-it-out`. The loop: check the predicate, make the smallest justified change, verify on the real artifact, commit or discard, log one row ([[concepts/decision-logs]]). A plateau means pivot, not stop, and the predicate never relaxes. **A duration is not a finish condition**: "work on this for 4 hours" gives the agent nothing to check. ### Earn trust before the loop Make a loop autonomous only after all four hold: you've done or watched the task once; the agent has your tools and signals (verification skill, profiler, logs; see [[concepts/verification-skills]]); every stage proves its work and can stop the line; you've read transcripts and turned repeat failures into tools, skills or checks. Until then, run it while you watch. ### How the autopilots keep trust at scale Autopilot-full: one Cursor cloud owner per PR builds, opens, babysits and merges; a swarm that never wrote the code verifies the code-ready head once (later rebases or minor fixes get a single verifier); green CI alone never authorizes a merge; owners push early and keep a trail because "Assume the VM dies"; the root countersigns anything that loosens a gate and never bypasses a forge-enforced approval; a stop becomes a zero-writes order to every owner. Autopilot-stack keeps all of that but gives the chain's topology one writer (the root) and leaves landing to the operator. Detail on landing rules: [[concepts/shipping-prs-and-watch-pr]]; on Orchestrate: [[concepts/orchestration-and-multi-phase-plans]]. ### Stopping and resuming Pause safely is **explicit only**: "keep going", "going to bed, keep going" or "don't stop" never pause. It finishes or backs out of the current atomic step, takes no irreversible action (no PR and no push unless one was already out), commits one `wip:` commit, and writes a resume note (e.g. `/tmp/<slug>-resume.md`). Session pickup reads that trail (a local transcript only under the active workspace's `agent-transcripts/`; a cloud-agent URL or pushed branch also counts), treats it as authoritative, names the resume point without redoing work, routes to the matching playbook, then verifies inherited claims on the real artifact. ### Projects and automations A Cursor Project gives one coordinator a persistent thread; subagents run in the cloud by default, so work continues with the laptop closed. Guide 07's habits: one Project per body of work, drag related chats in as context, a verification swarm per PR, and plans backed by data with prototypes answering open questions. For loops that start themselves, pstack ships the dormant Benny automation pack for Slack issue reports ([[entities/benny-automation]]); its two rules are that every stage can stop the line and every stage hands over evidence. ## Recommendations Analysis (the wiki's guidance, derived from the playbooks above): - **One task with a pass/fail predicate** → Autonomous run with the overnight contract. If you can't state the predicate, don't start the loop. - **Several independent changes and you grant merge authority** → Autopilot-full. - **Changes are coupled or sequenced, or you want to review before anything lands, or merge authority is withheld** → Autopilot-stack (the playbook's own rule). - **Multi-day work that outlives one agent's session budget** → Orchestrate, ideally in a Cursor Project. If one agent could finish it, Orchestrate itself sends you back to Autonomous run. - **PRs already open and you only need them green** → Babysit (`drive`), then Shipping on an explicit "land it". - **Going offline mid-run** → say "pause"; resume in a fresh chat via Session pickup. Saying "going to bed" alone means *keep going*. - **Morning** → `/show-me-your-work catch me up on what you did last night` for an audit (read the Attention section first), or `/ketchup` for a quick read-only status. ## Pages Compared - [[concepts/decision-logs]] - [[concepts/orchestration-and-multi-phase-plans]] - [[concepts/shipping-prs-and-watch-pr]] - [[concepts/worktrees]] - [[concepts/verification-skills]] - [[entities/benny-automation]] - [[syntheses/which-skill-when]] ## Sources - raw/github_doc-pstack-docs-guide-07-overnight-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/07-overnight.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-autonomous-run-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/autonomous-run.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-full-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/autopilot-full.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-autopilot-stack-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/autopilot-stack.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-pause-safely-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/pause-safely.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-session-pickup-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/session-pickup.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-babysit-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/babysit.md) - raw/github_doc-pstack-skills-poteto-mode-playbooks-orchestrate-md.md (https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/orchestrate.md) - raw/github_doc-pstack-docs-guide-06-verify-and-ship-md.md (https://github.com/cursor/plugins/blob/main/pstack/docs/guide/06-verify-and-ship.md) — Babysit example prompt <!-- ===== pstack/wiki/syntheses/overview.md ===== --> --- title: "pstack Overview" type: synthesis tags: [pstack, overview, cursor, plugin, philosophy, poteto-mode] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-docs-guide-readme-md.md", "raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_doc-pstack-plugin-json.md", "raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md"] --- # pstack Overview pstack is a Cursor plugin of agent-engineering skills whose README is written in the first person by poteto (the plugin manifest lists the author as Lauren Tan), MIT-licensed, living in the `cursor/plugins` repository under `pstack/`. Its pitch is "if you want to go fast, go deep first": the goal is fewer, higher-quality lines of code, not more output. The README says these are the skills poteto uses daily at Cursor, and that trusting one agent to write verifiable code is what makes "fearless parallelism" across many agents possible. ## Comparison The parts of pstack and how they relate: | Component | What it is | How you reach it | Where to read more | |---|---|---|---| | `/poteto-mode` + 23 playbooks | The front door. Matches a task to a playbook, copies its steps into a todo list, runs other skills as steps need them | Type `/poteto-mode <goal>` (or keep it on as a Custom Mode) | [[concepts/poteto-mode]], [[summaries/playbook-catalog]] | | Situational skills | `/how`, `/why`, `/architect`, `/arena`, `/swarm`, `/interrogate`, `/unslop`, `/tdd`, `/teach`, `/recall`, verification skills, etc. | Mostly run by `/poteto-mode`; type one directly to override | [[summaries/skill-catalog]], [[syntheses/which-skill-when]] | | 24 principles | One-rule skills (`principle-*`), grouped core / architecture / verification / delegation / meta. `poteto-mode` indexes them inline | Steer by name ("apply prove it works") or type `/principle-<name>` | [[summaries/principles-catalog]] | | Subagents | `poteto-agent` (delegate wrapper) and Comment Sicko (read-only comment reviewer) | `subagent_type: "poteto-agent"` / `"comment-sicko"` | [[entities/poteto-agent-and-comment-sicko]] | | Model config | `/setup-pstack` writes a per-role model rule | `/setup-pstack` | [[concepts/installation-and-model-setup]] | | benny automation pack | Dormant pack that triages Slack issue reports, then reproduces and fixes confirmed bugs. Not registered as slash skills; Cursor-only | Point Cursor at `automations/benny/FOR_AGENTS.md` | [[entities/benny-automation]] | | The guide | `docs/guide/` pages 01–10, from setup to overnight runs and recipes | Read in order the first time | [[syntheses/getting-started]] | The README skills table lists 32 skills and the principles table lists 24, which matches the 56 pstack skills a Codex user counted in issue #734 (open as of fetch 2026-10-21). ## Analysis **Philosophy.** The README frames AI "slop" as the problem and depth as the answer: "throughput without quality is not a goal". The guide's core habit is to stop micromanaging. You describe what you want and how you will know it is done; `/poteto-mode` picks the playbook and shows evidence. In practice this means pstack is opinionated about verification (the prove-it-works principle, project verification skills) and about prose (every reply goes through unslop rules). **Multi-model by design.** Out of the box, code delegates (feature, refactoring, bug fix, perf, hillclimb) go to Grok and the hardest changes, prose, and judgment go to Opus 5.5; the default panel is Opus 5.5 / Grok. `/setup-pstack` changes any of it. The defaults named in `poteto-mode` are `grok-4.7-xhigh-fast` for code and `claude-opus-5-5-xhigh` for prose and judgment. **How the parts fit.** The user normally types only two commands: `/setup-pstack` once, then `/poteto-mode` for any task that needs rigor. The README calls every other skill "situational": the mode skill runs `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `unslop`, `no-comments`, `technical-writing`, `tdd`, and the principles as steps fire. Playbooks are step lists inside `/poteto-mode`, not skills, so they have no slash command. **Not shipped in pstack.** `poteto-mode` references things it does not bundle: - `/deslop` and the `deslop` skill, plus `control-cli` (CLIs and TUIs) and `control-ui` (browser, Electron, web), ship in the `cursor-team-kit` plugin. Install it alongside pstack for the full set. - `/create-skill` and `/loop` are Cursor built-ins. Cursor also has a built-in `/autopilot` that watches a PR; inside `poteto-mode`, PR-status requests go to the Babysit playbook instead. - pstack has no `/orchestrate` skill. Orchestrate is a playbook; a `/orchestrate` in the slash menu comes from another plugin. **Why no planning skills.** The README says Cursor's plan mode works well with pstack, and poteto personally doesn't "believe in planning" because "the best spec is code". If you want a plan, asking `/poteto-mode` for one runs the Multi-phase plan playbook, which writes the plan without implementing it. Design questions are settled in code first, via the Prototype playbook or `/architect`. **Harness reach.** pstack is built for Cursor. It also installs in Claude Code from a generated copy (see [[syntheses/pstack-on-claude-code]]). `/poteto-help` notes other tools can read the skills because they use the Agent Skills format, but subagent spawning with per-role models, Custom Modes, and `/loop` are Cursor features, so those parts may not work elsewhere. ## Recommendations Start-here routing (wiki's analysis): - **Brand new:** [[syntheses/getting-started]] for install → `/setup-pstack` → first `/poteto-mode` task. - **Using Claude Code instead of Cursor:** [[syntheses/pstack-on-claude-code]]. - **Writing a good prompt:** [[concepts/prompting-pstack]]. - **Unsure which skill fits:** [[syntheses/which-skill-when]], or type `/poteto-help <question>`. - **Long or overnight work:** [[syntheses/overnight-and-autonomous-runs]]. - **Something broke:** [[summaries/known-issues]] and [[syntheses/recipes-and-pitfalls]]. - **Customizing:** [[concepts/make-it-yours]] (`/automate-me` drafts your own `-mode` skill). - Install `cursor-team-kit` too if you want `/deslop` and the control skills that `poteto-mode` routes to. - Save `/poteto-mode` for work that needs rigor; it spends extra tokens on subagents and review panels. ## Pages Compared - [[concepts/poteto-mode]] - [[summaries/skill-catalog]] - [[summaries/playbook-catalog]] - [[summaries/principles-catalog]] - [[entities/poteto-agent-and-comment-sicko]] - [[entities/benny-automation]] - [[entities/pstack]] - [[concepts/installation-and-model-setup]] ## Sources - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-docs-guide-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/README.md - raw/github_doc-pstack-skills-poteto-mode-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - raw/github_doc-pstack-plugin-json.md — https://github.com/cursor/plugins/blob/main/pstack/plugin.json - raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md — https://github.com/cursor/plugins/issues/734 <!-- ===== pstack/wiki/syntheses/pstack-on-claude-code.md ===== --> --- title: "pstack on Claude Code" type: synthesis tags: [pstack, claude-code, harness, adapter, cursor, codex] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-docs-harness-claude-code-md.md", "raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-docs-guide-01-setup-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md", "raw/github_issue-pstack-601-pstack-claude-code-and-codex-mapping-for-cursor-specific-ins.md", "raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md", "raw/github_issue-pstack-237-pstack-poteto-mode-name-breaks-the-documented-identifier-con.md", "raw/github_issue-pstack-701-poteto-mode-claude-code.md", "raw/github_commits-pstack-log.md"] --- # pstack on Claude Code pstack is written for Cursor and uses Cursor names throughout. It also installs in Claude Code, where an adapter file (`docs/harness/claude-code.md`) maps every Cursor name. This page compares the two and lists the open issues that affect Claude Code users. ## Comparison | Topic | Cursor | Claude Code | |---|---|---| | Install | `/add-plugin pstack` | `/plugin marketplace add cursor/plugins` then `/plugin install pstack@cursor-plugins` | | Command names | `/poteto-mode`, `/setup-pstack` | Prefixed: `/pstack:poteto-mode`, `/pstack:setup-pstack` | | Subagent types | `poteto-agent`, `comment-sicko`, `generalPurpose` | `pstack:poteto-agent`, `pstack:comment-sicko`, `"general-purpose"` | | Spawn tool | `Task` | `Agent` | | Questions | `AskQuestion` | `AskUserQuestion` (absent in `-p` mode; ask in plain text) | | Todo list | Open a todolist | `TodoWrite` if offered, else keep the list in the reply | | Running another pstack skill | `/name` | `Read` `<pstack>/skills/<name>/SKILL.md`; the `Skill` tool refuses most pstack skills | | Model rule | `~/.cursor/rules/pstack-models.mdc` | `~/.claude/rules/pstack-models.md` (no frontmatter; loaded into every new session) | | Model slug | `claude-opus-5-5-xhigh` | `model: "opus"` + `effort: "xhigh"`; `model` takes only `opus`, `sonnet`, `haiku`, `fable`; drop `-fast` | | Non-Claude slug (`grok-*`, `gpt-*`) | Used as-is | Omit `model` (runs on session model) and say so; `grok-4.7-xhigh-fast` maps to `inherit-parent` | | `readonly: true` | Readonly subagent | `subagent_type: "Explore"` plus "do not edit files" in the brief, then check `git status` | | `environment: "cloud"` | Cloud agent | `isolation: "worktree"`, naming the branch or commit | | `run_in_background: true` | Field | Omit (background is the default) | | `resume` | Field | Spawn a new agent with the earlier result pasted into the brief | | Skill paths | `.cursor/skills/`, `~/.cursor/skills/` | `.claude/skills/`, `~/.claude/skills/` | | Always-applied rules | `.cursor/rules/*.mdc` | `CLAUDE.md`, or `AGENTS.md` when no `CLAUDE.md` exists (model rule is the exception) | | Transcripts | `~/.cursor/projects/<slug>/agent-transcripts/` | `~/.claude/projects/<slug>/<session>.jsonl` (slug = workspace path with `/` and `.` → `-`) | | Automations, Bugbot, cloud agents | Supported | Skipped with one line: `Skipped in Claude Code: <step>. <reason>.` | | PR tool | Built-in | Use the forge command the step gives, e.g. `gh pr create` (not a skip) | ## Analysis **Generated copy.** Claude Code does not install `pstack/` directly. Per the README, it installs a generated copy (including the README and guide) from `harness/pstack/` at the repository root. Maintainers regenerate it with `node scripts/generate-pstack-harness-trees.mjs` from the repo root and commit the result; CI fails while the copy is out of date. The commit log records this landing as "install pstack in Claude Code from a generated tree (#637)" on 2026-10-16, followed by "close three gaps in the Claude Code plugin (#705)" on 2026-10-17. **setup-pstack in Claude Code.** Detected models are the `model` values in the `Agent` tool schema, each with an effort, written as `<model> <effort>` (e.g. `opus xhigh`). The skill writes `~/.claude/rules/pstack-models.md` with no frontmatter, overwriting the whole file, and must never put role lines in `CLAUDE.md` or `AGENTS.md`. If the file or a role line is missing, the skill's default slug applies. **Skipping is non-blocking.** When a step needs a Cursor-only feature, the adapter says to write the one-line skip and continue: do not stop, ask, or retry. If a later step needs the skipped output (a URL, a key), leave a placeholder and name it. Bugbot comments on a GitHub PR are treated as ordinary review threads; a step that starts or configures Bugbot is skipped when the PR has no Bugbot check or comment. The benny automation is Cursor-only (README). **Cross-family panels shrink.** Because a Grok or GPT slug is replaced by the session model, multi-model panels (interrogate, arena, architect) run on Claude only unless you adapt them. Analysis: this weakens the "diverse panel" premise; issue #601's external adaptation addresses it by running the second seat through another harness CLI. ## Recommendations - Read the adapter once per session; the adapter itself says to. - After `/pstack:setup-pstack`, start a new session so the rule loads. - Treat principle citations skeptically. Issue #726 (open as of fetch 2026-10-21) audited 18 `/pstack:poteto-mode` runs (pstack 0.15.25/0.15.27, Opus 5.5): the agent read the adapter in 1 run and a `principle-*/SKILL.md` in 0 runs, yet sometimes named principles anyway; one run spawned `general-purpose` instead of `pstack:poteto-agent`. Steering with "read `principle-<name>` first" is a possible workaround (wiki's analysis); a commenter's 72-run test on omp (not Claude Code) found a one-sentence read instruction moved only 7 of 72 runs, while principle lists inside each playbook reached 68 of 72. - If the slash menu shows `/pstack:Poteto Mode` and sending fails, you have an older copy. Issue #237 (still open as of fetch) reports this in Claude Code and T3 Code; a 2026-10-17 commit is titled "fix(pstack): name every skill after its folder (#702)", and the current `poteto-mode` SKILL.md has `name: poteto-mode`. Issue #701 (open) is the same symptom; a comment there by deanrie (not a maintainer ruling) says `/pstack:poteto-mode` is the form that resolves until the fixes land. Update the plugin. - The fetched files document no official Codex install. Issue #601 (open) links an external adaptation for Claude Code and Codex; issue #734 (open) requests official Codex install and native agents, and a commenter there measured that `codex plugin marketplace add cursor/plugins` then `codex plugin add pstack@cursor-plugins` installs the Claude Code copy today (Codex ignores `disable-model-invocation`). Both issues are still open as of fetch. ## Pages Compared - [[concepts/installation-and-model-setup]] - [[concepts/poteto-mode]] - [[entities/poteto-agent-and-comment-sicko]] - [[entities/pstack]] - [[summaries/known-issues]] - [[syntheses/overview]] ## Sources - raw/github_doc-pstack-docs-harness-claude-code-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/harness/claude-code.md - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-docs-guide-01-setup-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/01-setup.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md — https://github.com/cursor/plugins/issues/726 - raw/github_issue-pstack-601-pstack-claude-code-and-codex-mapping-for-cursor-specific-ins.md — https://github.com/cursor/plugins/issues/601 - raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md — https://github.com/cursor/plugins/issues/734 - raw/github_issue-pstack-237-pstack-poteto-mode-name-breaks-the-documented-identifier-con.md — https://github.com/cursor/plugins/issues/237 - raw/github_issue-pstack-701-poteto-mode-claude-code.md — https://github.com/cursor/plugins/issues/701 - raw/github_commits-pstack-log.md — https://github.com/cursor/plugins/commits/main/pstack <!-- ===== pstack/wiki/syntheses/recipes-and-pitfalls.md ===== --> --- title: "Recipes and Pitfalls" type: synthesis tags: [pstack, prompts, recipes, pitfalls, troubleshooting] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md", "raw/github_doc-pstack-skills-poteto-help-references-recipes-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_issue-pstack-237-pstack-poteto-mode-name-breaks-the-documented-identifier-con.md", "raw/github_issue-pstack-335-pstack-default-task-model-slugs-are-unresolvable-in-current-.md", "raw/github_issue-pstack-357-pstack-poteto-agent-description-routes-poteto-mode-into-a-ne.md", "raw/github_issue-pstack-449-pstack-worktree-cleanup-treats-untracked-and-ignored-files-a.md", "raw/github_issue-pstack-483-pstack-comment-sicko-agent-name-has-a-space-and-grok-rejects.md", "raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md", "raw/github_issue-pstack-731-pstack-watch-pr-blocked-merge-state-with-green-ci-reports-re.md", "raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md", "raw/github_issue-pstack-750-pstack-watch-pr-status-only-retries-for-minutes-on-a-repo-wi.md", "raw/github_issue-pstack-470-worktree-audit-sh-closed-unmerged-prs-and-unpushed-commits-a.md", "raw/github_issue-pstack-567-worktree-audit-sh-merged-is-checked-against-a-hardcoded-orig.md", "raw/github_issue-pstack-701-poteto-mode-claude-code.md", "raw/github_issue-pstack-531-ci-and-validator-cover-manifests-only-skills-hooks-mcp-json-.md", "raw/github_commits-pstack-log.md", "raw/github_doc-pstack-skills-poteto-mode-scripts-worktree-audit-sh.md"] --- # Recipes and Pitfalls Prompts worth copying, the mistakes guide 10 says "everyone makes once", and a troubleshooting table built from poteto-help and the issue tracker. Guide 10 says the recipes are "deliberately informal". Swap in your own paths and finish conditions. ## Comparison ### Copyable prompts (verbatim from guide 10) | Goal | Prompt | |---|---| | Understand a subsystem | `use /how first to understand how this initialization works. then use /why to figure out why it broke recently.` | | Restate a noisy report | `/poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet.` | | Sharpen a prompt | `/sharpen write the onboarding doc for the new billing service.` | | Prototype before picking | `/poteto-mode prototype a few options for the settings layout. put them behind a switcher and send me screenshots of each.` | | Design → plan | `/poteto-mode turn this design into a plan. small verifiable PRs, each with its own proof.` | | Second opinion on a design | `ask /arena for a second opinion on this thread and our approach` | | Parallel slice checks | `/swarm check every package under packages/ against its check.sh. one worker per package. one report.` | | Skeptical branch review | `/interrogate the whole branch, but skeptically. don't change anything yet. no nitpicks unless it's an actual bug or regression in behavior.` | | Bug via failing test | `/poteto-mode repro the duplicate write first. if there's a cheap test path, /tdd it. then fix and rerun.` | | Repro + fix with proof | `/poteto-mode repro this with /verify-<app>. if it repros on main, fix it and show me a video as proof.` | | Formal property | `/create-formal-verification-skill the retry queue. a message must never be delivered twice.` | | Vet a number | `/benchmark-checklist vet this 40% speedup before it goes in the pr description` | | Stop a repeated mistake | `/correct agents keep adding new config flags without registering them in the schema` | | Ask without starting work | `/poteto-help how do i get poteto-mode to stay on every turn?` | | Overnight, honest | `im going to bed, keep going autonomously until every fixture passes. do not stop. keep a decision log i can audit in the morning.` | | Plain-words reply / catch up | `/bro` · `/ketchup` | One-line steers for a drifting run (guide 10): ```text i said the goal is to repro. i did not ask for a fix yet. ``` ```text apply prove it works. show me the real output, not the build log. ``` ```text /unslop that, no emdashes ``` ### Extra templates from poteto-help `references/recipes.md` (verbatim) - Feature: `/poteto-mode add <behavior>. <current output> stays byte-identical. verify both.` - Refactor: `/poteto-mode move <code> into one module, zero behavior change. record the current output first and prove it's unchanged after.` - Perf: `/poteto-mode <operation> takes <time> on <fixture>. trace it, fix the measured cause, show me before and after.` - Migration plan: `/poteto-mode plan the migration of <library> to <target>. small verifiable PRs. the result must match the original exactly, bugs included.` - Babysit / status: `/poteto-mode babysit this pr. get it green.` · `/poteto-mode check on pr <number>. anything outstanding?` · Land: `/poteto-mode land the stack.` - Takeover: `/poteto-mode take over this branch. read the decision log, find what's done, and continue. don't redo finished work.` - Overnight (full): `/poteto-mode im going to bed. <goal> in a fresh worktree off <base>. done means <checks>. keep a decision log. don't ask me before committing. /loop until done. if you're truly stuck after a few hours, stop and write up why.` - Autopilot: `/poteto-mode full autopilot on this queue. each item is independent.` · `/poteto-mode autopilot these changes but stack them, don't ship. i'll land the stack.` - After: `/reflect capture what we learned so the next run doesn't repeat it.` The recipes file adds: "Approve only edits that change a future decision." ### The pitfalls (guide 10) | Pitfall | Why it hurts | Do instead | |---|---|---| | Enumerating skills in the prompt | Reorders steps the playbook already sequences | State goal + constraints; name a skill only to override | | Vague finish condition | "make it better" gives `/loop` nothing to check | A command or artifact that passes or fails | | Leading with your theory | The agent searches where you pointed | Ask for a restatement first, then share the hunch | | Taking the first design | Locks in the model's first shape | Prototypes or `/architect`, pick from evidence | | Polishing an abstract plan | Adversarial review of planless code invents risks | Settle questions with prototypes, review what got built | | Parallel agents in one worktree | They overwrite each other | Cloud agents, or "own worktree per attempt" | | Looping before trusting the loop | Unchecked work gets faster | Get the verification skill working first | | Trusting an unvetted number | Warm cache or skipped path fakes a speedup | `/benchmark-checklist` | | Correcting the same mistake by hand | Helps one run | `/correct` | | `/arena` for coverage | arena repeats one brief | `/swarm` partitions slices | | Accepting every review comment | Real catches mixed with noise | `/interrogate` sorts act-on vs dismissed | | Treating `auto` as a model slug | `auto`/`inherit-parent` mean omit the model field | See setup roles | | Success off a green build | A build proves it compiles | Ask for real command/flow/value/profile | | Writing a `SKILL.md` freehand | Skips validation and review | Authoring-a-skill playbook | ## Analysis ### Troubleshooting table The first block comes from poteto-help's "Fix a run that went wrong" table. The rest come from issues, with state as of fetch 2026-10-21. | Symptom | Cause | Fix / workaround | Source (state) | |---|---|---|---| | Mode stops applying after a few turns | Started with Enter (one message only) | Option+Enter / Alt+Enter for a Custom Mode, or `/poteto-mode` per task | poteto-help | | A question was treated as the next step | Mode still attached | Say "new task" | poteto-help | | New model choice had no effect | The `/setup-pstack` rule applies to new chats | Start a new chat | poteto-help | | A skill didn't load on its own | Only `/setup-pstack` loads from your words | Type it, or let `/poteto-mode` run it | poteto-help | | Overnight run moved but finished nothing | `/loop` got a duration, not a check | Give a pass/fail check | poteto-help | | `Invalid model selection "…". Model could not be resolved…` | Task allow-list exposes one effort tier per family | Use the closest valid slug from the error list, e.g. a `-medium` tier | #335 (open) | | Claude Code slash menu shows `/pstack:Poteto Mode` and it won't send | `name` didn't match the folder | Rename `name:` to the folder name. Commit #702 ("name every skill after its folder") did this upstream on 2026-10-17 | #237 (open) | | `/no-comments` never starts Comment Sicko on Grok Build | Agent name had a space | Update; the agent is now `comment-sicko` (fix #486, per the thread and the commit log) | #483 (closed) | | On a Cloud Agent, no todo list and no subagents | A spawned `poteto-agent` ran the playbook one level down | The chat that receives `/poteto-mode` runs it. Commit #575 ("make the /poteto-mode chat the runner, poteto-agent a delegate") is the likely fix; the issue does not name it | #357 (closed) | | poteto-mode in Claude Code never cites or reads principles | Principle reads are never a step; leaves are typed-only | Commenter experiment: list principles in each playbook. Not shipped | #726 (open) | | `watch-pr --status-only` prints `RETRY … GraphQL rollup was empty` for minutes | No checks configured; treated as retryable | Downstream fork fix (`ci-none`); no upstream fix at fetch | #750 (open) | | watch-pr says `ready` but GitHub blocks the merge | `BLOCKED` + green rollup is allowed by design | Treat `ready` as CI-clean; check required reviews yourself | #731 (open) | | Claude Code: `Unknown command: /Poteto` after picking `/pstack:Poteto Mode` | Display name vs folder-name mismatch on older installs | Type `/pstack:poteto-mode` (a Cursor-side commenter, deanrie, says that form resolves) | #701 (open) | | Audit marks a worktree `safe` although its PR was closed unmerged or it has unpushed commits | `safe` accepts any PR state; the REMOTE column is ignored | Check the REMOTE (`ahead*`, `no-remote`, `detached`) and PR (`/CLOSED`) columns before pruning; PR #492 pending | #470 (open) | | Audit shows `MERGED=no` for branches that landed in a non-main base | MERGED was checked against `origin/main` | `scripts/worktree-audit.sh -b origin/<branch>` | #567 (closed) | | A change to a SKILL.md or script broke something that CI didn't catch | CI validates manifests only; script test suites never run in CI | Run `bun test orch watch-pr` in `skills/poteto-mode/scripts` locally | #531 (open) | | Worktree cleanup can delete untracked and ignored files (run artifacts, `.env`) | Untracked and ignored files treated as disposable; `--force`, `rm -rf` | Use your own retirement procedure until PR #459 | #449 (open) | | On Codex, pstack skills show up in the automatic skill list | Codex's parser never reads `disable-model-invocation` (commenter's measurement, Codex CLI 0.163.0: 56 listed) | Commenter's `agents/openai.yaml` with `allow_implicit_invocation: false` cut it to 1 | #734 (open) | Analysis: several pitfalls share one failure, an unverifiable finish line ("make it better", a green build, an unvetted number, a loop with no verifier). The fix is the same each time: give the agent something that can fail. The issue-derived rows are mostly harness edges (Cloud Agents, Grok Build, Claude Code, Codex) and watch-pr policy, not core-skill bugs. ## Recommendations The wiki's own guidance, drawn from the material above: 1. Copy a recipe, swap in a real finish condition, and send it. Informal wording is fine. 2. When a run drifts, steer with one line and a principle name. Don't rewrite the prompt. 3. Before any overnight or `/loop` run, check the verification skill works. See [[syntheses/overnight-and-autonomous-runs]]. 4. Treat worktree cleanup as hazardous until #449 and #470 are resolved. See [[concepts/worktrees]]. 5. Check [[summaries/known-issues]] before you report a bug. Several symptoms above are already tracked. ## Pages Compared - [[concepts/prompting-pstack]], [[syntheses/which-skill-when]], [[summaries/known-issues]], [[concepts/shipping-prs-and-watch-pr]], [[concepts/installation-and-model-setup]], [[summaries/principles-catalog]] ## Sources - raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/10-recipes-and-pitfalls.md - raw/github_doc-pstack-skills-poteto-help-references-recipes-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/references/recipes.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - raw/github_issue-pstack-237-pstack-poteto-mode-name-breaks-the-documented-identifier-con.md — https://github.com/cursor/plugins/issues/237 - raw/github_issue-pstack-335-pstack-default-task-model-slugs-are-unresolvable-in-current-.md — https://github.com/cursor/plugins/issues/335 - raw/github_issue-pstack-357-pstack-poteto-agent-description-routes-poteto-mode-into-a-ne.md — https://github.com/cursor/plugins/issues/357 - raw/github_issue-pstack-449-pstack-worktree-cleanup-treats-untracked-and-ignored-files-a.md — https://github.com/cursor/plugins/issues/449 - raw/github_issue-pstack-483-pstack-comment-sicko-agent-name-has-a-space-and-grok-rejects.md — https://github.com/cursor/plugins/issues/483 - raw/github_issue-pstack-726-pstack-in-claude-code-poteto-mode-cites-principles-without-r.md — https://github.com/cursor/plugins/issues/726 - raw/github_issue-pstack-731-pstack-watch-pr-blocked-merge-state-with-green-ci-reports-re.md — https://github.com/cursor/plugins/issues/731 - raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md — https://github.com/cursor/plugins/issues/734 - raw/github_issue-pstack-750-pstack-watch-pr-status-only-retries-for-minutes-on-a-repo-wi.md — https://github.com/cursor/plugins/issues/750 - raw/github_issue-pstack-470-worktree-audit-sh-closed-unmerged-prs-and-unpushed-commits-a.md — https://github.com/cursor/plugins/issues/470 - raw/github_issue-pstack-567-worktree-audit-sh-merged-is-checked-against-a-hardcoded-orig.md — https://github.com/cursor/plugins/issues/567 - raw/github_issue-pstack-701-poteto-mode-claude-code.md — https://github.com/cursor/plugins/issues/701 - raw/github_issue-pstack-531-ci-and-validator-cover-manifests-only-skills-hooks-mcp-json-.md — https://github.com/cursor/plugins/issues/531 - raw/github_commits-pstack-log.md — https://github.com/cursor/plugins/commits/main/pstack - raw/github_doc-pstack-skills-poteto-mode-scripts-worktree-audit-sh.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/scripts/worktree-audit.sh <!-- ===== pstack/wiki/syntheses/which-skill-when.md ===== --> --- title: "Which Skill When" type: synthesis tags: [pstack, decision-map, skills, playbooks, comparison] created: 2026-10-21 updated: 2026-10-21 confidence: medium sources: ["raw/github_doc-pstack-readme-md.md", "raw/github_doc-pstack-skills-poteto-help-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-skill-md.md", "raw/github_doc-pstack-skills-arena-skill-md.md", "raw/github_doc-pstack-skills-swarm-skill-md.md", "raw/github_doc-pstack-skills-how-skill-md.md", "raw/github_doc-pstack-skills-why-skill-md.md", "raw/github_doc-pstack-skills-teach-skill-md.md", "raw/github_doc-pstack-skills-tdd-skill-md.md", "raw/github_doc-pstack-skills-poteto-mode-playbooks-bug-fix-md.md", "raw/github_doc-pstack-skills-create-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-create-formal-verification-skill-skill-md.md", "raw/github_doc-pstack-skills-interrogate-skill-md.md", "raw/github_doc-pstack-skills-reflect-skill-md.md", "raw/github_doc-pstack-skills-blast-radius-skill-md.md", "raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md", "raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md", "raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md"] --- # Which Skill When **Default answer: `/poteto-mode`.** The README calls it the "default entry point for any non-trivial task". poteto-help says to name a skill directly only "when the user wants more or less of something than the playbook gives". Guide 10 lists enumerating skills in a prompt as a pitfall, because it "reorders steps the playbook already sequences". The map below is for the cases where you go direct. ## Comparison ### "I want to…" → use | I want to… | Use | |---|---| | Do any non-trivial task with rigor | `/poteto-mode` (it picks a playbook) | | Find out which skill/playbook/principle fits, without starting work | `/poteto-help` | | Check the agent understood my goal before it starts | `/in-your-own-words` | | Make my prompt deeper before sending it | `/sharpen` (returns the rewrite only) | | Know how code works now, or where new code should live | `/how` | | Know why code is shaped this way, or where a number came from | `/why` | | Actually understand a change or subsystem, explained plainly | `/teach` | | Rebuild my recent context across chats | `/recall` | | Catch up on this chat since my last message | `/ketchup` | | Hear the last reply in plain words | `/bro` | | Settle types and module shape before code crosses a function boundary | `/architect` | | Get several attempts at one brief, merged into the best | `/arena` | | Run parallel checks over slices, or race workers | `/swarm` | | Have different models try to break my diff | `/interrogate` | | Know what a small diff breaks outside itself | `/blast-radius` | | Fix a bug test-first with a cheap local test | `/tdd` (or the Bug fix playbook, which points to it) | | Vet a perf number before reporting it | `/benchmark-checklist` | | Give agents a scripted way to drive my app | `/create-verification-skill` | | Prove a race/invariant tests rarely reach | `/create-formal-verification-skill` | | Run a large or cross-cutting change I'll review later | `/figure-it-out` | | Keep an auditable decision log | `/show-me-your-work` | | Strip comments before review | `/no-comments` | | Clean AI tells from prose / write docs to a standard | `/unslop` / `/technical-writing` | | Turn a finished task's lessons into skill edits | `/reflect` | | Stop agents repeating the same repo mistake | `/correct` | | Build my own routing mode | `/automate-me` | | Choose models per role and a budget | `/setup-pstack` | ### Close calls | Pair | Difference (from the sources) | Pick | |---|---|---| | **arena vs swarm** | arena gives every candidate the **same prompt**. It derives a rubric that candidates never see ("Candidates only see the task"), used by the cross-judge and the picker, then picks a base and grafts the best parts of the losers. swarm partitions work into **slices** or races N workers, then aggregates one `PASS`/`ISSUES`/`BLOCKED` report. Guide 10 lists "Using `/arena` for coverage" as a pitfall | arena for a design or code bakeoff, swarm for coverage, gauntlets and races | | **how vs why vs teach** | "`/how` explains what the code does. `/why` explains the reasons. `/teach` runs one or both and explains the result plainly" (poteto-help). why discovers MCPs at run time and queries each evidence category in parallel. teach keeps why "narrow by default since its full sweep is slow" | how before changing code, why for history and regressions, teach when *you* need to understand it | | **tdd vs Bug fix playbook** | tdd is a narrow workflow: failing test, fix, rerun. It says "Prefer no new test over a bad test" and skips when the test path is unclear, expensive or integration-heavy. The Bug fix playbook goes wider: repro on the real surface, binary-search the cause with how/why, delegate, verify on the same surface, then stage the failing repro before the fix. It points to tdd only "when the bug has a cheap local test path" | `/poteto-mode` (Bug fix) by default, with `/tdd` inside it, as in guide 10's "if there's a cheap test path, /tdd it" | | **verification vs formal verification** | create-verification-skill generates `.cursor/skills/verify-<app>/` with Launch / Doctor / Drive / Evidence / Cleanup, to drive the real app like a user. create-formal-verification-skill checks "every case in a stated scope" of one property, with a model checker, proof assistant or SMT verifier (TLA+ is the default for ordering questions). Each has a `maintain-` twin | verify skill to prove a feature works end to end; formal for races, retries, state machines, parsers, unsafe code | | **interrogate vs reflect** | interrogate reviews a **diff**: one reviewer per configured model, a synthesized verdict, "Do NOT auto-apply changes". reflect reviews the **transcript**: three lenses (judgment, tooling, divergent) plus a synthesizer, producing an Accepted / Rejected / Backlog list. Accepted edits wait for explicit approval; Backlog items are filed without waiting | interrogate before shipping code, reflect after a long task to improve skills | | **interrogate vs blast-radius** | "`/interrogate` reviews the diff. `/blast-radius` looks for breakage outside the diff and proves the one fact that makes the change safe" (poteto-help) | blast-radius for a small diff you don't trust; interrogate for a full review | | **poteto-help vs poteto-mode** | poteto-help answers the question, hands back a prompt and links the source. It does not start work, because "a pstack run spends real tokens". A work request sent to poteto-help gets routed to poteto-mode | poteto-help when unsure, poteto-mode to do the work | | **figure-it-out vs Orchestrate vs Autonomous run** | "`/figure-it-out` designs one rigorous run. The Orchestrate playbook runs a program that spans days and many PRs. The Autonomous run playbook drives one task to a finish condition" (poteto-help) | see [[concepts/orchestration-and-multi-phase-plans]] | | **recall vs ketchup vs Session pickup** | recall rebuilds context across recent chats. ketchup covers only this chat since your last message. Resuming one specific chat or branch is the Session pickup playbook | — | ## Analysis - Analysis: most of the close calls come down to **the same input vs split input** (arena vs swarm), **the code vs the history vs you** (how / why / teach), and **the diff vs the conversation** (interrogate vs reflect). Ask what the skill consumes and the choice usually falls out. - Analysis: a direct skill call skips poteto-mode's playbook scaffolding: the todo list, the `skip: <reason>` lines and Opening a PR. So `/tdd` alone gives you the test-first loop but not the same-surface repro or the PR conventions. Use the direct call when you want *less* than the playbook. - poteto-help says "Only `/setup-pstack` loads from the user's words"; the others load when you type them or when `/poteto-mode` runs them. Issues #527 and #734 report that every other skill sets `disable-model-invocation: true` (counts as of 0.15.15 and 0.15.29 respectively). Analysis: so if you describe a need without naming a skill and you aren't in `/poteto-mode`, pstack does not route it. poteto-help warns that a phrase like "babysit this pr" without `/poteto-mode` can instead start Cursor's own skill for that job. See [[summaries/skill-catalog]]. ## Recommendations The wiki's own guidance (analysis), except where a quote is attributed: 1. Start with `/poteto-mode` and a goal plus a pass/fail finish condition. Don't list skills. 2. Unsure? Ask `/poteto-help <question>`. It costs one cheap answer, not a run. 3. Reach for arena only when one brief deserves several attempts. Reach for swarm when work divides into independent slices. 4. For bugs, let the Bug fix playbook decide whether `/tdd` fits rather than forcing a test. 5. Build a verify skill before you rely on `/loop` or overnight runs. Guide 10 warns that "A loop that can't verify its own work only makes unchecked work faster." Add formal verification only where tests can't reach the failure. 6. After a long run, `/reflect` fixes the *skills*. `/correct` fixes the *repo*. ## Pages Compared - [[summaries/skill-catalog]], [[summaries/playbook-catalog]], [[concepts/poteto-mode]], [[concepts/understanding-code]], [[concepts/design-before-code]], [[concepts/code-review-with-interrogate]], [[concepts/verification-skills]], [[concepts/formal-verification]], [[concepts/build-and-clean]], [[concepts/make-it-yours]] ## Sources - raw/github_doc-pstack-readme-md.md — https://github.com/cursor/plugins/blob/main/pstack/README.md - raw/github_doc-pstack-skills-poteto-help-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-help/SKILL.md - raw/github_doc-pstack-skills-poteto-mode-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/SKILL.md - raw/github_doc-pstack-skills-arena-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/arena/SKILL.md - raw/github_doc-pstack-skills-swarm-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/swarm/SKILL.md - raw/github_doc-pstack-skills-how-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/how/SKILL.md - raw/github_doc-pstack-skills-why-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/why/SKILL.md - raw/github_doc-pstack-skills-teach-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/teach/SKILL.md - raw/github_doc-pstack-skills-tdd-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/tdd/SKILL.md - raw/github_doc-pstack-skills-poteto-mode-playbooks-bug-fix-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/poteto-mode/playbooks/bug-fix.md - raw/github_doc-pstack-skills-create-verification-skill-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/create-verification-skill/SKILL.md - raw/github_doc-pstack-skills-create-formal-verification-skill-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/create-formal-verification-skill/SKILL.md - raw/github_doc-pstack-skills-interrogate-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/interrogate/SKILL.md - raw/github_doc-pstack-skills-reflect-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/reflect/SKILL.md - raw/github_doc-pstack-skills-blast-radius-skill-md.md — https://github.com/cursor/plugins/blob/main/pstack/skills/blast-radius/SKILL.md - raw/github_doc-pstack-docs-guide-10-recipes-and-pitfalls-md.md — https://github.com/cursor/plugins/blob/main/pstack/docs/guide/10-recipes-and-pitfalls.md - raw/github_issue-pstack-734-pstack-support-codex-installation-and-native-agents.md — https://github.com/cursor/plugins/issues/734 (55 skills set `disable-model-invocation`; `setup-pstack` does not) - raw/github_issue-pstack-527-pstack-disable-model-invocation-hides-poteto-mode-s-routed-s.md — https://github.com/cursor/plugins/issues/527 ("all except `setup-pstack` in 0.15.15")