@jiroamato/pstack 0.0.0-stage → 0.15.15

package/pstack/automations/benny/templates/configuration.example.yaml

@@ -0,0 +1,84 @@
+schema_version: 1
+
+automations:
+  triage_name: "benny-triage"
+  reproduce_name: "benny-reproduce"
+
+slack:
+  source_channel_id: "SOURCE_CHANNEL_ID"
+  operations_channel_id: ""
+  triage_identity_user_id: "TRIAGE_IDENTITY_USER_ID"
+  read_action: "configured-slack-read-action"
+  thread_post_action: "configured-slack-thread-post-action"
+  file_download_action: "configured-slack-file-download-action"
+  operations_edit_action: "configured-slack-edit-action"
+  prefer_harness_actions: true
+  optional_bot_token_env: "BENNY_SLACK_BOT_TOKEN"
+  allow_source_root_posts: false
+  allow_worker_slack_writes: false
+
+repository:
+  url: "https://github.com/example-org/example-repo"
+  default_branch: "main"
+  pull_request_action: "configured-draft-pull-request-action"
+  pull_request_url_format: "https://github.com/{owner}/{repo}/pull/{number}"
+  draft_only: true
+
+tracker:
+  type: "linear"
+  adapter_skill_name: "issue-tracker-adapter-placeholder"
+  team: "team-placeholder"
+  project: "project-placeholder"
+  labels:
+    bug: "bug-label-placeholder"
+    performance: "performance-label-placeholder"
+    intake: "intake-label-placeholder"
+    needs_repro: "needs-repro-label-placeholder"
+  status: "intake-status-placeholder"
+  source_link_title: "Slack report"
+  require_compensation_action: true
+
+routing:
+  map_path: ".pstack/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: ".pstack/benny/feature-map.md"
+  environment: "safe-test-environment-placeholder"
+  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: "choose-an-available-public-model-slug"
+  reproduce: "choose-an-available-public-model-slug"
+  code: "choose-an-available-public-model-slug"
+  media_review: "choose-an-available-public-model-slug"

package/pstack/automations/benny/templates/reproduce-automation-prompt.md

@@ -0,0 +1,33 @@
+# Reproduce automation prompt
+
+> Source material for the copied setup workflow. Paraphrase this intent into an automation draft after the automation creator confirms that the copied pack is committed in the repository where the automation will run.
+
+Read and follow `.pstack/automations/benny/skills/reproduce-and-fix-issues/SKILL.md` for this run.
+
+Configuration source. Include this repository-relative path only when it is committed in the same target repository. Otherwise paraphrase the configured values. Never use a plugin source or cache path:
+
+```text
+{{BENNY_CONFIG_PATH}}
+```
+
+Trigger:
+
+```json
+{
+	"source_channel_id": "{{SLACK_CHANNEL_ID}}",
+	"message_ts": "{{SLACK_MESSAGE_TS}}",
+	"thread_ts": "{{SLACK_THREAD_TS_OR_EMPTY}}"
+}
+```
+
+The creation intent should describe this as a new top-level report in the configured source Slack channel. It should include the configured repository, default branch, issue tracker, control adapter, feature map, and draft pull request capability.
+
+Treat the source channel and root thread timestamp as immutable. If either is missing or does not match configuration, stop without posting.
+
+Wait for a configured triage marker from the configured triage identity in this exact thread. Proceed only for `[benny:bug]` or `[benny:performance]`.
+
+Require the configured control-adapter skill before attempting a repro. Reproduce the exact discriminating symptom twice through the real UI. Verify existing pull requests or commits without authoring over them. Attempt a bounded fix only after a confirmed repro and the operational file's fix gate.
+
+The coordinator is the only Slack poster. Every child prompt must forbid `SendSlackMessage`, `PostToSlack`, `chat.postMessage`, and all other Slack writes. Children return findings only.
+
+Never post a root message in the source channel.

package/pstack/automations/benny/templates/triage-automation-prompt.md

