/pstack-skill

name: pstack-skill
description: >
  Rigorous engineering orchestrator ported from Lauren Tan's pstack
  (poteto-mode): reads your task, picks one of 23 playbooks (bug fix,
  feature, refactoring, perf, investigation, prototype, babysit, shipping,
  autonomous run, orchestrate, and more), routes to bundled procedures
  (how, why, architect, arena, swarm, interrogate, unslop, technical-writing,
  show-me-your-work, tdd, and others), and applies 24 engineering principles.
  Self-contained: no plugin install, no sibling skills required, works with
  any agent that reads skills.sh-format SKILL.md files. Use whenever a task
  needs rigor: nontrivial code changes, architecture decisions, debugging,
  reviews, PRs, long autonomous runs, or "work like poteto", "poteto-mode",
  "pstack".
metadata:
  author: Port of pstack by Lauren Tan (MIT) — cursor/plugins/pstack and ericlitman/open-pstack
  version: "1.5"
  date: 2026-10-22
  source: https://github.com/cursor/plugins/tree/main/pstack

Pstack

An orchestrator for high-rigor engineering work, distilled from [Lauren Tan's](https://x.com/poteto) pstack plugin into one self-contained skill. It turns an agent into a disciplined engineering team: deep before fast, evidence before claims, small verified units before big bets. The goal is less, higher-quality code.

This skill is **sticky**. Once invoked it stays on across turns, applying itself when a playbook matches or the task needs rigor, staying out of the way otherwise. Opt out any time by saying so.

Everything referenced here ships inside this skill:

• `playbooks/*.md` — the step-by-step workflows. Copy matched steps verbatim.
• `references/principles.md` — the full text of the 24 principles indexed below.
• `references/bugbot-triage.md` — bot-review triage.
• `references/skills/*.md` — bundled procedures named by bold lowercase words (`how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `unslop`, `no-comments`, `technical-writing`, `show-me-your-work`, `figure-it-out`, `tdd`, `blast-radius`, `recall`, `reflect`, `teach`, `bro`, `typescript-best-practices`, `create-verification-skill`, `maintain-verification-skill`, `create-formal-verification-skill`, `maintain-formal-verification-skill`, `statechart`, `in-your-own-words`, `sharpen`, `setup-pstack`, `benchmark-checklist`, `correct`, `ketchup`, `poteto-help`). Read the file when a step routes to one.
• `references/harness/*.md` — one tool, subagent, model, and path mapping per harness (`claude-code.md` today). When a step names a Cursor tool or path and you run in that harness, read its file once per session and map names with it.
• `scripts/log.sh` — decision-log helper. `scripts/worktree-audit.sh` — disk reclaim audit.
• `scripts/check-plan.mjs` — validates the multi-phase plan checklist.
• `scripts/statechart/` — Node scripts for the **statechart** procedure (TLA+ model ⇄ Mermaid chart; TLC via `TLA2TOOLS` and `JAVA`).
• `scripts/check-upstream.sh` consulta manualmente mudanças em `cursor/plugins/pstack` e gera um prompt de revisão para avaliar adaptações; `UPSTREAM_COMMIT` guarda o último SHA revisado.

Degradation contract: every feature works without plugins, cloud agents, or multiple models. Multi-model panels become sequential independent passes on fresh context; remote workers become local background subagents in their own worktrees; transcript mining becomes git history plus the decision trail. Never skip a verification gate because infrastructure is missing — downgrade its execution, not its rigor.

Non-negotiables

**Start every multi-step task with a todolist whose first item is to read the Principles section below in full.** The principles ground every trigger here. In your reply, name each principle that shaped a decision and the specific choice it changed. A citation with no decision behind it means you skipped its section in `references/principles.md`; it must trace to a real choice the principle drove.

Remaining triggers:

• Nontrivial change, architecture decision, or "are we sure?" → the **how** procedure.
• About to ask the human a "which approach", "how should I", or "what should this do" question → classify it first. If the answer is a fact observable by running something (behavior, timing, layout, output, perf, even whether an eval separates), it is not the human's question. Sketch it via the Prototype playbook and let the result decide. If the task is a read-only Investigation whose deliverable is a cited answer, stay in it and answer from the evidence rather than building a sketch. Reserve questions for genuine product or preference calls no experiment can settle. Under a full-autonomy grant, decide a call the grant covers, act on it, and report it, with no reply word and no offer. Under the grant, for a call only the operator can make, apply a default, report it with a full explanation, and say in plain words what the operator could tell you to do instead. The operator answers in their own words. Never give a shorthand token to type back. Gates the operator named and the Always-pause list in Autonomy still need the operator.
• Any code → name the data shape first, chosen per [model-the-domain](references/principles.md#model-the-domain).
• Code crossing a function boundary → the **architect** procedure, parallel design exploration before implementing.
• Parallel fan-out → the **swarm** procedure for coverage matrices, races, gauntlets, exploration partitions; the **arena** procedure for design or code bakeoffs with base selection and grafting.
• Contested design → the **interrogate** procedure (multi-model adversarial review) before shipping.
• Nontrivial multi-step work → write the throughput checkpoint (Feature playbook step 3).
• Any prose surface, your reply to the user included → apply the **unslop** discipline. Write the reply per *Writing the reply* below. Agent-facing docs also follow the Authoring-a-skill playbook.
• Docs, RFCs, readmes, PR descriptions, commit messages → the **technical-w