pstack: add public usage tutorial

[poteto]

Adds a ten-page pstack tutorial in a friendly react.dev-style voice: setup, task routing through poteto-mode, understanding code, design review, building, verification (including the optional setup-time verification skill offer, generation, and maintenance), overnight runs, steering with principle names, personal modes and skill evals, and a recipes page. Example prompts are short, informal, and goal-first, matching how the skills get prompted in practice. Six pages (routing, understanding, design, verification, overnight runs, recipes) each open with an illustration, committed as 1200px JPEGs under docs/guide/images/. Links the guide from the README. Docs only, no version change.

This PR targets main directly. The inherit-parent model changes it previously stacked on landed in main via #163, #165, and #166, so the branch was rebased onto main and the redundant commits dropped.

  

[cursor]

Cursor Bugbot has reviewed your changes using high effort and found 1 potential issue.

Bugbot Autofix prepared a fix for the issue found in the latest run.

• ✅ Fixed: Arena cross-judge omits inherit-parent
  • Phase C now resolves the configured cross-judge pool, prefers a different model family, and omits model for inherit-parent/auto aliases.

Or push these changes by commenting:

@cursor push ecf0430a27

Preview (ecf0430a27)

diff --git a/pstack/.cursor-plugin/plugin.json b/pstack/.cursor-plugin/plugin.json
--- a/pstack/.cursor-plugin/plugin.json
+++ b/pstack/.cursor-plugin/plugin.json
@@ -1,7 +1,7 @@
 {
 	"name": "pstack",
 	"displayName": "pstack",
-	"version": "0.11.5",
+	"version": "0.11.6",
 	"description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.",
 	"author": {
 		"name": "Lauren Tan"

diff --git a/pstack/README.md b/pstack/README.md
--- a/pstack/README.md
+++ b/pstack/README.md
@@ -27,6 +27,8 @@
 
 `inherit-parent` and `auto` keep Auto-plan users on the parent chat model by omitting the Task `model` field.
 
+read the [pstack guide](./docs/guide/README.md) for setup, task routing, verification, and unattended runs.
+
 that's it. the other skills are situational; the mode skill uses them for you as needed. out of the box the mode splits work by model strength: your main agent reasons and reviews, precisely-specified code goes to fast code models (cursor grok 4.5 by default), and prose and judgment go to a thinking model. [`/setup-pstack`](./skills/setup-pstack/SKILL.md) changes any of it.
 
 ## usage

diff --git a/pstack/docs/guide/01-setup.md b/pstack/docs/guide/01-setup.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/01-setup.md
@@ -1,0 +1,56 @@
+# Set up pstack
+
+In this tutorial, you install pstack. You configure its model roles. You then start a task with `/poteto-mode`. The `/setup-pstack` skill writes a rule for new sessions.
+
+## Install the plugin
+
+1. Open a Cursor chat.
+2. Run:
+
+   ```text
+   /add-plugin pstack
+   ```
+
+3. Confirm that Cursor reports the plugin as installed.
+
+## Configure model roles
+
+1. Run [`/setup-pstack`](../../skills/setup-pstack/SKILL.md):
+
+   ```text
+   /setup-pstack
+   ```
+
+2. Review the available models and the role list.
+3. For each role you want to override, choose a model.
+4. Confirm the choices.
+
+The skill writes `~/.cursor/rules/pstack-models.mdc`. A role that is absent from the rule uses the skill's default. If you want to restore a default, delete that role's line.
+
+## Keep Auto-plan on the parent model
+
+If you use Auto-plan, set a role to either `inherit-parent` or `auto`. Both values tell pstack to omit the subagent `model` field. The subagent then inherits the parent chat model.
+
+These values are aliases. They are not model slugs.
+
+For a panel role, each list entry starts one subagent. A list of inherited entries keeps the same panel size. Every subagent uses the parent model.
+
+After setup, start a new Cursor chat. The model rule applies to new sessions.
+
+## Start your first task
+
+Run:
+
+```text
+/poteto-mode add a JSON output option to this command.
+Keep the current text output unchanged.
+Verify both output forms.
+```
+
+The first todo tells `/poteto-mode` to read the Principles section. The next todos come from the matched playbook. For this prompt, `/poteto-mode` should choose the Feature playbook.
+
+You can now write normal follow-up prompts. `/poteto-mode` stays active until you opt out.
+
+If you want to change one role or panel, read the full [`setup-pstack` skill](../../skills/setup-pstack/SKILL.md).
+
+Next: [Route work through `/poteto-mode`](./02-poteto-mode.md).

diff --git a/pstack/docs/guide/02-poteto-mode.md b/pstack/docs/guide/02-poteto-mode.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/02-poteto-mode.md
@@ -1,0 +1,105 @@
+# Route work through `/poteto-mode`
+
+Use `/poteto-mode` for a task with several steps or a result you must verify. Give `/poteto-mode` the task. Give `/poteto-mode` the finish condition. `/poteto-mode` matches a playbook. It copies the playbook steps into the todo list. When a step requires another skill, `/poteto-mode` calls that skill.
+
+## Follow the routing rules
+
+```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. Use the other bundled playbooks for these tasks:
+
+- Improve one metric through repeated attempts.
+- Diagnose a live runtime symptom.
+- Diagnose a saved trace.
+- Build a prototype.
+- Match a visual reference.
+- Write or edit a skill.
+- Test a skill change.
+- Continue an unattended run.
+- Continue a prior session.
+- Pause work.
+- Write a multi-phase plan.
+
+Read the [playbook directory](../../skills/poteto-mode/playbooks/) for the full list.
+
+## Describe the result
+
+State the result instead of listing skills:
+
+```text
+/poteto-mode fix the duplicate notification.
+Reproduce it first.
+The finish condition is one notification after three retries.
+```
+
+The todo list should contain the Bug fix steps. `/poteto-mode` keeps each skipped step and adds `skip: <reason>`.
+
+If the task is already clear from the conversation, short prompts work:
+
+```text
+/poteto-mode do it
+```
+
+If the prior messages state the task and finish condition, send this plain follow-up:
+
+```text
+continue
+```
+
+## Match a new playbook when the task changes
+
+If you switch tasks in the same chat, say:
+
+```text
+/poteto-mode new task.
+Investigate why the cache entry survives logout.
+Do not change code.
+```
+
+`new task` is a plain prompt phrase. It tells `/poteto-mode` to match the new request to a playbook. The read-only request should select Investigation instead of continuing the prior build playbook.
+
+## Use a separate worktree
+
+If another agent uses the repository, ask for an isolated worktree:
+
+```text
+/poteto-mode new task.
+Create a branch from <base>.
+Create a separate worktree for that branch.
+Implement the parser change in that worktree.
+```
+
+A separate branch and worktree keep this task's files and commits apart from other work. The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) defines the branch, commit, and PR flow for code changes.
+
+## Set a finish condition before you leave
+
+State a checkable finish condition before you leave:
+
+```text
+/poteto-mode I am stepping away.
+Keep working until the migration check reports zero old callers.
+Log each decision for review.
+```
+
+When you leave work for later review, `/poteto-mode` uses `/figure-it-out`. `/figure-it-out` invokes `/show-me-your-work` to record decisions. If no bundled playbook fits, `/poteto-mode` also uses `/figure-it-out`.
+
+Read [`poteto-mode`](../../skills/poteto-mode/SKILL.md) for the routing rules. If you want the full unattended workflow, read [Run work while you are away](./07-overnight.md).
+
+Next: [Understand the code](./03-understand.md).

diff --git a/pstack/docs/guide/03-understand.md b/pstack/docs/guide/03-understand.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/03-understand.md
@@ -1,0 +1,89 @@
+# Understand the code before changing it
+
+Before you edit unfamiliar code, use pstack to build an up-to-date explanation with sources. Use `/how` to trace behavior. Use `/why` to find past reasons. Use `/teach` to combine both.
+
+## Trace the code path with `/how`
+
+Run:
+
+```text
+/how trace what happens from the CLI command to the final database write.
+Name the owning modules and the error path.
+```
+
+[`/how`](../../skills/how/SKILL.md) reads the code and returns the runtime flow, key types, file map, and non-obvious behavior. For a large subsystem, `/how` starts two to four read-only explorers. It then starts one explainer. For a small question, `/how` starts one explainer directly.
+
+If you also want an architecture review, ask for Critique mode:
+
+```text
+/how explain the sync service.
+Then critique its ownership boundaries.
+```
+
+The critique follows the explanation. This order keeps review comments tied to the real design.
+
+## Find past reasons with `/why`
+
+Run:
+
+```text
+/why was this retry limit set to five?
+Which constraints still apply?
+```
+
+[`/why`](../../skills/why/SKILL.md) starts from source control. It also searches the evidence categories your connectors expose. These categories can include tickets, long-form documents, team discussions, runtime signals, error records, and product data.
+
+The report separates direct evidence from inference. When the evidence supports several explanations, the report lists each one. The report also lists missing evidence and every source category searched.
+
+Use both skills when mechanics and history matter:
+
+```text
+/how explain how request retries work now.
+/why explain why the retry policy has this shape and which assumptions may be stale.
+```
+
+## Combine behavior and history with `/teach`
+
+Run:
+
+```text
+/teach me how this PR changes retries.
+Explain why this design was chosen.
+Tell me what I should verify as a reviewer.
+```
+
+For a subsystem, [`/teach`](../../skills/teach/SKILL.md) runs `/how` and `/why` in parallel. For a small change, `/teach` may run only one. It combines the findings in plain language.
+
+Ask the explanation to test the design argument:
+
+```text
+/teach me how this change works. Convince me that it fixes the cause instead of hiding the symptom.
+```
+
+## Resume one run with the Session pickup playbook
+
+If you take over a prior run, give `/poteto-mode` the prior transcript, a cloud-agent URL, or the pushed branch:
+
+```text
+/poteto-mode take over this branch with the Session pickup playbook.
+Read the prior work record.
+Identify completed work.
+Continue from the first unfinished step.
+```
+
+The [Session pickup playbook](../../skills/poteto-mode/playbooks/session-pickup.md) reconstructs the branch, decisions, and open work. It does not repeat completed investigation. It verifies inherited claims against the original goal before it reports the outcome.
+
+## Investigate a topic across runs
+
+If the topic spans several sessions, start a new Investigation:
+
+```text
+/poteto-mode investigate the current state of request retries.
+Use /how to trace the retry code path.
+Use /why to find the decisions that still constrain the retry policy.
+Do not change code.
+```
+
+Add the branch names, PR links, or document links that define your scope. The connectors can search only the evidence they expose.
+
+Next: [Design the change](./04-design.md).

diff --git a/pstack/docs/guide/04-design.md b/pstack/docs/guide/04-design.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/04-design.md
@@ -1,0 +1,77 @@
+# Design before you write code
+
+When a design would be costly to reverse, start with `/architect`. `/architect` already runs `/arena`. If you want several attempts at another artifact, run `/arena` directly. Before you ship a contested design, run `/interrogate`.
+
+## Sketch the contract with `/architect`
+
+Run:
+
+```text
+/architect design the import pipeline.
+Do not write code yet.
+Show the caller usage, types, function signatures, and module ownership.
+```
+
+When code already exists, [`/architect`](../../skills/architect/SKILL.md) runs `/how` first. If the design changes ownership or layers, `/architect` also runs `/why`. `/architect` then runs `/arena` to compare complete candidate designs.
+
+The synthesized design starts with caller usage. It includes types, signatures, a module map, and a synthesis decision.
+
+If you want to review the synthesized design before implementation, ask for a checkpoint:
+
+```text
+/architect with checkpoint.
+Stop after the synthesized design.
+Wait for my review.
+```
+
+Without that request, `/architect` proceeds from the synthesized design into implementation.
+
+## Compare alternatives with `/arena`
+
+Use `/arena` directly when you want several attempts at the same artifact:
+
+```text
+/arena compare candidate designs for the cache key format.
+Keep each candidate output separate.
+Judge each design on migration safety, lookup cost, and reader load.
+```
+
+```mermaid
+flowchart LR
+    A[One task] --> B[Configured panel]
+    B --> C[Candidate design 1]
+    B --> D[Candidate design 2]
+    B --> E[Candidate design N]
+    C --> F[Cross-judge]
+    D --> F
+    E --> F
+    F --> G[Pick a base]
+    G --> H[Add useful parts]
+    H --> I[Verify the synthesized design]
+```
+
+[`/arena`](../../skills/arena/SKILL.md) writes each candidate design to a separate path. A read-only judge scores every candidate design. The coordinating agent reads each design and chooses a base. It adds selected parts from other designs. It records each rejection. It then verifies the synthesized design.
+
+Your [`setup-pstack` configuration](../../skills/setup-pstack/SKILL.md) controls the panel. The guide does not assume a specific model.
+
+## Challenge the result with `/interrogate`
+
+Run:
+
+```text
+/interrogate review this branch against the stated intent.
+Do not change files.
+If a style comment does not expose a maintenance risk, ignore it.
+```
+
+[`/interrogate`](../../skills/interrogate/SKILL.md) sends the same intent, diff, and rubric to the configured review panel. It returns one verdict with `Act on`, `Consider`, `Noted`, and `Dismissed` findings. It does not apply fixes.
+
+Review the `Act on` findings. Check the dismissed findings too. The lead explains each dismissal. You can override a dismissal.
+
+## Choose the amount of design work
+
+For a small finished change, use `/interrogate` alone. When function boundaries or module ownership change, use `/architect`. If several independent answers would improve a separate decision, run `/arena` directly. Before you ship a contested design that would be costly to reverse, run `/interrogate`.
+
+Most changes do not need the full sequence.
+
+Next: [Build and clean the change](./05-build-and-clean.md).

diff --git a/pstack/docs/guide/05-build-and-clean.md b/pstack/docs/guide/05-build-and-clean.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/05-build-and-clean.md
@@ -1,0 +1,61 @@
+# Build the change and clean the diff
+
+Tell `/poteto-mode` the task type. State the finish condition. Name the evidence you expect. `/poteto-mode` chooses the matched playbook and cleans the diff before each commit.
+
+## Choose the build playbook
+
+Use these prompts as starting points:
+
+| Playbook | Prompt | Result to expect |
+|---|---|---|
+| [Bug fix](../../skills/poteto-mode/playbooks/bug-fix.md) | `/poteto-mode this command emits two records after a retry. Reproduce the failure. Find the cause. Fix the cause. Rerun the same command.` | A failing reproduction, a confirmed cause, the smallest supported fix, and a passing reproduction. |
+| [Feature](../../skills/poteto-mode/playbooks/feature.md) | `/poteto-mode add a --json option. Keep text output unchanged. Define the data shape before implementation. Verify both output forms.` | A grounded design, a named data shape, an implementation diff, and real output from both forms. |
+| [Refactoring](../../skills/poteto-mode/playbooks/refactoring.md) | `/poteto-mode move parsing into one module without changing behavior. Record the current output first. After each step, prove that the output is unchanged.` | A behavior pin, small structural commits, and old-versus-new output proof. |
+| [Perf issue](../../skills/poteto-mode/playbooks/perf-issue.md) | `/poteto-mode startup takes 1.8 seconds on this fixture. Capture a baseline profile. Fix the measured cause. Report the before and after values.` | A baseline artifact, a trace-backed change, a post-change artifact, and a measured difference. |
+
+When you want repeated attempts against one metric, use the [Hillclimb playbook](../../skills/poteto-mode/playbooks/hillclimb.md). Set a target and a minimum attempt count. Give Hillclimb a fixed measurement command. Name the regression check.
+
+## When the test path is cheap, use TDD
+
+Run:
+
+```text
+/tdd add a regression test for the duplicate record.
+Run the test before the fix.
+Show the expected failure.
+Fix the bug.
+Rerun the test.
+```
+
+[`/tdd`](../../skills/tdd/SKILL.md) writes the smallest useful failing test before the production fix. It reruns the same test after the fix. When the change has wider risk, `/tdd` runs nearby checks.
+
+If a test needs broad setup or brittle mocks, use the closest executable check. State why you skipped the test. A focused script or real command can provide stronger evidence than a test that copies implementation details.
+
+## Let TypeScript rules load on their own
+
+[`typescript-best-practices`](../../skills/typescript-best-practices/SKILL.md) loads when the agent reads or edits a `.ts` or `.tsx` file. You do not need a slash command.
+
+The skill turns the type system and boundary principles into concrete TypeScript rules. It favors discriminated unions, boundary validation, `unknown` for external data, exhaustive variants, and schema-derived types.
+
+## Clean the diff before each commit
+
+The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) calls `/deslop` before each commit. pstack does not bundle `/deslop`.
+
+1. If your environment exposes `/deslop`, run it on the diff.
+2. If `/deslop` is unavailable, ask `/poteto-mode` to remove needless comments, unsupported guards, dead compatibility paths, and unrelated edits.
+3. Apply [`/unslop`](../../skills/unslop/SKILL.md) to documentation, commit text, and the PR description.
+4. Inspect the diff.
+5. Run the repository checks.
+
+Use a direct prompt when a prose file still needs work:
+
+```text
+/unslop pstack/docs/guide/05-build-and-clean.md.
+Cut filler.
+Remove repeated claims.
+Keep the commands and evidence.
+```
+
+`/poteto-mode` applies `/unslop` to its replies. To rewrite a prose file, invoke `/unslop` with the file path.
+
+Next: [Verify and ship](./06-verify-and-ship.md).

diff --git a/pstack/docs/guide/06-verify-and-ship.md b/pstack/docs/guide/06-verify-and-ship.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/06-verify-and-ship.md
@@ -1,0 +1,64 @@
+# Verify the result and open a PR
+
+Before `/poteto-mode` reports success, define the finish condition. Ask `/poteto-mode` to run the real command or flow. If the change writes data, inspect the stored value.
+
+## Define the finish condition
+
+Write the finish condition in the first prompt:
+
+```text
+/poteto-mode add JSON output to this command.
+Use this finish condition:
+- The text output remains byte-for-byte unchanged.
+- The JSON output parses.
+- Both forms run against the sample project.
+```
+
+`/poteto-mode` can now check each part of the finish condition.
+
+## Prove behavior on the real artifact
+
+The [Prove It Works principle](../../skills/principle-prove-it-works/SKILL.md) rejects proxy evidence when the real artifact is available.
+
+Choose the check that matches the change:
+
+- For a CLI change, run the real command.
+- For a UI change, complete the changed flow in the running app.
+- For a parser or migration, replay a saved input.
+- For a performance change, compare the before and after profiles.
+- For a storage change, read back the written value.
+
+A build or type check still matters. It does not prove user behavior on its own.
+
+Ask for the evidence in the reply:
+
+```text
+Show the exact command, output, and artifact path that prove the finish condition.
+If a check is inconclusive, mark it as inconclusive.
+```
+
+## Open the PR through the playbook
+
+When verification passes, run:
+
+```text
+/poteto-mode open the PR with the Opening a PR playbook.
+Keep the commits small and ordered.
+Clean the diff before each commit.
+Put the verification evidence in the PR.
+```
+
+The [Opening a PR playbook](../../skills/poteto-mode/playbooks/opening-a-pr.md) defines the worktree, commit, cleanup, and PR steps. Expect a focused diff, ordered commits, unslopped prose, and a PR link.
+
+After the PR opens, use Cursor's built-in PR tools to watch CI. Use the same tools to process review comments. Before you change code, judge each comment against the task intent.
+
+## Replace tools that pstack does not include
+
+> [!NOTE]
+> **What pstack does not include**
+>
+> pstack does not include PR monitoring, stacked PR management, or app-specific UI control. Use Cursor's built-in PR tools for CI and review follow-up. Use your project's verification path to prove behavior.
+
+If pstack does not include a tool, do not skip the step. Use a check that your repository or runtime supports.
+
+Next: [Run work while you are away](./07-overnight.md).

diff --git a/pstack/docs/guide/07-overnight.md b/pstack/docs/guide/07-overnight.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/07-overnight.md
@@ -1,0 +1,85 @@
+# Run work while you are away
+
+Turn a long task into an unattended run with a checkable finish condition. Keep the work isolated. Record each decision. When you step away, use `/figure-it-out` even if the task follows a known playbook. Use the Autonomous run playbook to repeat each check.
+
+## Define the unattended run
+
+Before you leave, give `/poteto-mode` six inputs:
+
+1. State the exact finish condition.
+2. Request an isolated worktree from the named base branch.
+3. State which writes the agent may make.
+4. Name the verification command or artifact.
+5. Request a `/show-me-your-work` decision log.
+6. Give a stop condition for a genuine dead end.
+
+Use a prompt like this:
+
+```text
+/poteto-mode I am stepping away.
+Use <base> as the base branch.
+Create an isolated worktree.
+Migrate every caller to the new parser in that worktree.
+Use this finish condition:
+- No caller uses the old API.
+- All parser fixtures pass.
+- The old API no longer exists.
+Before editing, use /figure-it-out to design the phases.
+Keep a /show-me-your-work decision log.
+Add evidence for each decision or checkpoint.
+Until the finish condition passes, keep the run active with Cursor's /loop.
+If no viable approach remains, stop.
+Record the evidence.
+```
+
+Before writing code, `/figure-it-out` writes the workflow. The workflow expresses the finish condition as a check that every iteration can run.
+
+## Follow the unattended loop
+
+```mermaid
+flowchart TD
+    A[Define the finish condition] --> B[Make the smallest supported change]
+    B --> C[Check the real artifact]
+    C --> D{Did the change make progress}
+    D -->|No| E[Discard the change]
+    D -->|Yes| F[Commit the change]
+    E --> G[Append one decision log row]
+    F --> G
+    G --> H{Finish condition met}
+    H -->|No| B
+    H -->|Yes| I[Review the decision log and report]
+```
+
+The [Autonomous run playbook](../../skills/poteto-mode/playbooks/autonomous-run.md) uses Cursor's `/loop` command to wake the run for a later check. `/loop` is a Cursor command, not a pstack skill.
+
+Each iteration follows this sequence:
+
+1. Make one evidence-backed change.
+2. Check the finish condition.
+3. If the change made progress, commit it.
+4. If the change did not help, discard it.
+5. Append one row to the decision log.
+
+## Use `/figure-it-out` before unattended work
+
+When you will review work after stepping away, use [`/figure-it-out`](../../skills/figure-it-out/SKILL.md). Use it also for large migrations, cross-cutting work, or tasks with no matched playbook. It writes a phased workflow with a baseline, isolated work, explicit verdicts, and final verification.
+
+Run `/figure-it-out` once for the unattended run. After the workflow settles the main design, do not run another design comparison. If new evidence invalidates the design, compare the designs again.
+
+## Keep a reviewable decision log
+
+[`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) writes one append-only TSV row for each decision or checkpoint. Each row records the time, phase, decision, reason, evidence pointer, and result. The default path is `decisions.tsv` or `.audit/<task-slug>.tsv`.
+
+For routine work, keep the decision log local. When a reviewer needs the decision log for a large change, commit it.
+
+When you return, run:
+
+```text
+/show-me-your-work summarize the unattended run.
+Compare the decision log with the transcript.
+Flag weak evidence.
+```
+
+Before `/show-me-your-work` reports the run, it asks a different model family to review the decision log. The final report states the finish condition, iteration count, and final result. It lists accepted changes, discarded changes, open work, and review flags.
+
+Next: [Understand the principles](./08-principles.md).

diff --git a/pstack/docs/guide/08-principles.md b/pstack/docs/guide/08-principles.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/08-principles.md
@@ -1,0 +1,81 @@
+# The principles change work decisions
+
+pstack has 21 principle skills. A playbook defines the steps for a task. The principles change the decisions inside those steps.
+
+For every multi-step task, `/poteto-mode` puts "read the Principles section in full" first in the todo list. For each principle the agent applies, the agent reads the full skill. In the final reply, the agent names each applied principle and the decision it changed.
+
+You do not need to invoke all 21 principles. Their names give you a precise way to redirect the work.
+
+## Core principles set scope and design choices
+
+The nine core principles decide how much to build and when to reconsider the design:
+
+- [Laziness Protocol](../../skills/principle-laziness-protocol/SKILL.md) prefers deletion and the smallest change that solves the problem.
+- [Foundational Thinking](../../skills/principle-foundational-thinking/SKILL.md) chooses the core data structures before logic.
+- [Redesign from First Principles](../../skills/principle-redesign-from-first-principles/SKILL.md) treats a new requirement as a base assumption.
+- [Subtract Before You Add](../../skills/principle-subtract-before-you-add/SKILL.md) removes unused or redundant code before adding structure.
+- [Minimize Reader Load](../../skills/principle-minimize-reader-load/SKILL.md) reduces layers, hidden state, and needless indirection.
+- [Outcome-Oriented Execution](../../skills/principle-outcome-oriented-execution/SKILL.md) moves planned rewrites toward the target design. It avoids code that only keeps intermediate phases compatible.
+- [Experience First](../../skills/principle-experience-first/SKILL.md) favors the user result over implementation convenience.
+- [Exhaust the Design Space](../../skills/principle-exhaust-the-design-space/SKILL.md) builds two or three competing prototypes when a new design has no codebase precedent.
+- [Build the Lever](../../skills/principle-build-the-lever/SKILL.md) creates the smallest script, generator, check, or shared skill that performs or proves nontrivial work.
+
+## Architecture principles set code structure
+
+The six architecture principles decide where state, validation, and compatibility belong:
+
+- [Model the Domain](../../skills/principle-model-the-domain/SKILL.md) encodes repeated rules in one data structure.
+- [Boundary Discipline](../../skills/principle-boundary-discipline/SKILL.md) validates external data at the boundary and trusts internal types.
+- [Type System Discipline](../../skills/principle-type-system-discipline/SKILL.md) makes invalid states hard to represent.
+- [Make Operations Idempotent](../../skills/principle-make-operations-idempotent/SKILL.md) makes retries converge on the same result.
+- [Migrate Callers Then Delete Legacy APIs](../../skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md) migrates every caller and removes the old API in the same refactor.
+- [Separate Before Serializing Shared State](../../skills/principle-separate-before-serializing-shared-state/SKILL.md) removes shared writes before adding coordination.
+
+## Verification principles define proof
+
+The three verification principles require evidence:
+
+- [Prove It Works](../../skills/principle-prove-it-works/SKILL.md) checks the real artifact before `/poteto-mode` reports success.
+- [Fix Root Causes](../../skills/principle-fix-root-causes/SKILL.md) confirms the failure mechanism before the agent changes code.
+- [Sequence Work into Verifiable Units](../../skills/principle-sequence-verifiable-units/SKILL.md) finishes and checks one small unit before the next.
+
+## Delegation principles protect context and progress
+
+The two delegation principles control parallel work:
+
+- [Guard the Context Window](../../skills/principle-guard-the-context-window/SKILL.md) sends large reads to subagents and keeps short findings in the main chat.
+- [Never Block on the Human](../../skills/principle-never-block-on-the-human/SKILL.md) keeps reversible work moving without a permission pause.
+
+## The meta principle turns repeated advice into checks
+
+[Encode Lessons in Structure](../../skills/principle-encode-lessons-in-structure/SKILL.md) replaces repeated prose instructions with a lint rule, check, script, or metadata field.
+
+## A principle name changes the next decision
+
+A principle name is a direct instruction. This prompt asks the agent to remove old structure before editing:
+
+```text
+Use Subtract Before You Add.
+1. Delete the obsolete adapters.
+2. Design the remaining path.
+```
+
+This prompt rejects a compile-only success claim:
+
+```text
+Apply Prove It Works.
+1. Run the real import flow.
+2. Show the written records.
+3. After both checks pass, report success.
+```
+
+This prompt keeps parallel agents isolated:
+
+```text
+Apply Separate Before Serializing Shared State.
+Give each attempt its own worktree instead of adding a lock.
+```
+
+The name works because it points to a complete rule. The agent still has to state which decision the rule changed.
+
+Next: [Create and test your own pstack skills](./09-make-it-yours.md).

diff --git a/pstack/docs/guide/09-make-it-yours.md b/pstack/docs/guide/09-make-it-yours.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/09-make-it-yours.md
@@ -1,0 +1,72 @@
+# Create and test your own pstack skills
+
+You create a personal mode from your work. You turn one repeated correction into a skill change. You test the change before you adopt it.
+
+## 1. Create a personal mode
+
+Run:
+
+```text
+/automate-me create a <handle>-mode skill from how I work in this project.
+```
+
+[`/automate-me`](../../skills/automate-me/SKILL.md) reads transcripts from the active workspace. It looks for repeated response, delegation, verification, code, prose, and process preferences. It then asks you which patterns matter.
+
+The skill drafts `.cursor/skills/<handle>-mode/SKILL.md` through Cursor's built-in skill creator, `create-skill`. `/automate-me` applies the [`unslop` skill](../../skills/unslop/SKILL.md). It then shows you the draft. After you approve the draft, `/automate-me` opens a PR from a worktree.
+
+When your preferences change, run `/automate-me` again:
+
+```text
+/automate-me update my <handle>-mode skill with the work since its last edit.
+```
+
+The update keeps rules that new evidence did not contradict. It adds a rule only when the pattern repeats.
+
+## 2. Reflect on one completed session
+
+Run:
+
+```text
+/reflect
+```
+
+[`/reflect`](../../skills/reflect/SKILL.md) sends the current transcript to three reviewers. A synthesizer groups the results as `Accepted`, `Rejected`, or `Backlog`.
+
+Before you edit a skill, review the proposals. Approve only rules that will change a future decision. One unusual session is not enough evidence for a permanent rule.
+
+## 3. Author one focused skill
+
+If you already know the workflow to capture, run:
+
+```text
+/poteto-mode write a skill for verifying database migrations.
+Use the Authoring or modifying a skill playbook.
+```
+
+The [Authoring or modifying a skill playbook](../../skills/poteto-mode/playbooks/authoring-a-skill.md) uses Cursor's built-in `create-skill` flow. It validates frontmatter, referenced files, and cross-skill links. It adds tests for structural rules. It skips tests for subjective rules. It then uses the Opening a PR playbook.
+
+Use `create-skill` because that is the authoring flow named in the current pstack playbook. Do not write a `SKILL.md` from memory.
+
+## 4. Test the skill change without revealing the comparison
+
+Before you replace a skill rule, ask `/poteto-mode` to run the Eval playbook:
+
+```text
+/poteto-mode run the Eval playbook for this skill change.
+Use the same natural task for the current and proposed forms.
+Do not reveal the comparison to the workers.
+```
+
+The [Eval playbook](../../skills/poteto-mode/playbooks/eval.md) creates isolated directories with ordinary project names. Each worker receives the same user-style prompt without the hidden scoring criteria. One judge reviews all outputs under neutral labels.
+
+Expect these artifacts:
+
+- A short success rubric that workers never see.
+- One isolated output per worker.
+- Workspace-scoped transcripts that show which files each worker read.
+- One judge verdict across all outputs.
+- A recommendation to keep or reject the skill change.
+
+Before you accept the judge's result, read every output. If your judgment differs, check for an unclear rubric or judge bias before you decide.
+
+Next: [Use pstack recipes and avoid common mistakes](./10-recipes-and-pitfalls.md).

diff --git a/pstack/docs/guide/10-recipes-and-pitfalls.md b/pstack/docs/guide/10-recipes-and-pitfalls.md
new file mode 100644
--- /dev/null
+++ b/pstack/docs/guide/10-recipes-and-pitfalls.md
@@ -1,0 +1,84 @@
+# Use pstack recipes and avoid common mistakes
+
+When you need a known workflow, copy one recipe. Add concrete paths from your project. Add a finish condition and a verification command.
+
+## Understand an unfamiliar subsystem
+
+```text
+/how trace the request from the public API to storage.
+Name the owning modules and failure path.
+/why explain why these boundaries exist.
+Name the constraints that still apply.
+```
+
+Use `/how` for current mechanics. Use `/why` for the evidence behind the design.
+
+## Learn enough to review a PR
+
+```text
+/teach me how this PR works.
+Explain why this design was chosen.
+Name the evidence that would disprove the main assumption.
+```
+
+When you want one combined explanation, use `/teach`.
+
... diff truncated: showing 800 of 917 lines

_{You can send follow-ups to the cloud agent here.}

^{Reviewed by Cursor Bugbot for commit 65ab5e6. Configure here.}