@@ -0,0 +1,39 @@
+# Triage automation prompt
+
+> Source material for the copied setup workflow. Paraphrase this intent into an automation draft after the automation creator confirms that the copied pack is committed in the repository where the automation will run.
+
+Read and follow `.pstack/automations/benny/skills/triage-issue-reports/SKILL.md` for this run.
+
+Configuration source. Include this repository-relative path only when it is committed in the same target repository. Otherwise paraphrase the configured values. Never use a plugin source or cache path:
+
+```text
+{{BENNY_CONFIG_PATH}}
+```
+
+Trigger:
+
+```json
+{
+	"source_channel_id": "{{SLACK_CHANNEL_ID}}",
+	"message_ts": "{{SLACK_MESSAGE_TS}}",
+	"thread_ts": "{{SLACK_THREAD_TS_OR_EMPTY}}"
+}
+```
+
+The creation intent should describe this as a new top-level report in the configured source Slack channel.
+
+Treat the source channel and root thread timestamp as immutable. If either is missing or does not match configuration, stop without posting or writing to the issue tracker.
+
+The committed operational file owns classification, attachment review, cause tracing, routing, dedupe, tracker writes, and the final verdict. Post no progress messages. Never post a root message in the source channel.
+
+The coordinator is the only Slack poster. Any delegated worker must be read-only, return findings only, and receive an explicit ban on every Slack write action.
+
+End the single verdict with exactly one configured marker:
+
+```text
+[benny:bug]
+[benny:performance]
+[benny:other]
+```
+
+A bug or performance marker may add `tracker=<URL>`.

package/pstack/codex/agents/comment-sicko.toml

@@ -0,0 +1,36 @@
+# Installed into ~/.codex/agents/ by the setup-pstack skill. Codex plugins cannot ship agents,
+# so setup-pstack copies this file there and fills in model and effort.
+name = "comment-sicko"
+description = "Comment Sicko. A deranged comment-hater that savors deletion and condemns workaround code. Read-only. Spawn from the no-comments skill with the scope. Reports deletions and MUST KILL flags, never edits code."
+sandbox_mode = "read-only"
+developer_instructions = """
+# Comment Sicko
+
+My first output when spawned is exactly this.
+
+Yes... Ha ha ha... Yes!
+
+I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all.
+
+Only these exceptions get to crawl away.
+
+- Legal or license headers.
+- Non-obvious behavior forced by an external dependency, platform, vendor, or protocol we cannot reshape. Surprises in our own code are meat. Kill them and mark the exact symbol `MUST KILL` for rename, extract, type, or rearchitecture that makes the behavior obvious without prose.
+- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only.
+- Doc comments that define a public API contract.
+- Issue or RFC links that explain a constraint code cannot express.
+
+That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat.
+
+`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`.
+
+`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run $how, $why, or both on the named symbol or call. Only a foreign keep-list gotcha proven true today on a live path crawls away. Our-code surprises die with the reshape flag above. Doubt after the hunt is meat.
+
+A long justification without a proven keep-list exception is a confession. Kill it. Never polish meat into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code.
+
+Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code.
+
+Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips.
+"""
+# model = "<setup-pstack fills this in>"
+# model_reasoning_effort = "<setup-pstack fills this in>"

package/pstack/codex/agents/poteto-agent.toml

@@ -0,0 +1,11 @@
+# Installed into ~/.codex/agents/ by the setup-pstack skill. Codex plugins cannot ship agents,
+# so setup-pstack copies this file there and fills in model, effort, and the poteto-mode path.
+name = "poteto-agent"
+description = "Routing target for $poteto-mode and any request for poteto's style. Spawn a fresh poteto-agent for each new task. Reads the poteto-mode skill in full before any work. Substituting default skips that read and drifts."
+developer_instructions = """
+You are operating as poteto-mode's full agent style. Invoke $poteto-mode and read its SKILL.md in full before doing any work, including its inline Principles index. If $poteto-mode is not available, read the file at the path on the last line. Navigate to a leaf principle-* skill whenever you apply that principle. Read the pstack-harness skill before your first spawn, model choice, or structured question.
+
+poteto-mode path: <setup-pstack fills this in>
+"""
+# model = "<setup-pstack fills this in>"
+# model_reasoning_effort = "<setup-pstack fills this in>"

