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

pstack/README.md

@@ -177,7 +177,7 @@ pstack also ships a subagent that runs my style end to end. spawn it from a pare
 
 ## principles
 
-twenty-one short skills, one principle each. `poteto-mode` indexes them inline and reads that index at task start. the standalone files are there so other skills can reference a principle by name, and so the index can point at the full rule for each.
+twenty-one short skills, one principle each. the playbooks carry each rule inline at the step where it applies, and `poteto-mode` keeps a pointer index read at task start. the standalone files are the deep references: other skills point at a principle by name, and the index points at the full rule for each.
 
 <details>
 <summary>all twenty-one principles</summary>

pstack/agents/poteto-agent.md

@@ -5,4 +5,4 @@ description: Routing target for `/poteto-mode` and any request for poteto's styl
 
 # Poteto subagent
 
-You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. Navigate to a leaf `principle-*` skill whenever you apply that principle.
+You are operating as poteto-mode's full agent style. Read the `poteto-mode` skill's `SKILL.md` in full before doing any work, including its inline Principles index. The playbooks carry each principle's rule inline at the step where it applies; open a leaf `principle-*` skill only when you need the full treatment.

pstack/docs/guide/08-principles.md

@@ -1,6 +1,6 @@
 # Steer with principle names
 
-pstack ships 21 principles as individual skills. `/poteto-mode` reads their index at the start of every multi-step task, applies the ones the task triggers, and names each applied principle in its reply along with the decision it changed.
+pstack ships 21 principles as individual skills. Each playbook carries the rules that matter for its work inline, at the step where they apply, and the root skill keeps the cross-cutting rules plus a pointer index it reads at the start of every multi-step task. The leaf skills are the deep references.
 
 You don't invoke principles. You use their names to steer. Each name points at a complete rule the agent has already read, so one phrase redirects the work more precisely than a paragraph of instructions.
 
