dsh-pstack 0.1.0 → 0.2.0-beta.3

package/assets/skills/show-me-your-work/scripts/log.sh

@@ -1,42 +0,0 @@
-#!/usr/bin/env bash
-# Append a well-formed row to a show-me-your-work decision log (TSV).
-# Usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>
-set -euo pipefail
-
-if [ "$#" -ne 6 ]; then
-	printf 'usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>\n' >&2
-	exit 1
-fi
-
-logfile="$1"
-shift
-
-logdir="$(dirname "$logfile")"
-if [ -n "$logdir" ] && [ "$logdir" != "." ] && [ ! -d "$logdir" ]; then
-	mkdir -p "$logdir"
-fi
-
-# Use `>>` here, never `>`. A network mount can fail this test for a log
-# that exists. Then the cost is one stray header line, not the rows.
-if [ ! -s "$logfile" ]; then
-	printf 'ts\tphase\tdecision\twhy\tevidence\tresult\n' >> "$logfile"
-fi
-
-ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
-# Strip tabs/newlines/CR so cells stay on one line, and prefix any cell
-# whose first char a spreadsheet would parse as a formula (=, +, -, @)
-# with a single quote. The skill expects this log to be read in
-# spreadsheets, so attacker-controlled evidence (PR titles, filenames,
-# generated text) must not become formula execution when a reviewer
-# opens the file.
-clean() {
-	local v
-	v=$(printf '%s' "$1" | tr '\t\n\r' '   ')
-	case "$v" in
-		=*|+*|-*|@*) printf "'%s" "$v" ;;
-		*) printf '%s' "$v" ;;
-	esac
-}
-printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
-	"$ts" "$(clean "$1")" "$(clean "$2")" "$(clean "$3")" "$(clean "$4")" "$(clean "$5")" \
-	>> "$logfile"

package/assets/skills/swarm/SKILL.md

@@ -1,41 +0,0 @@
----
-name: swarm
-description: Fan out N parallel workers, drain them, and return one report. Use for /swarm, 'swarm this', or parallel coverage, races, gauntlets, and exploration.
-disable-model-invocation: true
----
-
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
-# Swarm
-
-## Start
-
-Call `todo_write` with one entry per phase before launching anything.
-
-1. Frame
-2. Fan out
-3. Aggregate
-4. Report
-
-## Phase A: Frame
-
-1. State the done predicate and the artifact or report the swarm must return.
-2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning.
-4. Spawn every worker with `role: "swarm workers"` and `agent: "general"`. The tool resolves the route from `~/.dsh/pstack-models.md`; `inherit-parent` runs on the parent model. For a race, name each arm's role up front.
-5. Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result.
-
-## Phase B: Fan out
-
-Spawn all N workers in one message with `agent: "general"`, the slice or race arm, and `role: "swarm workers"`. Every worker gets its own writable output when it writes.
-
-Every brief stands alone. Include the goal, scope, exact slice or race arm, how to verify, and what to report. Reports use `PASS`, `ISSUES`, or `BLOCKED` with evidence. A worker that can prove a defect reports `ISSUES` and lists every issue it can prove, not only the first.
-
-If a worker drops out, proceed with N-1 and note it.
-
-## Phase C: Aggregate
-
-Read the terminal results. Drop a result that does not record the SHAs and method its brief names, and respawn that worker once. After a second miss, record a gap. A gap does not count as a pass. For coverage, every required slice needs a result. For a race, apply the selection rule declared up front. Use first pass, rank all, or best-of. Do not paste raw worker dumps.
-
-## Phase D: Report
-
-Return one consolidated in-chat report with the table, issue one-liners, gaps or dropouts, and the race rule when used.

package/assets/skills/why/SKILL.md