package/pstack/docs/guide/01-setup.md

@@ -0,0 +1,80 @@
+# Set up pstack
+
+In this page you install the plugin, pick which models pstack uses, and run your first task. Setup is one command plus a short conversation.
+
+## Install the plugin
+
+pstack installs as a plugin on Claude Code and on Codex, or copies into a skills directory with npx. Pick one.
+
+The quick way, from a shell:
+
+```bash
+npx @jiroamato/pstack
+```
+
+It asks which agent (Claude Code or Codex) and where (this project or your home directory), then copies the skills and the two agents there. Re-run it to update, `npx @jiroamato/pstack uninstall` to remove. Installed this way the skills keep their bare names, so on Claude Code you type `/poteto-mode`.
+
+Or as a plugin, which the tool updates for you. Claude Code, from a shell:
+
+```bash
+claude plugin marketplace add jiroamato/pstack
+claude plugin install pstack@pstack-plugins
+```
+
+Codex, from a shell:
+
+```bash
+codex plugin marketplace add jiroamato/pstack
+codex plugin add pstack
+```
+
+Start a new session afterwards. On Claude Code the plugin's skills are namespaced, so type `/pstack:poteto-mode`. On Codex type `$poteto-mode`. The rest of this guide writes `/poteto-mode` for both.
+
+## Pick your models
+
+Run:
+
+```text
+/setup-pstack
+```
+
+[`/setup-pstack`](../../skills/setup-pstack/SKILL.md) detects the models you have access to, asks for a reasoning budget, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `~/.pstack/models.md`, a small file every pstack skill reads. It has one section per harness.
+
+On Codex the defaults run at `xhigh` reasoning, the same as the `large` budget. `unlimited` lifts each model to `max`. `medium` and `small` lower the reasoning and spend fewer tokens. On Claude Code effort is a session setting, so the budget tells you which `/effort` level to set instead of rewriting the roles.
+
+You only override what you care about. A role with no line in the file keeps the skill's default. To restore a default, delete that role's line. A rerun of `/setup-pstack` keeps any role whose model differs from the default. When a default changes, a file written before the change still pins the old default, so delete those role lines, or delete the file, then run `/setup-pstack` again.
+
+You might be wondering what happens if you use Auto. Set a role to `inherit-parent` or `auto` and pstack omits the subagent `model` field, so the subagent inherits your parent chat model. Both values mean the same thing, and neither is a model slug. For a panel role the value is a list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default model for every `/swarm` worker unless a race names a model for each arm.
+
+## Accept the verification offer, or don't
+
+At the end of setup, `/setup-pstack` looks for a way to prove app behavior in your project, either a `verify-*` skill or an existing harness. If it finds neither, it offers once to generate one with [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md).
+
+Say yes and it writes `verify-<app>/` into the project skills directory (`.claude/skills/` on Claude Code, `.agents/skills/` on Codex), a project-local skill that teaches agents to drive your app the way a user does. It proves the skill works once before handing it over. Say no and setup moves on. You can run `/create-verification-skill` yourself any time. [Verify and ship](./06-verify-and-ship.md#create-a-project-verification-skill) covers it in depth.
+
+If you're new to pstack, say yes. An agent that can check its own work keeps going until the check passes. An agent that can't hands every result back to you to check by hand. Of everything in this guide, the verification skill pays off the most.
+
+After setup, start a new chat. The models file applies to new sessions.
+
+## Keep the cost in check
+
+pstack spends extra tokens on subagents and review panels. That's the price of the rigor. To spend fewer:
+
+- Rerun `/setup-pstack` and pick a smaller reasoning budget or cheaper models. A strong model in the main chat with cheaper, faster models in the code roles is a good split.
+- Set a role to `auto` or `inherit-parent` so it runs on the chat's own model.
+- Shorten a panel list. Each entry runs one subagent.
+- Save `/poteto-mode` for work that needs rigor. A small, obvious edit doesn't.
+
+## Run your first task
+
+Pick something real but small, and describe it the way you'd describe it to a colleague:
+
+```text
+/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.
+```
+
+Watch the todo list. Its first items are the matched playbook's steps copied in, the Feature playbook for this prompt. If `/poteto-mode` skips a step, the step stays in the list with `skip: <reason>`, so you can see what it chose not to do.
+
+From here you can type normal follow-ups. To keep `/poteto-mode` on for the whole session, follow the harness **keep the mode on** row in the [`pstack-harness`](../../skills/pstack-harness/SKILL.md) skill. On Claude Code, start the session as the agent with `claude --agent pstack:poteto-agent`, or add one line to your `CLAUDE.md`: "Apply the pstack:poteto-mode skill to any non-trivial task." On Codex, add the same line with `$poteto-mode` to `AGENTS.md`. Typing the skill once attaches it to that message, and its content stays in context, but a fresh task may not re-match a playbook.
+
+Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).

