dsh-pstack 0.0.0-stage → 0.1.0

package/assets/skills/why/references/sources/sentry.md

@@ -0,0 +1,66 @@
+# Sentry Error History
+
+## How to search it
+
+Use the Sentry MCP.
+
+1. **Orient.** If you don't know the project slug and organization:
+
+   ```
+   find_organizations
+   find_projects
+   ```
+
+2. **Search for issues related to the target.**
+
+   ```
+   search_issues (natural language, e.g., "errors in PaymentService timeout", "unhandled exceptions in uploadFile")
+   ```
+
+   Build queries from the exception class names the target handles, its function or class name, the error message strings it checks for, and its file path.
+
+3. **Narrow by release and time window.**
+
+   ```
+   search_issue_events (filter by release, time, environment, trace ID, tags)
+   get_issue_tag_values (for an issue, see distribution across versions, users, environments)
+   ```
+
+   For a suspected issue, check **first seen** and **last seen** (does the stop line up with the target's ship date?), the **affected releases** (which saw it, and which was the fix?), and the **frequency trajectory** (did it spike, then get resolved?).
+
+4. **Pull the full event for context.**
+
+   ```
+   get_sentry_resource (pass a Sentry URL or type+ID)
+   ```
+
+   Does the stack trace pass through the target code? Do the tags and breadcrumbs match the conditions the target defends against?
+
+5. **Check releases that landed near the target.**
+
+   ```
+   find_releases (around the commit date of the target)
+   ```
+
+   Cross-reference release version with the PR's merge date.
+
+6. **Use Seer sparingly.**
+
+   ```
+   analyze_issue_with_seer
+   ```
+
+   Seer's AI root-cause analyses are a hypothesis generator. Treat them as inference, not authoritative. The actual events and stack traces are the primary evidence.
+
+## What to return
+
+For each relevant issue:
+- Issue ID and title
+- Project and organization
+- First seen / last seen timestamps
+- Event count (and sampling rate if known)
+- Affected releases
+- A representative stack trace snippet showing relevance to the target (verbatim excerpt, not summary)
+- First/last-seen correlation with the target's ship date
+- Link to the issue
+- Any author comments or resolution notes

package/assets/skills/why/references/sources/slack.md

@@ -0,0 +1,17 @@
+# Slack Conversations
+
+## How to search it
+
+Slack MCP tools vary. Check which Slack MCP is available and inspect its tool schema first. It may require `mcp_auth`. If authentication fails, stop and report the gap.
+
+1. **Author-bounded search.** Messages from the PR author around the PR merge date. Limits scope dramatically and often hits gold.
+3. **PR URL search.** Slack often links PRs when they're reviewed or discussed. Search for the PR URL (or just `/pull/<number>`).
+4. **Error string search.** If the code handles a specific error, search for the error string. Incident threads often surface.
+
+## Common pitfalls
+
+- **Channel archaeology limits.** Very old messages may be gone due to retention policies. If you can't find anything before a certain date, note the retention cliff.
+- **Unsearched DMs.** Many decisions happen in DMs that aren't searchable. You'll miss them. That's a known limitation.
+- **Speculative jokes as "decisions."** Slack is casual. "Lol just do the thing" isn't a decision, even if it preceded the commit. Look for considered discussion.
+- **Context collapse in single messages.** Without the thread, a single message often reads differently than in context. Always fetch threads.
+- **Auth failures.** If the MCP isn't authenticated, stop. Don't make up findings. Report that Slack wasn't searchable.

package/assets/skills/why/references/synthesizer-prompt.md

@@ -0,0 +1,129 @@
+# Synthesizer Prompt Template
+
+Fill in the placeholders.
+
+---
+
+You are answering a "why" question about a piece of code by synthesizing findings from investigators who searched different historical sources (source control, issue / ticket tracker, long-form documents, real-time team chat, infrastructure observability, error / exception tracking, product analytics warehouse, and code comments). Produce a confidence-weighted, evidence-cited narrative that says honestly what the evidence supports, and just as honestly what it doesn't.
+
+## The Question
+
+> {QUESTION}
+
+## The Code Anchor
+
+**Target files:** {FILES_WITH_LINE_RANGES}
+
+**Key symbols:** {SYMBOLS}
+
+## Investigator Findings
+
+{ALL_INVESTIGATOR_FINDINGS}
+
+## Sources That Weren't Searched
+
+{SKIPPED_SOURCES_WITH_REASONS}
+
+## Epistemics Framework
+
+You MUST follow `references/epistemics.md`. Read it in full before writing. The key rules:
+
+1. Every claim must sit in one tier: **Direct**, **Supported**, **Inferred**, **Speculative**, **Unknown**. The tier sets its section and its phrasing.
+2. Every Direct/Supported claim must have a citation (PR #, ticket ID, doc URL, chat permalink, commit hash, or file:line).
+3. Inferred and Speculative claims must use hedged language ("appears to", "likely", "suggests", "one possibility is").
+4. Never cite code as evidence for its own intent.
+5. Document gaps. Don't fill them with plausible-sounding guesses.
+6. Treat a hypothesis embedded in the user's question as a candidate, not a conclusion. Check it independently.
+
+## Instructions
+
+1. **Read all investigator findings** and weigh the evidence yourself. Investigators gathered raw evidence, not conclusions.
+2. **Merge overlaps.** When several investigators cite the same PR, ticket, or doc, give it one authoritative reference.
+3. **Surface contradictions.** When two items disagree, show both. Don't pick one.
+4. **Calibrate each claim.** Find its evidence and tier. Direct: cite it and state it plainly. Inferred: hedge it and show the inference. Speculative: mark it. No evidence: put it in the gaps.
+5. **Verify citations by spot-checking.** If you're uncertain a cited item exists or says what the investigator claims, check it by reading the codebase or calling MCP tools. Don't propagate errors. Do not write files, commit, or modify external state.
+6. **Don't overreach.** The user will act on this. Leave an open question open rather than fill it with a confident guess.
+
+## Output Format
+
+Write for the user, in this exact structure:
+
+---
+
+### The Question
+
+Restate the user's question in one or two sentences.
+
+### The Code in Question
+
+File paths, line ranges, key symbols. Two or three lines to orient a cold reader.
+
+### What We Found
+
+Claims with textual evidence, each quoted or paraphrased and cited precisely:
+
+- **[Direct]** {Claim}. Source: [PR #123](url) / ticket ID / file:line. {Brief quote or paraphrase.}
+- **[Supported]** {Claim}. Evidence: {list of items and what each contributes}.
+
+`[Direct]` is single-source, explicit evidence. `[Supported]` is multiple indirect items converging on a conclusion.
+
+### What We Can Reasonably Infer
+
+Claims stated nowhere but well-supported by indirect evidence. Each bullet must make the inference chain visible ("Given A and B, it's likely that C") and must use hedged language ("appears to", "likely", "suggests", "is consistent with"):
+
+- **[Inferred]** {Hedged claim}. Reasoning: {the specific evidence and the inference step}.
+
+Skip this section if there's nothing to infer.
+
+### Competing Hypotheses
+
+If the evidence fits multiple stories, present each. Don't force a winner the record doesn't support. For each hypothesis:
+
+- **Hypothesis:** {one-sentence statement}
+- **Evidence for:** {specific items}
+- **Evidence against or missing:** {what would need to be true but isn't, or what counter-signals exist}
+
+Skip this section if there's a single clear answer.
+
+### What We Don't Know
+
+Specific gaps: "We searched the issue tracker for [query1], [query2], [query3] and found no issue discussing the rate-limit threshold", not "We don't know why." Include:
+
+- Questions that went unanswered
+- Searches that returned nothing
+- Sources that were unavailable, and why (such as a missing real-time team chat MCP)
+- People who would likely know but whom you can't ask
+
+### Sources Consulted
+
+What was actually searched, so the user can judge coverage and redirect:
+
+- **Source control history**: {file paths}, {number of commits reviewed}, PRs #{numbers}, and code comments searched. Or "Not searched. This should not happen because git and `gh` are always expected."
+- **Issue / ticket tracker**: {ticket IDs and keyword searches}. Or "Not searched. No matching MCP available in this environment."
+- **Long-form documents**: {page titles and search queries}. Or "Not searched. No matching MCP available in this environment."
+- **Real-time team chat**: {channels searched, date ranges, queries}. Or "Not searched. No matching MCP available in this environment."
+- **Infrastructure observability**: {dashboards, monitors, metrics, logs, traces, or incidents searched}. Or "Not searched. No matching MCP available in this environment."
+- **Error / exception tracking**: {issues, events, or releases searched}. Or "Not searched. No matching MCP available in this environment."
+- **Product analytics warehouse**: {fully-qualified tables queried, the time windows, and the numeric summaries (counts, percentiles, first/last-seen timestamps) that bore on the question}. Or "Not searched. No matching MCP available in this environment."
+
+### Confidence Summary
+
+One or two sentences on overall confidence, e.g.:
+
+> "The core rationale (A) is well-supported by direct PR and ticket evidence. The specific threshold value (100) is inferred from the surrounding context but not explicitly documented. The question of whether this was driven by a customer request could not be answered. No relevant issue tracker or long-form doc content surfaced, and real-time team chat search was unavailable."
+
+---
+
+## Quality Check Before Returning
+
+Revise if any item fails:
+
+1. Does every claim in "What We Found" have a citation? If not, add one or move it to "Inferred" or "Hypotheses."
+2. Is the phrasing tier-appropriate? (Direct claims can use "because". Inferred claims cannot.)
+3. Did you surface every contradiction you noticed, or quietly pick one?
+4. Does "What We Don't Know" name specific gaps? If it's empty or missing, be suspicious. Historical investigations almost always have gaps.
+5. Did you check any hypothesis embedded in the question against the evidence rather than rubber-stamp it?
+6. Did you cite code as evidence for its own intent? Remove it. Code is mechanics, not motivation.
+7. Is the tone calibrated? A confident-sounding answer on weak evidence is the exact failure this skill exists to prevent.
+
+The value of this output is its honesty, not its authority. A reader who takes it to the original author, an engineering lead, or a product manager should know what's known, what's inferred, and what's missing, so they can ask the right follow-up questions. Optimize for being useful, not for looking decisive.

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# dsh-pstack bundle patch.
+#
+# Two rows, both installed by this package:
+#   - `pstack` mounts the bundled skill provider. Every pstack skill becomes a
+#     normal DSH skill: model-invocable skills reach the catalog, user-invocable
+#     skills reach the `/` menu.
+#   - `pstack-subagent` mounts the `pstack_subagent` tool, the DSH replacement
+#     for Cursor's `Task` tool. It resolves pstack role lines from
+#     `~/.dsh/pstack-models.md` and delegates through `ctx.subagents`.
+#
+# The `pstack` row requires `ctx.skills`, which `@deepseek-ai/dsh-base` provides.
+# The `pstack-subagent` row requires `ctx.tools` and `ctx.subagents`, also in
+# base-backed profiles. Installing this bundle into a profile that lacks them
+# leaves the rows pending, exactly like any other dependency-driven plugin.
+- insert:
+    - id: pstack
+      name: "dsh-pstack"
+
+    - id: pstack-subagent
+      name: "dsh-pstack/subagent"

package/dist/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 dsh-pstack contributors
+Copyright (c) 2025 Lauren Tan (upstream pstack, https://github.com/cursor/plugins)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/README.md

@@ -0,0 +1,159 @@
+# 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

@@ -0,0 +1,32 @@
+---
+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

@@ -0,0 +1,8 @@
+---
+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

@@ -0,0 +1,64 @@
+# 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).