diff --git a/pstack/README.md b/pstack/README.md index ad17785d..7e1f8435 100644 --- a/pstack/README.md +++ b/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.
all twenty-one principles diff --git a/pstack/agents/poteto-agent.md b/pstack/agents/poteto-agent.md index 444bc430..d51dff79 100644 --- a/pstack/agents/poteto-agent.md +++ b/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. diff --git a/pstack/docs/guide/08-principles.md b/pstack/docs/guide/08-principles.md index 97dc61ce..2f7d04e9 100644 --- a/pstack/docs/guide/08-principles.md +++ b/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 diff --git a/pstack/skills/how/SKILL.md b/pstack/skills/how/SKILL.md index 490a6e34..7190df60 100644 --- a/pstack/skills/how/SKILL.md +++ b/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?": diff --git a/pstack/skills/poteto-mode/SKILL.md b/pstack/skills/poteto-mode/SKILL.md index 304f2b01..4a9c4f39 100644 --- a/pstack/skills/poteto-mode/SKILL.md +++ b/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 diff --git a/pstack/skills/poteto-mode/playbooks/authoring-a-skill.md b/pstack/skills/poteto-mode/playbooks/authoring-a-skill.md index 0fc01383..259de206 100644 --- a/pstack/skills/poteto-mode/playbooks/authoring-a-skill.md +++ b/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. diff --git a/pstack/skills/poteto-mode/playbooks/autonomous-run.md b/pstack/skills/poteto-mode/playbooks/autonomous-run.md index bc68ad73..e1dea88d 100644 --- a/pstack/skills/poteto-mode/playbooks/autonomous-run.md +++ b/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. diff --git a/pstack/skills/poteto-mode/playbooks/bug-fix.md b/pstack/skills/poteto-mode/playbooks/bug-fix.md index 3db48fb5..48c8c462 100644 --- a/pstack/skills/poteto-mode/playbooks/bug-fix.md +++ b/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. diff --git a/pstack/skills/poteto-mode/playbooks/feature.md b/pstack/skills/poteto-mode/playbooks/feature.md index 3ed7bafc..c2f57cf2 100644 --- a/pstack/skills/poteto-mode/playbooks/feature.md +++ b/pstack/skills/poteto-mode/playbooks/feature.md @@ -7,12 +7,12 @@ 3. Write the throughput checkpoint as four todo items. A dimension that genuinely does not apply (single file, no fan-out) keeps its item with `n/a: ` rather than being dropped: - **Blocking first steps.** Gates run before fan-out. - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. - - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. + - **Shared mutable state.** Default to splitting the target: give each worker its own file, key, or branch and merge at the read boundary. Two workers writing their own field into one shared file is still a collision. When one shared write target is a real invariant, serialize structurally (a lockfile, sequential phases, a single writer); telling parallel workers to take turns is not concurrency control. - **Smallest safe decomposition.** If one worker is best, name why. -4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.5-fast-xhigh`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain** — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). You can spawn a subagent even though you are one; "the app is small" and "a subagent cannot spawn one" are both wrong. A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation; no "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. +4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.5-fast-xhigh`) with a specific scope (file paths, named data shape and its organizing structure — a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic — and success criteria); review its diff yourself. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). You can spawn a subagent even though you are one; "the app is small" and "a subagent cannot spawn one" are both wrong. A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation; no "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. 5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass; flag it. 6. Rebase into small, ordered commits; stack follow-ups. - Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. + Build, verify, and commit each small unit before starting the next; never batch the verification at the end. 7. If the design is contested, `interrogate` before shipping. 8. Run **Opening a PR**. diff --git a/pstack/skills/poteto-mode/playbooks/hillclimb.md b/pstack/skills/poteto-mode/playbooks/hillclimb.md index 6ae44bb6..ca6ef2d7 100644 --- a/pstack/skills/poteto-mode/playbooks/hillclimb.md +++ b/pstack/skills/poteto-mode/playbooks/hillclimb.md @@ -2,19 +2,19 @@ **You own the metric and the experiment's integrity. Supervise and review; delegate the attempts.** For sustained, iterative improvement of one measurable thing against a target ("hillclimb on X", "make startup 50% faster", "systematically drive down ", "keep trying until improves by N%"). A one-off fix is Bug fix or Perf issue; this is the loop. -Core discipline: one change, one measurement, keep or revert. Never stack untested changes, and never claim a win from code inspection. The data decides (the **prove-it-works** principle skill). +Core discipline: one change, one measurement, keep or revert. Never stack untested changes, and never claim a win from code inspection. The data decides. 1. Ground the workload and architecture before choosing the ruler. Run the **how** skill over the target, name the realistic workload dimensions that can move the result (data size, history, state, concurrency), and select a case that reproduces the user's complaint. If no case reproduces it, fix the repro instead of hillclimbing. Then fix one metric, the direction that counts as better, and a checkable stop predicate that pairs a target with a floor on attempts so a lucky early win can't end the run (the example "at least 50% better than baseline and at least 10 iterations" is this shape). Use the user's numbers when given, otherwise agree them. -2. Build the measurement harness, prove its sensitivity, then freeze it (the **build-the-lever** principle skill). Run contrasting realistic workloads and confirm the target case reproduces the symptom while easier cases separate as expected. If the ruler cannot distinguish them, revise the workload or metric. Once frozen, one repeatable command emits the metric, sampled enough to clear the noise (median of N, not a single run); changing it invalidates every earlier number. Record the baseline metric and a green run of the regression gate (the tests that must keep passing) before any change. +2. Build the measurement harness, prove its sensitivity, then freeze it. The harness is the lever: one artifact a reviewer can rerun to check every claim. Run contrasting realistic workloads and confirm the target case reproduces the symptom while easier cases separate as expected. If the ruler cannot distinguish them, revise the workload or metric. Once frozen, one repeatable command emits the metric, sampled enough to clear the noise (median of N, not a single run); changing it invalidates every earlier number. Record the baseline metric and a green run of the regression gate (the tests that must keep passing) before any change. 3. Open the decision log via the **show-me-your-work** skill. A `decision.tsv`, one row per attempt: id, hypothesis, change, before, after, delta, tests, verdict (kept or reverted), note. This is the run's memory. Read it before each attempt so the search accumulates instead of circling. Keep it out of the tree (gitignored) so it survives reverts. 4. Ground each hypothesis in the architecture model from step 1, so it names a specific mechanism ("defer X off the boot path because it blocks first paint"), not "try memoizing something". 5. Loop, one hypothesis per iteration: - - Hand the change to a subagent using your configured hillclimb model (default `gpt-5.6-sol-max`) with a tight scope; supervise and review the diff rather than typing it (the **guard-the-context-window** principle skill). When several independent hypotheses are live, fan them to parallel subagents, each in its own worktree so they can't collide (the **separate-before-serializing-shared-state** principle skill). + - Hand the change to a subagent using your configured hillclimb model (default `gpt-5.6-sol-max`) with a tight scope; supervise and review the diff rather than typing it. When several independent hypotheses are live, fan them to parallel subagents, each in its own worktree so they can't collide; parallel attempts never write the same branch or file. - Measure before and after with the frozen harness, and run the regression gate. - Accept only when the metric moves past noise and the gate stays green. Otherwise revert the change in full; a tweak that "might help" does not ride along. - One commit per accepted fix, staging only the files you changed (`git add `, never `-A`). Log the row either way, kept or reverted. - Each iteration ends in a check before the next begins (the **sequence-verifiable-units** principle skill). If the run is unattended, borrow only the wake mechanism from the Autonomous run playbook (`playbooks/autonomous-run.md`), not its stop rule. This playbook's stop criteria below govern, so a plateau means pivot, not stop. -6. Push past the first plateau. On a stall, several rejects in a row, pivot category, combine near-misses, re-read the source, or try something more radical before concluding the hill is climbed. Correctness and simplicity outrank the number. Revert a win that breaks behavior, and keep a simplification that holds the number (the **laziness-protocol** principle skill). + Each iteration ends in a check before the next begins. If the run is unattended, borrow only the wake mechanism from the Autonomous run playbook (`playbooks/autonomous-run.md`), not its stop rule. This playbook's stop criteria below govern, so a plateau means pivot, not stop. +6. Push past the first plateau. On a stall, several rejects in a row, pivot category, combine near-misses, re-read the source, or try something more radical before concluding the hill is climbed. Correctness and simplicity outrank the number. Revert a win that breaks behavior, and keep a simplification that holds the number. 7. Stop when the predicate is met, or when the remaining ideas are genuinely marginal and not worth their cost. Don't relax the predicate to declare victory, and don't quit while cheap untried hypotheses remain. If you are stuck, surface it instead of spinning. 8. Run **Opening a PR** with the accepted commits stacked in the order they landed, so the metric's climb reads top to bottom. diff --git a/pstack/skills/poteto-mode/playbooks/perf-issue.md b/pstack/skills/poteto-mode/playbooks/perf-issue.md index e791de35..59385dbb 100644 --- a/pstack/skills/poteto-mode/playbooks/perf-issue.md +++ b/pstack/skills/poteto-mode/playbooks/perf-issue.md @@ -14,7 +14,7 @@ - **Lazy evaluation.** Cost lands on results that are never used or not needed yet (eager init on the boot path, rendering offscreen items). Defer the work until first use. - **Scheduling.** The work must happen, but not during the interactive moment. Move it to where nobody is waiting: idle callbacks, a background warmup after boot, precompute before the user arrives, cleanup after the frame commits. Distinct from Lazy (later-when-needed): Scheduling often runs the work *earlier* than the hot moment, or in its shadow. The win is perceived latency, so measure the interactive path, not total work done. 3. Plan the fix from the trace. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured perf-issue model (default `gpt-5.6-sol-max`); review the diff. Capture a post-fix trace. - Apply the **sequence-verifiable-units** principle skill, verifying each attempt before trying the next. + Verify each attempt against a fresh trace before trying the next; revert an attempt that does not move the number rather than letting it ride. 4. Parse and compare the artifacts (JSON to sqlite, diff). "Inconclusive" or wrong-surface is not a pass; flag it. 5. Cite the measurement in the PR. 6. Run **Opening a PR**. diff --git a/pstack/skills/poteto-mode/playbooks/prototype.md b/pstack/skills/poteto-mode/playbooks/prototype.md index 0f0a8883..07363548 100644 --- a/pstack/skills/poteto-mode/playbooks/prototype.md +++ b/pstack/skills/poteto-mode/playbooks/prototype.md @@ -7,7 +7,7 @@ The one playbook where the Laziness Protocol's "smallest change" and the verific 1. Scope the decision the prototype exists to make: which layout, which interaction, which density, or for an empirical fork which behavior, timing, or approach. No decision means no prototype; route to Feature. 2. Gather references when the design space is open. Search for prior art, summarize a moodboard of themes, palettes, and layouts, let the user pick directions before building. Skip when the direction is set. 3. Build throwaway in an isolated scratch dir, separate from production source. For a visual decision, vanilla HTML/CSS/JS or the lightest stack that renders the idea, CDN deps, a dev server with hot reload. For a behavioral or timing decision, the smallest script that exercises the question. No production framework, no tests, no abstractions. -4. When comparing alternatives, build them behind one switcher (buttons or a keypress), each variant labeled so the user can name it. This is the **exhaust-the-design-space** principle skill made cheap. +4. When comparing alternatives, build them behind one switcher (buttons or a keypress), each variant labeled so the user can name it. When the right answer is not obvious, build two or three competing variants, not one safe pick, and compare them side by side before committing. 5. Verify on the matching surface. For a visual decision, screenshot each variant via the control skill and drive the interaction; the eye is the test. For a behavioral or timing decision, observe the thing you are deciding by logging the timing, printing the output, or watching the render. The observation is the test here, not an assertion. 6. Present alternatives, tradeoffs, and a recommendation. The output is the decision plus the throwaway artifact, not shippable code. Hand the chosen direction to **Feature** (or `architect` for the shape) for the real build. diff --git a/pstack/skills/poteto-mode/playbooks/refactoring.md b/pstack/skills/poteto-mode/playbooks/refactoring.md index 7a6e8b60..f8a88c88 100644 --- a/pstack/skills/poteto-mode/playbooks/refactoring.md +++ b/pstack/skills/poteto-mode/playbooks/refactoring.md @@ -4,13 +4,13 @@ A refactor that smuggles in a behavior change loses its safety net. If the cleanup reveals a missing feature or a real bug, split it out and ship the structural change first against the pinned contract. A redesign is allowed, but name it and route to Feature. Large or cross-cutting structural work (a migration across many call sites, a coordinated reshape of many subsystems) belongs to the **figure-it-out** skill; this playbook is the focused-to-medium change. -1. Pin the behavior contract first. Run the **how** skill over the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. The harness makes "refactor" a checkable claim (**principle-prove-it-works**). If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin. -2. Name the structure the code is missing per **principle-model-the-domain**: a state machine over scattered booleans, a table or registry over spread-out branching, a typed model over repeated shape assumptions, a reducer over ad hoc mutations. Boring code stays when the shape is already clear and local; the reshape must delete branches or invalid states, not add indirection. -3. Name the target shape. State what the module layout, types, and call graph should be if built today (**principle-foundational-thinking**, **principle-redesign-from-first-principles**). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move. -4. Subtract before you add. Delete dead weight, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (**principle-subtract-before-you-add**). The smallest change that reaches the target shape ships (**principle-laziness-protocol**). A speculative cleanup that "might help" gets reverted, not left to ride. -5. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (**principle-migrate-callers-then-delete-legacy-apis**). No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files; renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a subagent using your configured refactoring model (default `grok-4.5-fast-xhigh`) with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself. -6. Prove behavior is unchanged on the real artifact, not "it compiles" (**principle-prove-it-works**). For larger reshapes, run an equivalence check: a script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant control skill. Own the verification yourself; do not trust a delegate's "looks good" summary. -7. Confirm the change earns its place. The success measure is reduced reader load (**principle-minimize-reader-load**): fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. If the diff does not lower reader load somewhere, revert it. -8. Rebase into small ordered commits that tell the story. A subtraction commit, then the reshape, then any follow-on cleanup, so a single revert undoes one slice. Shape them with the **sequence-verifiable-units** principle skill, so each behavior-preserving slice stays green before the next. Run **Opening a PR**. +1. Pin the behavior contract first. Run the **how** skill over the affected subsystem to learn the contract, then write a characterization test, snapshot, or equivalence harness that captures current behavior before any structure moves. The pin is what makes "refactor" a checkable claim rather than a self-report. If the area has no coverage, write the pin before touching structure. Type check and lint are not a pin. +2. Name the structure the code is missing: a state machine over scattered booleans, a table or registry over spread-out branching, a typed model over repeated shape assumptions, a reducer over ad hoc mutations. Boring code stays when the shape is already clear and local; the reshape must delete branches or invalid states, not add indirection. +3. Name the target shape. State what the module layout, types, and call graph should be if built today, with the current requirements as day-one assumptions. The target types make illegal states unrepresentable; a cast or `any` needed to squeeze existing code through the new shape means the shape is wrong, not the code. If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move. +4. Subtract before you add. Delete dead weight, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape. The smallest change that reaches the target shape ships; fewer lines beat elegant boilerplate. A speculative cleanup that "might help" gets reverted, not left to ride. +5. Move in small behavior-preserving steps, each keeping the pin green; never batch the moves and check once at the end. For API reshapes, migrate every caller and delete the old API in the same wave. No compatibility shims, no parallel old-and-new paths. When the sweep is scriptable, write the codemod and run it over every site instead of hand-editing each one; the script is the artifact a reviewer can rerun. Spot-check every rename against the actual files; renames silently miss usages in strings, prose, and back-references. Delegate non-scriptable mechanical edits to a subagent using your configured refactoring model (default `grok-4.5-fast-xhigh`) with a specific scope (file paths, the names being moved, the behavior to hold); review the diff yourself. +6. Prove behavior is unchanged on the real artifact, not "it compiles". For larger reshapes, run an equivalence check: a script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant control skill. Own the verification yourself; do not trust a delegate's "looks good" summary. +7. Confirm the change earns its place. The success measure is reduced reader load: fewer layers between question and answer, less hidden state, fewer indirections without a second consumer. The test is that a new reader can answer "where does X come from?" and "what can change X?" in under 30 seconds. If the diff does not lower reader load somewhere, revert it. +8. Rebase into small ordered commits that tell the story. A subtraction commit, then the reshape, then any follow-on cleanup, so a single revert undoes one slice and each slice lands green on its own. Run **Opening a PR**. **Reply:** the structure that changed, the pin you held it against, the equivalence proof, the reader-load delta, what shipped and what got reverted. No new behavior. diff --git a/pstack/skills/poteto-mode/playbooks/runtime-forensics.md b/pstack/skills/poteto-mode/playbooks/runtime-forensics.md index 76ebfb3a..b060408c 100644 --- a/pstack/skills/poteto-mode/playbooks/runtime-forensics.md +++ b/pstack/skills/poteto-mode/playbooks/runtime-forensics.md @@ -3,7 +3,7 @@ **You own the diagnosis. Instrument the live process, don't theorize from source.** For "why is X leaking / spinning / slow at runtime", heap snapshots, idle-but-busy processes, intermittent glitches. The deliverable is a cited diagnosis, not a fix. 1. Capture the live signal on the matching surface via the control skill: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP trace for a visual glitch. A real artifact, not a guess. -2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread. +2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent; the main thread gets the reduced finding, never the raw payload. 3. Prove the mechanism before believing it. Inject instrumentation via CDP eval on the running process, or hotfix the live code without reloading, to confirm the hypothesis cheaply. A plausible-but-unconfirmed cause can be wrong while the real one sits one layer over. 4. Map the finding back to source: file, symbol, the line that allocates or schedules. 5. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`. diff --git a/pstack/skills/poteto-mode/playbooks/session-pickup.md b/pstack/skills/poteto-mode/playbooks/session-pickup.md index b75ce11a..28fac04d 100644 --- a/pstack/skills/poteto-mode/playbooks/session-pickup.md +++ b/pstack/skills/poteto-mode/playbooks/session-pickup.md @@ -4,10 +4,10 @@ A pickup is inheritance. The prior agent already paid the cost of reading the code, running the repros, making the design choices. Redoing loses the bias check and burns context. Resist the urge to re-derive; read. -1. Locate the prior trail. A local transcript under the active workspace's `agent-transcripts/` directory (the system prompt names the path; do not glob across `~/.cursor/projects/*/`, that crosses workspace boundaries and reads private chats from unrelated projects), a cloud-agent URL, or a pushed branch. Read the metadata overview and last messages first, then scan back for the decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread (the **principle-guard-the-context-window** skill). +1. Locate the prior trail. A local transcript under the active workspace's `agent-transcripts/` directory (the system prompt names the path; do not glob across `~/.cursor/projects/*/`, that crosses workspace boundaries and reads private chats from unrelated projects), a cloud-agent URL, or a pushed branch. Read the metadata overview and last messages first, then scan back for the decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread. 2. Reconstruct operational state. The branch and worktree, what already landed (`git log`, `git diff` against the base), the open todos, the decisions made. The prior trail is authoritative input. Resist the bias to re-derive it. 3. Diff done vs pending. Compare what shipped against what was planned, name the resume point, do not re-run the prior repro or redo completed work. A "let me verify from scratch" pass is the tell that you're treating the trail as untrustworthy when it's actually authoritative. 4. Route the remaining work to the matching playbook and pick the verdict: continue the execution, ship a finished recommendation, ratify or override a prior conclusion, or postmortem a failed run. The pickup playbook ends here; the routed playbook owns the rest. -5. Verify the inherited claims against the original goal on the real artifact (the **principle-prove-it-works** skill). A passing prior self-report is not the proof. +5. Verify the inherited claims against the original goal on the real artifact. You are inheriting unverified work, and a passing prior self-report is not the proof. **Reply:** where the prior agent stopped, what you inherited vs redid (ideally nothing redone), the resume point, and the outcome. diff --git a/pstack/skills/poteto-mode/playbooks/trace-forensics.md b/pstack/skills/poteto-mode/playbooks/trace-forensics.md index 10f8209e..293035d6 100644 --- a/pstack/skills/poteto-mode/playbooks/trace-forensics.md +++ b/pstack/skills/poteto-mode/playbooks/trace-forensics.md @@ -4,7 +4,7 @@ Distinct from **Runtime forensics**, which instruments the live process. Here the capture already exists; the artifact is a fixed dataset, read it, don't re-run it. Keep tooling generic so the playbook stays portable: a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot. -1. Identify the format and load it with the right tool. Parse large artifacts in a subagent (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread. +1. Identify the format and load it with the right tool. Parse large artifacts in a subagent and keep the reduced finding in the main thread; a multi-megabyte trace inlined into your context is the failure mode. 2. Transform the raw artifact into a form you can query. Dump the trace or heap snapshot into sqlite, one row per sample, frame, or node. Reach the queryable shape before you read. 3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree to the hot path. For a leak, follow the retainer chain from the leaked object to a GC root. For a spindump, find the thread stuck on-CPU or blocked and its wait reason. 4. Attribute to source. Map the hot frame to file, symbol, and line via the artifact's own symbols. A frame with no source mapping is not yet a diagnosis; resolve the symbols, or say plainly the artifact does not carry them. diff --git a/pstack/skills/poteto-mode/playbooks/visual-parity.md b/pstack/skills/poteto-mode/playbooks/visual-parity.md index ec4a449e..172dd311 100644 --- a/pstack/skills/poteto-mode/playbooks/visual-parity.md +++ b/pstack/skills/poteto-mode/playbooks/visual-parity.md @@ -4,7 +4,7 @@ 1. Establish the baseline first, before any migration: a visual regression harness that screenshots the current component across its states, plus the target when matching two implementations. No baseline, no parity claim. A blocking prerequisite, not a follow-up. 2. Anti-shortcut clauses, stated and held: no harness modifications, no baseline tampering, no component restructuring to make a diff pass. If the baseline looks wrong, stop and ask, don't edit it. -3. Migrate one component at a time. Each is an independent artifact, so parallelize across worktrees, one owner per component (the **separate-before-serializing-shared-state** principle skill). Shared primitives migrate first as a blocking phase. +3. Migrate one component at a time. Each is an independent artifact, so parallelize across worktrees, one owner per component; two owners never write the same worktree or branch. Shared primitives migrate first as a blocking phase, so parallel owners consume them instead of racing to edit them. 4. Verify each component against its baseline via image diff on the matching surface via the control skill. A nonzero diff is a fail; investigate the pixel delta, don't wave it through. `/loop` per component until the diff is zero. 5. Run **Opening a PR** per component or per safe batch. diff --git a/pstack/skills/poteto-mode/references/plan.md b/pstack/skills/poteto-mode/references/plan.md index 49ab89ab..4caa762f 100644 --- a/pstack/skills/poteto-mode/references/plan.md +++ b/pstack/skills/poteto-mode/references/plan.md @@ -12,17 +12,17 @@ Plan when the change spans three or more files, introduces architecture, has com ## 1. Re-read principles -Read the **Principles** section of the `poteto-mode` skill end to end, and the leaf `principle-*` skills it indexes. The principles govern every plan decision; cross-link them. +Read the **Principles** section of the `poteto-mode` skill end to end. The sections below carry the specific rules where they apply; open a leaf `principle-*` skill only when you need its full treatment. ## 2. Scope and constraints -State your read of scope and constraints in one paragraph. Use `AskQuestion` only for genuinely ambiguous intent (the **never-block-on-the-human** principle skill); give concrete options with each open question. +State your read of scope and constraints in one paragraph. Use `AskQuestion` only for genuinely ambiguous intent; give concrete options with each open question. Resolve what is in scope vs explicitly out, technical or platform constraints, patterns to preserve, and the definition of done. ## 3. Explore in subagents -Delegate codebase exploration (the **guard-the-context-window** principle skill). +Delegate codebase exploration; the main thread gets pointers, not payloads. - Prefer `subagent_type: "poteto-agent"`. `generalPurpose` is the fallback. Never use the built-in `plan` subagent_type; it ignores this skill. - Pass `model:` explicitly per the configured roles (defaults `grok-4.5-fast-xhigh` for code, `claude-fable-5-thinking-max` for judgment). @@ -47,7 +47,7 @@ NN-slug/ - One function or type plus tests, or one bug fix. Not "one file". - Two to three files touched, max. -- Prefer eight to ten small phases over three to four large ones to preserve option value (the **foundational-thinking** principle skill). +- Prefer eight to ten small phases over three to four large ones to preserve option value. - Split if a phase has more than five test cases or three functions. ### Overview file @@ -55,7 +55,7 @@ NN-slug/ - **Context.** Problem and why now. - **Scope.** Included; explicitly excluded. - **Constraints.** Technical, platform, dependency, pattern. -- **Alternatives.** Two or three approaches sketched, choice and rationale (the **exhaust-the-design-space** principle skill). Skip when constraints dictate one. +- **Alternatives.** Two or three approaches sketched, choice and rationale. Skip when constraints dictate one. - **Applicable skills.** Domain skills the implementer should invoke, by name. - **Phases.** Ordered standard-markdown links to phase files. - **Verification.** Project-level commands. @@ -66,12 +66,12 @@ NN-slug/ - Back-link to overview. - **Goal.** What the phase accomplishes. - **Changes.** Files affected and the change at a high level. What and why, not how. No code snippets. -- **Data structures.** Name the key types or schemas. One-line sketch only (the **foundational-thinking** principle skill). +- **Data structures.** Name the key types or schemas. One-line sketch only. - **Verification.** Per section 6. -Order phases so infrastructure and shared types land first (the **foundational-thinking** principle skill). Each phase should be independently shippable. +Order phases so infrastructure and shared types land first; a data-structure change is a one-line diff early and a rewrite late. Each phase should be independently shippable. -For changes touching existing code, apply the **redesign-from-first-principles** principle skill: if we'd built this with the new requirement on day one, what would it look like? Redesign holistically; deliver incrementally. +For changes touching existing code: if we'd built this with the new requirement on day one, what would it look like? Redesign holistically; deliver incrementally. If a phase creates or edits a skill, the phase instructs the implementer to use the **create-skill** skill (Cursor's built-in for authoring SKILL.md files). @@ -88,7 +88,7 @@ Each phase needs both: - Native mobile: whatever simulator-driving skill your team has. - No control skill for the touched surface: flag it in the plan. -For bug fixes, the loop is reproduce on the surface, fix, verify on the same surface. Unit tests show a branch behaves a certain way; they do not prove the bug is gone (the **prove-it-works** principle skill). +For bug fixes, the loop is reproduce on the surface, fix, verify on the same surface. Unit tests show a branch behaves a certain way; they do not prove the bug is gone. ## 6. Implementation guidance