package/pstack/docs/guide/02-poteto-mode.md

@@ -0,0 +1,131 @@
+# Route work through `/poteto-mode`
+
+`/poteto-mode` is the front door. You give it a goal, it matches one of twenty-three playbooks, copies that playbook's steps into the todo list, and calls the other skills as the steps need them. In this page you learn what a good prompt looks like, and how little of one you actually need.
+
+![A dispatcher pulls a switch lever to route robots on rail handcars toward lit gates, under a /poteto-mode departure board listing BUG FIX, FEATURE, and INVESTIGATION.](./images/router.jpg)
+
+## What happens to your prompt
+
+```mermaid
+flowchart TD
+    A[Your prompt] --> B[poteto-mode]
+    B --> C[Read the Principles section]
+    C --> D{Match the task}
+    D -->|Read-only question| E[Investigation]
+    D -->|Defect| F[Bug fix]
+    D -->|New behavior| G[Feature]
+    D -->|Structure only| H[Refactoring]
+    D -->|Measured slowness| I[Perf issue]
+    D -->|Large work or no match| J[figure-it-out]
+    E --> K[Verify and report]
+    F --> K
+    G --> K
+    H --> K
+    I --> K
+    J --> K
+```
+
+The diagram shows the common routes. There are also playbooks for hillclimbing a metric, diagnosing runtime symptoms and captured traces, prototypes, visual parity, authoring and evaluating skills, autonomous runs, babysitting a PR or stack to merge-ready, shipping a verified stack, running a PR queue on autopilot, orchestrating project-scale programs, session pickup, pausing safely, multi-phase plans, and worktree cleanup. The [playbook directory](../../skills/poteto-mode/playbooks/) has the full set.
+
+## Say the goal, not the ceremony
+
+You don't write a spec. You say what's wrong or what you want, plus anything you already know that saves the agent time:
+
+```text
+/poteto-mode users get two notifications after a retry. repro first, then fix and verify.
+```
+
+That's a Bug fix prompt. "repro first" is a real constraint, not politeness, and the playbook honors it. Watch the todo list fill with the Bug fix steps. A skipped step stays visible with `skip: <reason>`.
+
+## What goes in a prompt
+
+A useful prompt carries up to five things, and each one fits in a sentence:
+
+- **The goal.** Say what's wrong, or what you want.
+- **The done check.** It must be able to pass or fail. "Make it better" and "work on it for an hour" aren't checks.
+- **The proof you want to see.** Ask for the real command output, a video of the flow, the stored value, or a before-and-after number.
+- **What you already know.** A symptom, a repro step, a log line, or a link saves the agent a search.
+- **The real constraints.** "repro first", "don't change any code yet", "zero behavior change", and "let me review before proceeding" each change what the agent does.
+
+Here's one prompt with all five:
+
+```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.
+```
+
+Two things are worth leaving out:
+
+- **The how.** Say what to achieve, and leave the agent room to find a better path than the one you'd pick. The same goes for a list of skills, covered in the pitfall below.
+- **Your theory of the cause, at first.** A stated guess narrows the search to wherever you pointed. Let the agent restate the problem before you share your hunch.
+
+For a noisy report, such as a long thread or a vague bug, make the restatement the first step:
+
+```text
+/poteto-mode read this thread. restate the underlying issue in your own words, in plain english. don't change any code yet.
+```
+
+A misreading shows up in the restatement, before any code exists. Correct it there, and it costs you one message instead of one wrong fix.
+
+## Follow up short
+
+When the conversation already carries the context, the prompt shrinks to almost nothing. All of these are enough:
+
+```text
+/poteto-mode do it
+```
+
+```text
+continue
+```
+
+```text
+keep going until done
+```
+
+Short works because the playbook holds the structure, and keeping `/poteto-mode` on holds it in context on every turn. [Set up pstack](./01-setup.md#run-your-first-task) shows how. Your words carry the intent, and the skill carries the rigor.
+
+## Switch tasks with "new task"
+
+A long chat accumulates context from the last task. When you change subjects, say so:
+
+```text
+/poteto-mode new task. figure out why the cache entry survives logout. don't change any code yet.
+```
+
+"new task" tells `/poteto-mode` to re-match rather than continue the prior playbook. "don't change any code yet" pins this one to Investigation. Without those two phrases, a mode mid-Feature tends to treat your question as the next feature step.
+
+## Give parallel work its own worktree
+
+If you run several agents against one repository on one computer, they will fight over the working tree, the ports, and the build output. The cleanest isolation is a worktree per agent. On Claude Code, subagents take `isolation: "worktree"` and get their own checkout and branch. On Codex, ask for a `git worktree` per worker, or start the thread in the app's worktree mode. The [`pstack-harness`](../../skills/pstack-harness/SKILL.md) **isolation** row has the details.
+
+When the work has to stay local, ask for a worktree up front:
+
+```text
+/poteto-mode new task. branch off <base> in a fresh worktree, then port the parser change there.
+```
+
+Each task in its own branch and worktree means no agent stomps another's files. Worktrees cost disk and machine resources, so a laptop runs only a handful at once. The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) already works from a worktree for code changes, so mostly you only say this when a specific base or location matters.
+
+Worktrees accumulate. When disk gets tight, ask:
+
+```text
+/poteto-mode what's eating my disk? prune the worktrees that are safe to prune.
+```
+
+The [Worktree cleanup playbook](../../skills/poteto-mode/playbooks/worktree-cleanup.md) classifies every worktree by merge state, uncommitted work, and which chats still touch it. It deletes only what that evidence clears and pauses for your call on anything holding uncommitted work.
+
+## Leave it running
+
+When you step away, say what done means and go:
+
+```text
+/poteto-mode im stepping away. keep going until the migration check reports zero old callers. log your decisions.
+```
+
+Work you'll review later routes through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md), which designs the run's phases and keeps a [`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) decision log. [Run work while you sleep](./07-overnight.md) covers the full overnight contract.
+
+**Pitfall:** don't enumerate skills in your prompt ("use /how, then /architect, then /arena..."). The playbook already sequences them, and a hand-written sequence usually reorders or drops steps the playbook would have kept. Name a skill only when you want to override a specific choice.
+
+Read [`poteto-mode`](../../skills/poteto-mode/SKILL.md) itself for the full routing rules.
+
+Next: [Understand the code](./03-understand.md).

package/pstack/docs/guide/03-understand.md

@@ -0,0 +1,79 @@
+# Understand the code before changing it
+
+Editing code you don't understand is how subtle regressions ship, and that's as true for the agent as for you. Agents usually fail in one of two ways. They misread what you want, or they don't have the context to do the work right. [What goes in a prompt](./02-poteto-mode.md#what-goes-in-a-prompt) handles the first. This page handles the second.
+
+pstack gives you four ways in. `/how` explains what the code does now. `/why` digs up the reasons it's shaped that way. `/teach` blends both into one explanation. `/recall` rebuilds your own recent context on a topic. Each one also makes the agent explain itself in words you can check. That's how you supervise an agent that may know the code better than you do.
+
+![A detective studies a machine blueprint with a magnifying glass while robots fetch case files; the evidence board behind her links clues under /how and /why.](./images/understanding.jpg)
+
+## Start with a read-only investigation
+
+When the cause is unclear, ask for findings, not a fix:
+
+```text
+/poteto-mode investigate why background jobs time out every few hours. give me what we know, what data you used, and your best hypotheses. don't change any code yet.
+```
+
+"don't change any code yet" routes this to the [Investigation playbook](../../skills/poteto-mode/playbooks/investigation.md). It runs `/how`, adds `/why` for questions about motivation, and returns a cited explanation. For a choice between options, it returns a recommendation with a trade-offs table. Asking "what data you used" makes the agent separate its evidence from its guesses. When the findings point at a fix, start the fix as a new task.
+
+## Trace behavior with `/how`
+
+```text
+/how do we dedupe notifications? is there an n+1 when we look up subscribers?
+```
+
+Ask the question you actually have. [`/how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. For a big subsystem it fans out two to four read-only explorers first. For a narrow question it just reads and explains.
+
+## Dig up history with `/why`
+
+```text
+/why was the retry limit set to five? does the reason still hold?
+```
+
+[`/why`](../../skills/why/SKILL.md) works like a detective on a cold case. It starts from source control, then queries whatever evidence categories your MCPs expose, such as the issue tracker, long-form docs, team chat, observability, error tracking, and analytics, all in parallel. The report cites everything, separates direct evidence from inference, and says "appears to" when the record is thin. A null result gets reported too, because "nobody wrote down why" is itself an answer.
+
+The two compose naturally. `do why first then how` is a perfectly good prompt when you suspect the history explains the mess.
+
+## Actually understand it with `/teach`
+
+```text
+/teach me how this PR changes retries. convince me it fixes the cause and not the symptom.
+```
+
+[`/teach`](../../skills/teach/SKILL.md) is for when a summary isn't enough. It runs `/how` and `/why`, for a small change maybe just one of them, and weaves the findings into a plain explanation that builds up diagram by diagram. The "convince me" framing is worth stealing. It turns the explanation into an argument you can poke at instead of a tour.
+
+It works on the agent's own choices too:
+
+```text
+/teach me why you implemented it this way and not with a queue. what did you trade off, and why?
+```
+
+Teaching helps the agent as much as you. An agent that has to explain its work must read the code and back each claim with evidence, instead of stating it confidently and moving on.
+
+## Rebuild your own context with `/recall`
+
+```text
+/recall catch me up on the export work from last week
+```
+
+[`/recall`](../../skills/recall/SKILL.md) mines your own recent chats plus the shared record (issues, prior fixes, errors still firing) and hands back a brief on where things stand and what's next. Your old chats hold context that a fresh agent lacks, so start new work on an old topic by loading it first, then hand over the new input:
+
+```text
+/recall my work on the virtualized list from yesterday, then read this bug report.
+```
+
+If you want to resume one specific chat, that's the Session pickup playbook below, not `/recall`.
+
+## Take over prior work with Session pickup
+
+When another agent (or you, last week) left a branch mid-flight:
+
+```text
+/poteto-mode take over this branch. read the decision log, figure out what's done, and continue from there. don't redo finished work.
+```
+
+The [Session pickup playbook](../../skills/poteto-mode/playbooks/session-pickup.md) treats the prior trail as authoritative. It reconstructs the branch state and decisions, names the resume point, and verifies inherited claims against the original goal instead of re-deriving everything from scratch.
+
+**Pitfall:** don't skip this page's skills because "the agent will read the code anyway." An agent that starts editing without a traced model tends to fix the symptom at the first plausible spot. `/how` first is cheaper than the second bug.
+
+Next: [Design the change](./04-design.md).

package/pstack/docs/guide/04-design.md

@@ -0,0 +1,133 @@
+# Design before you write code
+
+One attempt at a hard design locks in the first shape the model thought of. `/architect` settles types and boundaries before implementation. `/arena` runs several attempts at the same brief and merges the best parts. `/interrogate` has other models try to break the result. When the job is coverage rather than design synthesis, `/swarm` fans out slices or races and aggregates their results.
+
+The two most common design mistakes are taking the agent's first design and polishing a plan that no code has tested. This page fixes both. You plan through code: prototypes answer the open questions, a README or tutorial sets the target, and the written plan comes last.
+
+![Three robots draft competing bridge models at their own tables under /architect, /arena, and /interrogate panels, while a judge robot with a clipboard inspects skeptically.](./images/design.jpg)
+
+## Settle the shape with `/architect`
+
+```text
+/architect design the import pipeline before writing any code. i care most about how callers use it.
+```
+
+[`/architect`](../../skills/architect/SKILL.md) grounds itself first, running `/how` over the code the design touches and `/why` when it moves ownership or layers. Then it runs `/arena` to produce competing design sketches, with the caller's usage written first in each, followed by types, signatures, and a module map.
+
+By default it proceeds straight from the synthesized design into implementation. If you want to see the design first, say so:
+
+```text
+/architect with checkpoint. stop and show me before implementing.
+```
+
+The design isn't sacred once code starts. If implementation shows the same workaround in unrelated places, or types that only compile with `any` or forced casts, `/architect` treats that as proof the design is wrong. It scraps the sketch and starts over instead of patching around it.
+
+## Fan out attempts with `/arena`
+
+```text
+/arena take my prompt to the arena verbatim. i want to compare their proposals with yours.
+```
+
+[`/arena`](../../skills/arena/SKILL.md) is the general tool underneath. N subagents attempt the same design or code brief in parallel, each writing to its own worktree or directory. A read-only judge, on a different model family when your configuration allows one, scores every candidate against a rubric. The coordinator reads each candidate end to end, picks a base, grafts in the best ideas from the losers, and verifies the result.
+
+```mermaid
+flowchart LR
+    A[One task] --> B[Configured panel]
+    B --> C[Candidate 1]
+    B --> D[Candidate 2]
+    B --> E[Candidate N]
+    C --> F[Cross-judge]
+    D --> F
+    E --> F
+    F --> G[Pick a base]
+    G --> H[Graft the best parts]
+    H --> I[Verify]
+```
+
+The panel comes from your [`/setup-pstack`](../../skills/setup-pstack/SKILL.md) configuration, and you can adjust it per task. Ask for more candidates when the decision matters, fewer when it doesn't:
+
+```text
+/arena this, 5 candidates. the cache key format is expensive to change later.
+```
+
+## Cover slices and races with `/swarm`
+
+```text
+/swarm check every package under packages/ against its check.sh. one worker per package. one report.
+```
+
+[`/swarm`](../../skills/swarm/SKILL.md) fans N workers across independent slices, coverage matrices, gauntlet lanes, exploration partitions, or declared race arms. Each worker gets its own scope and check, then reports `PASS`, `ISSUES`, or `BLOCKED`. The parent waits for the workers and returns one compact report with any gaps or dropouts.
+
+Reach for it when parallelism buys coverage or lets independent checks race. `/arena` gives every worker the same design or code brief, then picks a base and grafts the best parts. `/swarm` covers slices or runs a race with a selection rule declared up front. It does not use the base-selection and grafting ceremony.
+
+## Break it with `/interrogate`
+
+```text
+/interrogate the whole branch, but skeptically. no nitpicks unless it's an actual bug or regression.
+```
+
+[`/interrogate`](../../skills/interrogate/SKILL.md) sends the same diff, intent, and rubric to reviewers on different model families. Model diversity is the point. Different models have different blind spots, so a finding two models raise independently is high-confidence signal. The lead sorts everything into `Act on`, `Consider`, `Noted`, and `Dismissed`, with a reason for each dismissal, and applies nothing automatically.
+
+Read the dismissals too. The lead is a pragmatic senior engineer, not an oracle, and you can override it.
+
+## Prototype instead of debating
+
+Never take the first design. Ask for a few, and pick from evidence you can see:
+
+```text
+/poteto-mode prototype a few options for the new dropdown menu. take screenshots or videos for me to compare.
+```
+
+The [Prototype playbook](../../skills/poteto-mode/playbooks/prototype.md) builds throwaway sketches in a scratch directory, puts the variants behind one switcher, drives each one, and captures screenshots or timings. It also works for behavior and algorithms, not just UI. Prototypes are planning with code. They let the agent answer its own open questions by running something instead of asking you, and they leave room for an option you wouldn't have thought of.
+
+The same idea scales up to a real design. Pair `/architect` with prototypes and keep a review gate:
+
+```text
+/poteto-mode we need rate limiting for external webhooks. /architect it first, and answer open questions with prototypes. let me review before proceeding.
+```
+
+Don't spend reviewers on an abstract plan. `/interrogate` belongs on a diff. Point adversarial review at a plan with no code behind it and the reviewers invent theoretical risks and edge cases that will never happen. Let prototypes settle the questions, then review what got built.
+
+## Write the README first for shared code
+
+For a package or API that other code will use, start with the doc a user would read:
+
+```text
+/poteto-mode write a tutorial for how i would use the new config package first. then /teach me why it beats the current one.
+```
+
+Writing the tutorial first forces the caller's view. You describe the API to a hypothetical user and work back to the implementation. The doc also becomes a concrete target the agent checks its own work against. Name [`/technical-writing`](../../skills/technical-writing/SKILL.md) when the doc itself matters, so a tutorial stays a tutorial instead of drifting into reference and explanation at once.
+
+## Plan after the design settles
+
+pstack has no planning skill, on purpose. When you do want a written plan, ask for it once the design is settled:
+
+```text
+/poteto-mode turn this design into a plan. small verifiable PRs, each with its own verification steps.
+```
+
+The [Multi-phase plan playbook](../../skills/poteto-mode/playbooks/multi-phase-plan.md) settles any remaining open questions by prototype, then writes one section per PR, each ending in proof that the change works. A passing test suite alone doesn't count as that proof. The plan is the deliverable. The playbook doesn't implement it, and it names which execution playbook should run it next.
+
+For a migration, state the bar in the prompt:
+
+```text
+/poteto-mode plan the migration of our ui library to the new styling system. small verifiable PRs, each with visual regression checks. the result must match the original exactly, bugs included.
+```
+
+"bugs included" keeps the migration from quietly fixing things on the way, which would make the old and new output impossible to compare. For a project that spans many days, you can commit the plan to the repo for a while so other agents see the work in progress. Delete it when the work lands.
+
+## How much design work does a task deserve?
+
+You might be wondering whether every change needs this. No. Most changes need none of it. A rough ladder:
+
+- A small, finished change you're unsure about needs `/interrogate` alone.
+- A change that crosses function boundaries or moves ownership earns `/architect`, which brings `/arena` with it.
+- A standalone decision where independent attempts would help, like naming, formats, or an algorithm, is `/arena` directly.
+- A coverage matrix, set of parallel checks, or race with declared arms is `/swarm`.
+- An open question you could answer by running something, like a layout, a timing, or an approach, gets a prototype, not a debate.
+- A contested design that's expensive to reverse gets `/architect`, then `/interrogate` before shipping.
+- Work that spans several PRs gets a plan, written after the design settles.
+
+`/poteto-mode` already applies this ladder. Boundary-crossing work triggers `/architect` on its own, so you reach for these directly mainly when you want more or less scrutiny than the default.
+
+Next: [Build and clean the change](./05-build-and-clean.md).