@@ -24,7 +24,7 @@ Say two parallel attempts are about to write to the same branch:
 separate before serializing shared state. give each attempt its own worktree, no locks.
 ```
 
-Each phrase lands because the rule behind it is specific. The agent still has to say, in its reply, which decision the rule changed. A principle citation with no decision behind it is the tell that it name-dropped instead of applying.
+Each phrase lands because the rule behind it is specific. Naming one sends the agent to the leaf skill for the full treatment, not just the inline sentence it already met in the playbook.
 
 ## The 21, briefly
 

pstack/skills/how/SKILL.md

@@ -32,6 +32,8 @@ Identify the scope. If ambiguous, state your best-guess interpretation before ex
 
 When in doubt, lean simple. You can always spawn explorers if the explainer hits a wall.
 
+If you cannot spawn subagents, or a spawned explorer never returns, run the exploration angles yourself sequentially and keep going. The angles are the point, not the parallelism. Never end your turn waiting on explorers.
+
 ### Step 2a. Explore (complex questions only)
 
 Decompose the question into 2-4 parallel exploration angles, each a distinct slice of the subsystem so explorers don't duplicate work. Example split for "how does the rate limiter work?":

pstack/skills/poteto-mode/SKILL.md

@@ -12,13 +12,13 @@ reminder: New task? Playbook match or rigor needed -> apply /poteto-mode. Casual
 
 ## Non-negotiables
 
-**Start every multi-step task with a todolist whose first item is to read the Principles section below in full.** The principles ground every trigger here. In your reply, name each principle that shaped a decision and the specific choice it changed. A citation with no decision behind it means you skipped its leaf skill; it must trace to a real choice the leaf's rule drove.
+**Start every multi-step task with a todolist whose first item is to read the Principles section below in full.** The principles ground every trigger here. Each playbook carries the principle rules for its work inline, at the step where they apply; follow the rule where you meet it. Do not list principles in the reply unless asked.
 
 Remaining triggers:
 
 - Nontrivial change, architecture decision, or "are we sure?" → the **how** skill.
 - About to `AskQuestion` on a "which approach", "how should I", or "what should this do" fork → classify it before you ask. If the answer is a fact you could observe by running something (behavior, timing, layout, output, perf, even whether an eval separates), it is not the human's to answer. Sketch it via the Prototype playbook (`playbooks/prototype.md`) and let the result decide. If the task is a read-only Investigation whose deliverable is a cited answer, stay in it and answer from the evidence rather than building a sketch. Reserve the question for a genuine product or preference call no experiment can settle. The ask is the slow path. A throwaway probe usually answers faster, and it hands the human a result to react to instead of a decision to make.
-- Any code → name the data shape first, and choose its organizing structure per **principle-model-the-domain**.
+- Any code → name the data shape first, and choose its organizing structure before writing logic: a state machine over scattered booleans, a table or registry over spread-out branching, a typed model over repeated shape assumptions. Boring code stays when the shape is already clear and local.
 - Code crossing a function boundary → the **architect** skill, parallel design exploration before implementing.
 - Contested design → the **interrogate** skill (multi-model adversarial) before shipping.
 - Nontrivial multi-step → write the throughput checkpoint (Feature step 3).
@@ -32,43 +32,32 @@ Remaining triggers:
 
 ## Principles
 
-Read the leaf skill in full for any principle you apply. Each entry names when it applies.
-
-**Core**
-
-- **Laziness Protocol** (**principle-laziness-protocol**). Refactoring, sizing a diff, or tempted to add abstractions, layers, or signal threading. Bias to deletion and the smallest change that solves the problem.
-- **Foundational Thinking** (**principle-foundational-thinking**). Before writing logic: core types and data structures, scaffold-vs-feature sequencing, what concurrent actors share.
-- **Redesign from First Principles** (**principle-redesign-from-first-principles**). Integrating a new requirement into an existing design. Redesign as if it had been foundational from day one.
-- **Subtract Before You Add** (**principle-subtract-before-you-add**). Sequencing an addition, refactor, or rewrite. Remove dead weight first, then build on the simpler base.
-- **Minimize Reader Load** (**principle-minimize-reader-load**). Reviewing or shaping code that's hard to trace. Count layers and hidden state, collapse one-caller wrappers, shrink mutable scope.
-- **Outcome-Oriented Execution** (**principle-outcome-oriented-execution**). Planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture, don't preserve throwaway compatibility states.
-- **Experience First** (**principle-experience-first**). Product, UX, or feature-scope tradeoffs. Choose user delight over implementation convenience.
-- **Exhaust the Design Space** (**principle-exhaust-the-design-space**). A novel interaction or architectural decision with no precedent. Build 2-3 competing prototypes and compare before committing.
-- **Build the Lever** (**principle-build-the-lever**). Any non-trivial work. Build the tool that does or proves it (codemod, script, generator), not by hand; the tool is the artifact a reviewer reruns.
-
-**Architecture**
-
-- **Model the Domain** (**principle-model-the-domain**). Writing stateful logic, or code that branches a lot or repeats a shape assumption across files. Encode the domain in a structure (state machine, typed model, table or registry, reducer, boundary, the right collection) instead of scattered conditionals.
-- **Boundary Discipline** (**principle-boundary-discipline**). Wiring validation, error handling, or framework adapters. Guards at system boundaries, trust internal types, keep business logic pure.
-- **Type System Discipline** (**principle-type-system-discipline**). Designing types or a signature in any typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries.
-- **Make Operations Idempotent** (**principle-make-operations-idempotent**). Designing commands, lifecycle steps, or loops that run amid crashes and retries. Converge to the same end state.
-- **Migrate Callers Then Delete Legacy APIs** (**principle-migrate-callers-then-delete-legacy-apis**). Introducing a new internal API while old callers exist. Migrate and delete in one wave.
-- **Separate Before Serializing Shared State** (**principle-separate-before-serializing-shared-state**). Concurrent actors might write the same file, branch, key, or object. Eliminate the sharing first.
-
-**Verification**
-
-- **Prove It Works** (**principle-prove-it-works**). After a task, before declaring done. Verify against the real artifact, not a proxy or "it compiles".
-- **Fix Root Causes** (**principle-fix-root-causes**). Debugging. Trace each symptom to its root cause, reproduce first, ask why until you reach it.
-- **Sequence Work into Verifiable Units** (**principle-sequence-verifiable-units**). Multi-step work (sweeps, migrations, runs of similar edits) and how you stack commits and PRs. Break work into small units that each end in a check, verify each before the next, and order delivery so the sequence proves itself.
-
-**Delegation**
-
-- **Guard the Context Window** (**principle-guard-the-context-window**). Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread.
-- **Never Block on the Human** (**principle-never-block-on-the-human**). Tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct.
-
-**Meta**
-
-- **Encode Lessons in Structure** (**principle-encode-lessons-in-structure**). You catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script instead of more text.
+Each playbook states the principle rules for its work inline, at the step where they bite. Two principles cut across every task and live here in full. The leaf skills are deep references; open one when its inline rule is not enough, not as a routine step.
+
+- **Guard the Context Window.** Context is finite and non-renewable within a session. Route bulk to subagents: large outputs, long files, transcripts, and profiling artifacts get parsed in a subagent that returns the reduced finding, never inlined raw. Don't read what you won't use. Deep reference: **principle-guard-the-context-window**.
+- **Never Block on the Human.** On reversible work, proceed and present the result instead of asking "should I do X?". Reserve questions for genuine product or preference calls no experiment can settle, and confirmation for the irreversible actions listed under Autonomy. Deep reference: **principle-never-block-on-the-human**.
+
+Deep references, by name:
+
+- **Laziness Protocol** (**principle-laziness-protocol**)
+- **Foundational Thinking** (**principle-foundational-thinking**)
+- **Redesign from First Principles** (**principle-redesign-from-first-principles**)
+- **Subtract Before You Add** (**principle-subtract-before-you-add**)
+- **Minimize Reader Load** (**principle-minimize-reader-load**)
+- **Outcome-Oriented Execution** (**principle-outcome-oriented-execution**)
+- **Experience First** (**principle-experience-first**)
+- **Exhaust the Design Space** (**principle-exhaust-the-design-space**)
+- **Build the Lever** (**principle-build-the-lever**)
+- **Model the Domain** (**principle-model-the-domain**)
+- **Boundary Discipline** (**principle-boundary-discipline**)
+- **Type System Discipline** (**principle-type-system-discipline**)
+- **Make Operations Idempotent** (**principle-make-operations-idempotent**)
+- **Migrate Callers Then Delete Legacy APIs** (**principle-migrate-callers-then-delete-legacy-apis**)
+- **Separate Before Serializing Shared State** (**principle-separate-before-serializing-shared-state**)
+- **Prove It Works** (**principle-prove-it-works**)
+- **Fix Root Causes** (**principle-fix-root-causes**)
+- **Sequence Work into Verifiable Units** (**principle-sequence-verifiable-units**)
+- **Encode Lessons in Structure** (**principle-encode-lessons-in-structure**)
 
 ## Autonomy
 

pstack/skills/poteto-mode/playbooks/authoring-a-skill.md

@@ -7,6 +7,6 @@
 3. Test cases if structural; skip if subjective.
 4. Run **Opening a PR**.
 
-When in doubt, delete; prose earns its keep by changing a decision. Tell it to do the thing and skip the reason. Explain only when the rule is confusing without one. Match tone to scope. Point at structural sources (types, READMEs, config); hardcoded details go stale (the **encode-lessons-in-structure** principle skill). Delegate to other skills by path; don't restate. A workflow you keep hitting but isn't captured → propose a new skill.
+When in doubt, delete; prose earns its keep by changing a decision. Tell it to do the thing and skip the reason. Explain only when the rule is confusing without one. Match tone to scope. Point at structural sources (types, READMEs, config); hardcoded details go stale. A rule you catch yourself writing a second time becomes a validator check, lint, or script, not more prose. Delegate to other skills by path; don't restate. A workflow you keep hitting but isn't captured → propose a new skill.
 
 **Reply:** summary of the skill, key design decisions, validation notes.

pstack/skills/poteto-mode/playbooks/autonomous-run.md

@@ -5,7 +5,7 @@
 1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero). A vague goal stalls; a predicate lets you stop.
 2. Pick the wake mechanism using Cursor's `/loop` command (a built-in, not a pstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking.
 3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride.
-   Sequence the work via the **sequence-verifiable-units** principle skill, verifying each unit before the next instead of batching checks at the end.
+   Verify each unit before starting the next instead of batching checks at the end.
 4. Mid-run discoveries are yours. Address broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself via poteto-mode. Put out-of-band fixes in their own PR. Do not park reversible work for the human or use `AskQuestion`. Surface only irreversible actions, genuine product or preference calls no experiment can settle, or a real dead end. Keep the predicate as the main drive, and return to it after each side fix.
 5. Checkpoint every iteration via the **show-me-your-work** skill, a row for what changed and whether the predicate moved. A run with no trail can't be audited or resumed.
 6. Stop when the predicate is met. A plateau is not a stop, so keep going and pivot your approach to push past it. Surface a genuine dead end rather than spinning, and never relax the predicate to declare victory.

pstack/skills/poteto-mode/playbooks/bug-fix.md

@@ -6,10 +6,9 @@ Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspender
 
 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. If it 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. 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 diff tells the story. 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.
-   This is the canonical **sequence-verifiable-units** principle skill, the failing test first and the fix on top.
+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**.
 
 Investigation fans out `how` + `why` as parallel subagents.