@@ -1,100 +0,0 @@
----
-name: why
-description: Use for 'why does X work this way', 'why we picked Y', design rationale, regressions, postmortems, or data-backed thresholds. Discovers available MCPs and queries each evidence category (source control, issue tracker, long-form docs, real-time chat, infrastructure observability, error tracking, product analytics warehouse) in parallel, then returns a cited read on decisions and tradeoffs. Use how for runtime behavior.
-disable-model-invocation: true
----
-
-> DSH port of pstack. `pstack_subagent` replaces Cursor's `Task` tool, and `role` replaces Cursor model slugs. Full mapping: `../../docs/harness/dsh.md`.
-
-# Why
-
-Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works. `why` answers what forces led to its shape.
-
-Each spawn below names a `role` for `pstack_subagent`; the tool resolves it from `~/.dsh/pstack-models.md`, and a missing line inherits the parent model.
-
-Every spawn is a `pstack_subagent` call with `agent: "general"`. DSH has no readonly mode; tell each investigator not to write files, and check `git status` afterward. Investigators must not write anything.
-
-## Operating Posture
-
-Operate as a **careful, cautious, and precise investigator**. Be honest about what you know vs what you're inferring. Read `references/epistemics.md` for the full confidence framework and phrasing guide. The synthesizer must follow it.
-
-## Step 1. Understand the Target and the Question
-
-The **target** is usually a chunk of code, a pattern, a feature, or a named design decision. The **question** is usually a design rationale, a tradeoff, a motivating edge case, an external constraint, dead code, or a broad history sweep.
-
-If the target is vague ("why do we do it this way?" with no clear referent), make your best guess from conversation context (open files, recent edits, the current working directory, what was just discussed). State your interpretation briefly so the user can redirect if you're off, then proceed.
-
-## Step 2. Establish the Code Anchor
-
-Before spawning investigators, build the seed context inline: file paths and line ranges, key symbols (functions, classes, constants), the last few commits touching the target, PR numbers from merge commits (pattern `(#1234)` in the subject line), and any linked ticket IDs. Run `git blame -L <start>,<end> <file>` for last-touch commits, `git log --follow -p -- <file>` for full history with patches through renames, `git log --oneline -20 -- <file>` for recent commits with PR numbers visible, and `git log -1 --format=%B <commit>` to extract PR numbers. Then pull the PR bodies and discussion for any substantive commit: `gh pr view <number> --json title,body,author,createdAt,mergedAt,labels,closingIssuesReferences,comments,reviews`. This anchor goes to every investigator and to the synthesizer.
-
-## Step 3. Spawn Parallel Investigators
-
-**Default to the full parallel investigation.** The goal is a complete coverage map, not a minimal one. Document the null, don't skip the search.
-
-### Discovery
-
-Before spawning investigators, list the MCP servers available in this DSH session from the tool catalog and any MCP tools already in context.
-
-Map each available MCP to one evidence category:
-
-1. Source control history
-2. Issue / ticket tracker
-3. Long-form documents
-4. Real-time team chat
-5. Infrastructure observability
-6. Error / exception tracking
-7. Product analytics warehouse
-
-Source control is always available through git and `gh`. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map.
-
-Spawn one investigator per category that has a matching MCP, all in a single message so they run concurrently, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. `role: "why investigators"`.
-
-Each investigator's prompt is `references/investigator-prompt.md` filled in, plus:
-- the category playbook `references/sources/<source>.md` for the selected MCP, adapted from the examples in `references/source-playbook.md`
-- `references/sources/incident-postmortem.md` **if the target code looks defensive** (null checks, retry logic, timeout handling, rate limiting, feature flags, egress guards, OOM handlers)
-- the code anchor and the user's original question
-
-### Investigator roster, one per available evidence category
-
-Each category below is uniquely positioned to surface one shape of "why", shown after "Best at". Use it to know what to expect back, to name a gap when a category returns empty, and, only in the rare provably-irrelevant case, to justify a skip.
-
-1. **Source control** (git history, `gh` for PRs, code comments, tests). Always spawn, the only guaranteed source. Best at *implementation-time rationale captured during review*.
-2. **Issue / ticket tracker** (e.g. Linear, Jira, GitHub Issues, Plane, Shortcut MCP). Best at *the product or business forcing function*. Strongest when the why is external to engineering.
-3. **Long-form documents** (e.g. Notion, Confluence, Google Docs, Coda MCP). Best at *long-form design rationale*, written out before it becomes code.
-4. **Real-time team chat** (e.g. Slack, Discord, Microsoft Teams, Mattermost MCP). Best at *real-time deliberation that never reached a doc*. Especially important when the source control, ticket, and doc paper trail is thin.
-5. **Infrastructure observability** (e.g. Datadog, New Relic, Honeycomb, Grafana, Splunk MCP). Best at *infrastructure and runtime reality that motivated the code*. Strongest when the target reacts to an infra signal (timeouts, retries, rate limits, circuit breakers).
-6. **Error / exception tracking** (e.g. Sentry, Rollbar, Bugsnag, Airbrake MCP). Best at *the specific exceptions and error trajectories that motivated defensive or corrective code*. Strongest for catch blocks, null guards, type checks, retries, and other defenses.
-7. **Product analytics warehouse** (e.g. Databricks, Snowflake, BigQuery, ClickHouse, dbt, Redshift MCP). Best at *product and data reality that shaped the code*. Strongest for flag-gated code, experiment-driven ships, data migrations, and "where did this number come from" questions.
-
-### When to skip an investigator
-
-Only with an **explicit, written justification** that goes in the final Sources Consulted. Two valid reasons:
-
-- **No MCP is available for that category** in this environment. Flag it as a gap, not a choice: "Real-time team chat skipped. No matching MCP available, so the conversational record was not searchable."
-- **The source is provably irrelevant**, not just "probably irrelevant." A high bar: "Error / exception tracking skipped. Target is a build-time script with no runtime code path."
-
-If your scope assessment suggests a single-commit trivial target where the PR description already contains the complete answer, you may answer inline **only after** confirming all seven available category searches would be redundant. Say so explicitly. This should be rare.
-
-## Step 4. Synthesize
-
-Spawn one synthesizer. `role: "why synthesizer"`. It gets:
-1. The investigator findings, including any null results and any categories skipped with justification
-2. The code anchor
-3. The user's original question
-4. The epistemics framework from `references/epistemics.md`
-5. The synthesizer prompt template from `references/synthesizer-prompt.md`
-
-## Step 5. Present
-
-Present the synthesizer's output to the user. You may lightly edit for clarity or add context from the conversation, but **do not rewrite the confidence language**.
-
-## Output Format
-
-The structure is the one in `references/synthesizer-prompt.md`: The Question, The Code in Question, What We Found, What We Can Reasonably Infer, Competing Hypotheses, What We Don't Know, Sources Consulted, Confidence Summary. Adapt as needed, but keep the confidence separation intact, and keep Sources Consulted as one line per investigator, including the ones that returned nothing or were skipped, with the reason.
-
-After Sources Consulted, if the user's `why` question is a precursor to changing this code, convert the lineage findings into a Preserve / Change / Avoid / Risk constraint set for planning the change.
-
-## Common Failure Modes to Avoid
-
-- **Recency bias**. Assuming the most recent commit is authoritative. The current shape is often the accretion of many earlier decisions. Trace back.

