pstack: inline playbook principle rules, keep leaves as deep references

[poteto]

Trace measurements of which files agents actually open show that an invoked playbook gets read essentially every time, while separately indexed principle leaf files get opened only about half the time. A rule that changes how a playbook's work is done therefore belongs inline at the step where it bites, not behind a pointer the agent may never follow.

• Each poteto-mode playbook now states the principle rules that genuinely change its work as one-or-two-sentence rules at the relevant step, with the inline citations de-linked. One commit per playbook.
• The root skill's principle index shrinks to the two genuinely cross-cutting rules (guard the context window, never block on the human) plus a name-only pointer list. All 21 leaf skills stay as the deep references; the guide and README describe the new shape.
• The how skill degrades gracefully when subagents are unavailable: if explorers can't spawn or a spawned explorer never returns, run the exploration angles yourself sequentially and never end the turn waiting. Agents invoked as subagents often can't be woken by their own children, and observed runs have died waiting on explorers that would never report back.

---

Note

Low Risk
Documentation and agent-instruction changes only; no application runtime code. Behavior shifts are intentional guidance for how agents read and apply principles.

Overview
Principle rules now live in playbooks because agents read playbooks almost every time but opened indexed principle-* leaf skills only about half the time. Each affected playbook states the rules that change its work as short inline text at the step where they apply, with principle-* links removed from those steps. The 21 leaf skills stay as deep references.

poteto-mode root skill is slimmer. The long Principles index with per-principle “when it applies” blurbs is replaced by two cross-cutting rules in full (Guard the Context Window, Never Block on the Human) plus a name-only pointer list. Non-negotiables no longer require naming applied principles in every reply; playbooks are the source of truth at each step. The “any code” trigger inlines domain-modeling guidance instead of pointing at principle-model-the-domain.

Docs and routing align with the model. README, the principles guide, poteto-agent, and references/plan.md describe playbooks as carrying inline rules and leaves as optional depth. how adds a fallback: if explorers cannot spawn or never return, run the exploration angles sequentially and do not end the turn waiting on subagents.

^{Reviewed by Cursor Bugbot for commit 0bbcfb4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[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: Restart state rule dropped inline
  • Step 3 now directs agents to suspect stale persistent state in restart failures and prioritize state validation when clearing state restores behavior.

Or push these changes by commenting:

@cursor push 2eea757e8a

Preview (2eea757e8a)

diff --git a/pstack/skills/poteto-mode/playbooks/bug-fix.md b/pstack/skills/poteto-mode/playbooks/bug-fix.md
--- a/pstack/skills/poteto-mode/playbooks/bug-fix.md
+++ b/pstack/skills/poteto-mode/playbooks/bug-fix.md
@@ -6,7 +6,7 @@
 
 1. Reproduce it yourself on the matching surface via the control skill (Non-negotiables). Don't hand the repro to the user. A debug or instrumentation protocol that says to ask the user does not override this; you drive the instrumented runtime. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. Won't reproduce directly, force it: synthesize the trigger, tighten conditions, or instrument until it fires. A bug you can't reproduce, you can't prove fixed.
 2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with Cursor's `/loop` command. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out; a design grounded on a plausible-but-unconfirmed cause can be unanimously wrong while the real cause sits one subsystem over.
-3. Plan the fix at the root cause, not the symptom. A nil check or guard that silences the crash without explaining it is a symptom fix and does not ship. Check for the pattern, not just the instance: grep for the same shape elsewhere and fix every occurrence. If the fix crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (default `gpt-5.6-sol-max`) with a specific scope; review the diff.
+3. Plan the fix at the root cause, not the symptom. A nil check or guard that silences the crash without explaining it is a symptom fix and does not ship. Check for the pattern, not just the instance: grep for the same shape elsewhere and fix every occurrence. For failures after restart, suspect stale persistent state before code: config files, caches, lock files, and serialized state. If clearing state restores behavior, prioritize state validation as the fix. If the fix crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (default `gpt-5.6-sol-max`) with a specific scope; review the diff.
 4. Verify on the same surface; the original repro now passes. "Inconclusive" or wrong-surface is not a pass; flag it. Unit tests show branch behavior, not bug absence.
 5. Stage the commits so the failing repro lands before the fix in git history; the reviewer watches it go red, then green. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path; skip it when the test would be expensive, integration-heavy, or unclear.
 6. Run **Opening a PR**.

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

^{Reviewed by Cursor Bugbot for commit 0bbcfb4. Configure here.}

[cursor]

Restart state rule dropped inline

Medium Severity · Logic Bug

Step 3 now inlines fix-root-causes planning rules (symptom guards, pattern grep) but omits the leaf skill’s restart-specific guidance to suspect stale persistent state before chasing code changes. The playbook is read every time; the leaf may not be opened.

 

^{Reviewed by Cursor Bugbot for commit 0bbcfb4. Configure here.}