package/dist/README.md

@@ -1,159 +0,0 @@
-# dsh-pstack
-
-pstack for DeepSeek Harness. Rigorous agent workflows ported from
-[`cursor/plugins/pstack`](https://github.com/cursor/plugins/tree/main/pstack).
-
-pstack helps you write less, but higher quality code. `/poteto-mode` reads a
-task, picks a playbook, and routes the work through the same skills Lauren Tan
-uses at Cursor: investigation, design, implementation, verification, review,
-shipping. This package ports those skills to DSH and gives them a native
-delegation tool.
-
-Upstream is pinned as a git submodule at `upstream/cursor-plugins`. The DSH
-tree under `assets/` is generated from it, so upstream fixes flow through a
-repeatable sync instead of a hand fork. The generated tree is committed: it is
-what makes a sync reviewable as a `git diff`.
-
-## Install
-
-```bash
-dsh plugin --profile web add github:your-org/dsh-pstack
-```
-
-Or from a checkout:
-
-```bash
-git submodule update --init --depth 1
-dsh plugin --profile web add .
-```
-
-Restart `dsh web` after install. The bundle patch mounts two rows:
-
-- `pstack` registers the bundled skill provider. Every converted skill appears
-  in the session catalog with its Cursor invocation policy preserved:
-  `/poteto-mode` and friends stay user-invocable, and the principles stay
-  model-invocable.
-- `pstack-subagent` registers the `pstack_subagent` tool, the DSH replacement
-  for Cursor's `Task` tool.
-
-Verify the layer without booting:
-
-```bash
-dsh --profile web --dump-config | grep -A2 'pstack'
-```
-
-## Use
-
-Start with a real task:
-
-```text
-/poteto-mode add a --json flag to this command. text output stays byte-identical. verify both.
-```
-
-`/poteto-mode` opens a todo list whose first items are the matched playbook's
-steps. Each step names the skill it routes to. The other skills work directly:
-`/how`, `/why`, `/architect`, `/arena`, `/swarm`, `/interrogate`, `/tdd`,
-`/no-comments`, `/unslop`, `/technical-writing`, `/sharpen`, `/teach`, and the
-twenty-four `principle-*` rules.
-
-See the converted [pstack guide](assets/docs/guide/README.md) and the
-[DSH adapter reference](assets/docs/harness/dsh.md).
-
-### Configure roles
-
-`/setup-pstack` detects the routes your session can use and writes
-`~/.dsh/pstack-models.md`. One role per line:
-
-```text
-# pstack model configuration. One line per role.
-# Value: inherit-parent | <provider>/<model> [effort]
-# budget: large (xhigh)
-feature, refactoring: deepseek-official/deepseek-reasoner high
-judgment and prose: inherit-parent
-```
-
-A missing line means the role inherits the parent chat's route. The tool reads
-this file on every delegation, so edits apply without restarting.
-
-### Delegate
-
-`pstack_subagent` is the one delegation surface:
-
-```text
-pstack_subagent(
-  description: "port the retry helper",
-  prompt: "Port src/retry.ts ... prove it with pnpm test retry",
-  agent: "poteto-agent",
-  role: "feature, refactoring",
-)
-```
-
-- `agent`: `poteto-agent` (default), `general`, or `comment-sicko`. The tool
-  prepends the packaged agent instructions for the first and third.
-- `role`: a line from `~/.dsh/pstack-models.md`. Omit it to inherit the parent
-  route.
-- `cwd`: optional child working directory.
-
-The call returns `started subagent <id>` immediately. The runtime reports the
-final answer in a completion notice. Use `send_message` to steer a running
-child and `list_agents` to enumerate them.
-
-## What changed from Cursor
-
-| Cursor                                                                      | DSH                                                                                                     |
-| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
-| `Task` tool                                                                 | `pstack_subagent`                                                                                       |
-| `subagent_type`                                                             | `agent`                                                                                                 |
-| model slug                                                                  | `role` resolved from `~/.dsh/pstack-models.md`                                                          |
-| `readonly` / `run_in_background` / `environment`                            | Background by default; say "do not edit" in the prompt                                                  |
-| `~/.cursor/rules/pstack-models.mdc`                                         | `~/.dsh/pstack-models.md`                                                                               |
-| `.cursor/skills/`                                                           | `.dsh/skills/`                                                                                          |
-| Automations, Bugbot, cloud agents, Custom Modes, `/loop`, `cursor-team-kit` | Marked skipped, or remapped to `schedule_create`, `create_goal`, worktree subagents, and `/no-comments` |
-
-`skills/make-bot-ui` is not ported: it depends entirely on Cursor Automations.
-It is not shipped, in any form. If you need it, read it from the upstream
-submodule at `upstream/cursor-plugins/pstack/skills/make-bot-ui/`.
-
-## Develop
-
-Requirements: Node 22.19+ and pnpm. Vite+ provides the build, test, lint, and
-format toolchain.
-
-```bash
-vp install          # install dependencies
-git submodule update --init --depth 1
-vp run sync         # regenerate assets/ from upstream pstack
-vp check            # format, lint, type-check
-vp test             # unit tests
-vp pack             # build dist/
-```
-
-### Repository layout
-
-```text
-src/provider.ts          bundled skill provider (ctx.skills)
-src/subagent.ts          pstack_subagent tool (ctx.subagents + ctx.tools)
-src/roles.ts             ~/.dsh/pstack-models.md parsing and role resolution
-src/frontmatter.ts       SKILL.md frontmatter parser
-scripts/adapt.ts         upstream-to-DSH rewrite rules
-scripts/sync-upstream.ts generator: upstream -> assets/
-tests/                   unit tests for provider, roles, and prompt assembly
-assets/                  generated: skills, agents, docs (committed)
-cordis.patch.yml         the bundle layer this package installs
-upstream/cursor-plugins  git submodule, upstream reference only
-```
-
-`assets/` is generated. Never hand-edit it. Change `scripts/adapt.ts` or a
-skill's upstream source, then run `vp run sync`.
-
-[`docs/porting/`](docs/porting/README.md) is the policy the converter enforces:
-translate names, not sentences; awkward grammar is acceptable, changed meaning
-is not. It also records why the generated tree is committed rather than ignored.
-
-`vp run sync:check` fails when the committed tree differs from a fresh
-conversion and when a rewrite no longer matches its upstream anchor. Run it
-before publishing.
-
-## License
-
-MIT. The ported skills are MIT, copyright Lauren Tan; see [LICENSE](LICENSE).

package/dist/assets/agents/comment-sicko.md

@@ -1,32 +0,0 @@
----
-name: comment-sicko
-description: "A deranged comment-hater that savors deletion and condemns workaround code."
----
-
-# 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 from the **how** and **why** skills 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.

package/dist/assets/agents/poteto-agent.md

@@ -1,8 +0,0 @@
----
-name: poteto-agent
-description: "Delegate subagent for code-writing and helper tasks spawned during a `/poteto-mode` run. Use for delegates, not as the runner for `/poteto-mode` itself. Spawn a fresh `poteto-agent` for each new task, and resume one only in the strict cases that poteto-mode's Subagents section names. Reads the `poteto-mode` skill's `SKILL.md` in full before any work, including its inline Principles index. Substituting `agent: \"general\"` skips that read and drifts."
----
-
-# Poteto subagent
-
-You are operating as poteto-mode's full agent style. The chat that receives `/poteto-mode` owns the playbook, the todo list, and every `pstack_subagent` spawn. You are one of its delegates. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Use the absolute path your parent gave you. With no path, before any other work, search `~/.dsh/plugins/` for a file whose path ends in `skills/poteto-mode/SKILL.md`. If more than one file matches, use the copy whose `package.json` has the highest `version`. Your skill catalog hides this skill, so a missing catalog entry does not mean pstack is absent. If no such file exists, stop and tell your parent. Navigate to a leaf `principle-*` skill whenever you apply that principle.

package/dist/assets/docs/guide/01-setup.md

@@ -1,64 +0,0 @@
-# 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
-
-Install the bundle into your DSH profile:
-
-```bash
-dsh plugin --profile web add github:your-org/dsh-pstack
-```
-
-Restart `dsh web` after install. The bundle mounts the pstack skill provider and the `pstack_subagent` tool.
-
-## 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 `~/.dsh/pstack-models.md`, a small rule every pstack skill reads.
-
-The defaults inherit the parent chat route, so they cost nothing extra beyond the children themselves. A real route written as `<provider>/<model> [effort]` pins that role; `unlimited`, `large`, `medium`, and `small` set the effort token on those routes.
-
-You only override what you care about. A role with no line in the rule 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 rule written before the change still pins the old default, so delete those role lines, or delete the file, then run `/setup-pstack` again.
-
-`inherit-parent` means the child runs on the parent chat model. Both `inherit-parent` and `auto` are accepted aliases, and neither is a model slug. For a panel role the value is a comma-separated list, and one subagent runs per entry, so the list length sets the panel size. Setup also configures `swarm workers`, the default route for every `/swarm` worker unless a race names a route for each arm.
-
-## Accept the verification offers, 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 `.dsh/skills/verify-<app>/`, 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.
-
-Then setup offers once to generate a formal verification skill with [`/create-formal-verification-skill`](../../skills/create-formal-verification-skill/SKILL.md), unless the project already has one. Tests check the cases someone thought to write. A formal verification skill checks one key property of your code, such as "a job never runs twice at once", in every case within a stated scope. Say yes when your code has concurrency, retries, a state machine, or a parser, where a bug is costly and tests rarely reach the case that breaks. Otherwise say no, and run it later if that changes. [Verify and ship](./06-verify-and-ship.md#prove-a-property-with-a-formal-verification-skill) covers it.
-
-After setup, start a new chat. The model rule 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. DSH has no persistent custom mode. Start each new task with `/poteto-mode`, and its instructions apply to that turn.
-
-Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).

package/dist/assets/docs/guide/03-understand.md

@@ -1,79 +0,0 @@
-# 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) 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 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 reusing. It turns the explanation into an argument you can test 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).