pi-pstack-native 0.0.0-stage → 1.0.0

package/vendor/upstream/0.15.36/pstack/skills/poteto-mode/playbooks/worktree-cleanup.md

@@ -0,0 +1,12 @@
+### Worktree and simulator cleanup
+
+1. Snapshot and audit. Record `df -h /`, then run `scripts/worktree-audit.sh [-b <pr-base-ref>] [repo-path]` (principle-build-the-lever). Without `-b` it checks `MERGED` against `origin/HEAD`, so pass `-b origin/<branch>` when PRs target another branch. It reads paths from `git worktree list`, never hand-typed, since a hand-typed `myrepo-worktrees/x` misses one that lives at `.cursor/worktrees/myrepo/x` (principle-encode-lessons-in-structure). It classifies each worktree by size, age, merge state, uncommitted work, PR state, and the newest chat that touched it, then suggests a bucket. The transcript scan is slow, so background it.
+2. The bucket is advice, not permission. The pinned and active chats are the real artifact (principle-prove-it-works). Get that set from the user or sidebar and cross-check every candidate. The lever has marked `safe` a worktree the user had pinned, so the pinned set wins.
+3. Verify usage before deleting. For every `verify-recent-chat` row, or anything you doubt, fan subagents out to read the transcripts and report whether the chat is pinned or ongoing and which worktrees it touches (principle-guard-the-context-window, transcripts are bulk). A pinned chat spawns arena and repro trees into sibling worktrees via background subagents, and those are in use even when their names never hit the sidebar. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section.
+4. Pause on irreversible loss. `wip:N` is N tracked uncommitted edits. Show the diff and get a decision first, since removing a clean worktree is recoverable from its branch but uncommitted work is gone. `scratch:N` is untracked throwaway, safe to drop, but name the files. Per Autonomy, clean and merged and not-in-use proceeds. `wip` and in-use pause.
+5. Prune the confirmed set. Per path, `git worktree remove --force <path>`. If the dir survives on ignored build artifacts, `rm -rf` it, then `git worktree prune`. Branch refs survive, so no commits are lost. Confirm with `df -h /` and re-list.
+6. Simulators and other reclaimers. Simulators are usually the next-biggest win. `xcrun simctl --set testing delete all` (XCTestDevices clones), `xcrun simctl delete unavailable`, and `xcrun simctl runtime list` then `runtime delete <id>` for old runtimes. More when needed: Xcode `DerivedData` and `iOS DeviceSupport`, `~/Library/Application Support/Cursor` (`state.vscdb.backup`, and `snapshots/roots/<root>` where a `<root>` named for a folder you opened as a workspace balloons), package caches (pnpm, uv, brew, yarn). Clear only caches the user has not said to keep.
+
+This is the one playbook that deletes user state with no code review to catch a slip, so the gates above are the review.
+
+**Reply:** `df -h /` before and after with space reclaimed, the worktrees pruned, and a one-line reason for each held back (in-use by which chat, or uncommitted work).

package/vendor/upstream/0.15.36/pstack/skills/poteto-mode/references/bugbot-triage.md

@@ -0,0 +1,142 @@
+# Bugbot triage
+
+Use this reference when the Babysit playbook (`../playbooks/babysit.md`) handles Bugbot or review-automation comments. The goal is not to ignore Bugbot by default. The goal is to stop treating every comment as a required code change.
+
+## Decision rubric
+
+Classify each Bugbot thread before acting:
+
+- `fix`: The comment identifies a plausible correctness, security, privacy, data loss, auth, billing, migration, idempotency, race, or shipped-behavior issue. Fix it in the lowest owning PR, then reply with the commit SHA and resolve the thread.
+- `dismiss`: The comment matches a documented low-risk noisy pattern, and the current code/context proves the concern does not need a code change. Reply with a short reason and resolve the thread.
+- `ask`: The comment is novel, high-severity, security/privacy/data-related, or ambiguous. Ask the user instead of guessing.
+
+When in doubt, ask. Skipping a noisy code-quality comment is cheap; skipping a real data or security bug is not.
+
+## Learned pattern format
+
+Add future patterns in this shape:
+
+```markdown
+### <short pattern name>
+
+- Confidence: candidate | recurring | strong
+- Skip when: <conditions that must be true>
+- Do not skip when: <risk boundaries>
+- Example signal: <phrases or code context that identify the pattern>
+- Source: <PR/comment URL or short historical note>
+```
+
+Use `candidate` for one or two examples. Use `recurring` after multiple real dismissals. Use `strong` only when the pattern is narrow, repeatedly verified, and low-risk.
+
+## Recurring skip candidates
+
+### Intentional UI or design-system visual changes
+
+- Confidence: candidate
+- Skip when: The PR description, screenshots, design review, or nearby code makes the visual change explicit, and the Bugbot comment is only restating that a shared visual default changed.
+- Do not skip when: The comment points to accessibility, focus visibility, keyboard navigation, color contrast, or a component API contract that the PR did not intentionally change.
+- Example signal: Comments about focus outlines, button sizes, spacing, or shared component visual defaults where the owner replies "intentional" or "intended".
+
+### Upstack or stack-local usage Bugbot cannot see
+
+- Confidence: candidate
+- Skip when: Bugbot flags an export, component, helper, or file as unused, and the active forge's PR list and diffs, upper-stack diffs, or PR context show it is used by a later PR in the stack.
+- Do not skip when: The current PR is not part of a stack, the symbol is public API, or the supposed upstack use cannot be verified.
+- Example signal: "Exported component is never used" with a human reply like "used upstack".
+
+### Temporary duplication during parallel implementation
+
+- Confidence: candidate
+- Skip when: The PR intentionally duplicates a small amount of code to keep a new path parallel to an old path that is being deleted, replaced, or proven out.
+- Do not skip when: The duplicated code changes security, billing, data access, API behavior, or a long-lived shared abstraction would clearly reduce risk.
+- Example signal: "Significant duplication" or "duplicated validation logic" where the owner explains the old path will be deleted or the duplicate logic is intentionally local.
+
+### Existing framework or component invariant covers the warning
+
+- Confidence: candidate
+- Skip when: The concern is already guaranteed by a shared component, framework contract, type invariant, or single source of truth visible in the current diff or nearby code.
+- Do not skip when: The invariant is assumed but not enforced, depends on timing, or crosses async/state boundaries where values can diverge.
+- Example signal: Comments about missing max-height on an inner popover when the shared popover enforces viewport bounds, or nullable values where the local checked value and passed value share the same source.
+
+### Owner-declared follow-up or deferred cleanup
+
+- Confidence: candidate
+- Skip when: The PR owner explicitly says the issue is a known follow-up, the behavior is not made worse by the current PR, and the comment is not about a high-risk area.
+- Do not skip when: The agent is acting without owner input, the issue is medium/high severity product behavior, or deferring would merge a new regression.
+- Example signal: "I'll worry about that later" or "we'll delete this eventually".
+
+### Self-withdrawn or explicit false-positive rule comments
+
+- Confidence: recurring
+- Skip when: The comment body or a later Bugbot reply explicitly says the finding is withdrawn, compliant, or a false positive, and the agent can verify the relevant rule locally.
+- Do not skip when: The only evidence is a human saying "false positive" on a high-risk issue without explanation.
+- Example signal: A file-naming rule comment whose body says the file is already compliant.
+
+## Ask by default
+
+Do not auto-skip these categories, even if a previous PR dismissed something similar:
+
+- Security, privacy, auth, billing, data retention, training-data, and permission-boundary findings.
+- High-severity findings.
+- Migration, schema, idempotency, concurrency, and cross-system behavior findings.
+- Comments where the suggested fix is small and clearly reduces risk without changing product intent.
+
+Historical data showed humans sometimes dismiss security/data-flow comments. Treat those as owner judgment calls, not team-wide skip rules.
+
+## Candidate learnings from recent babysits
+
+Append new candidate learnings here during or after babysitting when they look team-useful but not yet mature. Prefer promoting recurring candidates into the section above once several PRs confirm the pattern.
+
+### Manual reimplementations of native browser behavior
+
+- Confidence: candidate
+- Skip when: Practically never. When a diff replaces native browser behavior with a manual equivalent (native sticky → JS-positioned clones, native scroll targeting → forwarded wheel/touch events, paint-order occlusion → masks/clip-path), Bugbot's logic-bug findings against that code have been consistently legitimate.
+- Do not skip when: The finding concerns event-forwarding gaps (wheel deltaMode, touch pans, scroll-chaining at edges, tap slop), mask/clip hit-testing divergence, or observer-vs-React state timing races in such code. Default to fix.
+- Example signal: "masks do not affect hit-testing", "overlay blocks wheel scroll", "ignores deltaMode", "runs in the IntersectionObserver callback before React applies state".
+- Source: one sticky-occlusion PR: six Bugbot passes, roughly eighteen findings, every one fixed rather than dismissed.
+
+### Contract-test drift claims are cheaply verifiable — run the test first
+
+- Confidence: candidate
+- Skip when: Never skip the verification itself; it costs one command. When a PR
+  ships a contract test that pins protocol or documentation prose (regexes over
+  a SKILL.md, snapshot of doc wording), and Bugbot claims "the test no longer
+  matches the doc" (or vice versa), run that test on the PR tip before
+  classifying. A red run confirms the claim empirically; a green run is a
+  concrete disproof for the dismissal reply.
+- Do not skip when: n/a — this is a verification shortcut, not a dismissal
+  pattern. Note that repeat-pass lean-dismiss heuristics would misfire here:
+  prose-pinning tests drift precisely BECAUSE earlier fix rounds edit the prose.
+- Example signal: "Contract test omits the pre-fix wait" on a PR whose earlier
+  fix commits reworded the pinned passage; the test run on the tip failed on
+  exactly the cited assertion.
+- Source: one prose-pinning PR with eight Bugbot passes; the claim was real on
+  pass 7 despite every earlier pass being fixed-and-resolved.
+
+### Stale security-review finding already fixed later in the same PR
+
+- Confidence: candidate
+- Skip when: An agentic security review (or similar) claims a missing authz/validation call, and the current PR tip clearly includes that exact gate (with tests), typically added in a later hardening commit after the review ran.
+- Do not skip when: The cited helper is a no-op for the principal under discussion, the check runs after the side effect it guards, or coverage for the claimed principal is missing.
+- Example signal: A HIGH "missing authorization check" finding while the exact guard is already called before the side effect on the tip.
+- Source: one webhook-endpoint PR whose hardening commit postdated the review run.
+
+### Widening a deliberately narrow error condition would mask the real error
+
+- Confidence: candidate
+- Skip when: The finding asks to broaden a narrow error condition (a specific
+  `errno`, error code, or status class) into a catch-all, and that narrowness
+  encodes a real distinction. The canonical shape is a dependency fallback
+  gated on `ENOENT`: "binary is not installed" is a different situation from
+  "the command ran and failed". Retrying on any non-zero exit would re-run a
+  legitimate failure (not found, expired auth, network) against the fallback
+  and then report the fallback's error, hiding the true one.
+- Do not skip when: The narrow condition misses a case in the SAME category
+  (another "binary unusable" errno such as `EACCES`, another transport-level
+  failure), the unhandled path loses data or leaves partial state, or the retry
+  is idempotent AND the original error is still surfaced.
+- Example signal: "only retries when X fails with ENOENT … never tries the
+  fallback even when a working Y exists", pointing at code whose fallback
+  exists for a missing dependency rather than a failed operation.
+- Source: one CLI-rename PR whose fallback existed for a missing binary rather
+  than a failed command.

package/vendor/upstream/0.15.36/pstack/skills/principle-attack-the-premise/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-attack-the-premise
+description: "Apply when two or more fixes that share one premise have failed the same gate. Write the premise down and test it directly before you write another fix that assumes it."
+disable-model-invocation: true
+---
+
+# Attack the Premise
+
+When two or more fixes that share one premise have failed the same gate, suspect the premise, not the fixes.
+
+**Why:** Each failed fix is evidence against the belief it assumed. A third fix on the same premise spends effort where the evidence already says the cause is not.
+
+**Pattern:**
+- **Write the premise down.** The premise is the one sentence that every failed fix assumed.
+- **Test the premise before the next fix.** Find an observation that would come out differently if the premise were false, and make it. Look at how the failures are distributed, not only at how large they are. Make the check rerunnable per [Build the Lever](../principle-build-the-lever/SKILL.md).
+- **Follow the evidence.** If it contradicts the premise, the cause is elsewhere. Look for what the failures have in common that the premise did not predict. If it confirms the premise, ask the next "why" per [Fix Root Causes](../principle-fix-root-causes/SKILL.md). The earlier fixes may have treated a consequence instead of the cause.
+- **Remove the condition instead of compensating for it**, per the [Laziness Protocol](../principle-laziness-protocol/SKILL.md). If the evidence shows that one part always lands on the losing side, change what puts it there. A mechanism that cleans up after it leaves the cause in place and adds work on every run.
+
+**Stop:** Do not start the next fix before the premise is written down and tested.
+
+This principle is distinct from [Redesign from First Principles](../principle-redesign-from-first-principles/SKILL.md), which rebuilds a design around a new requirement. It questions a fact the current design assumes.

package/vendor/upstream/0.15.36/pstack/skills/principle-boundary-discipline/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: principle-boundary-discipline
+description: "Apply when wiring validation, error handling, or framework adapters. Concentrate guards at system boundaries (CLI, config, network, external APIs); trust internal types and keep business logic in pure functions."
+disable-model-invocation: true
+---
+
+# Boundary Discipline
+
+Place validation, type narrowing, and error handling at system boundaries. Trust internal code unconditionally. Business logic lives in pure functions. The shell is thin and mechanical.
+
+**Why:** Scattered validation is noisy, redundant, and gives a false sense of safety. Keep logic out of framework wiring so it can be tested without the framework.
+
+**The pattern:**
+- **At boundaries** (CLI args, config files, external APIs, network protocols): validate, return errors, handle defensively.
+- **Inside the system:** typed data, error propagation, no re-validation. Trust the types.
+- **Across the boundary.** Expose domain concepts, not the boundary's private representation. Keep general-purpose mechanism inside and special-purpose policy at the edge.
+
+**Applications:**
+
+Validation and error handling:
+- Validate config at parse time (the boundary), not inside business logic
+- Parse raw data into domain types at the boundary
+- Do not re-export transport, storage, framework, or wire types through the public surface
+- No redundant nil checks deep in call chains if the boundary already validated
+
+Code organization:
+- Business logic in pure functions with no framework dependencies
+- Parse functions: pure transforms from raw bytes to typed state
+- Prompt construction: structured state in, string out
+- Scoring and assessment: pure transforms from state to results
+
+**The tests:**
+- "Is this data crossing a system boundary right now?" If not, validation is redundant.
+- "Can this be a pure function that the shell just calls?" If yes, extract it.

package/vendor/upstream/0.15.36/pstack/skills/principle-build-the-lever/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: principle-build-the-lever
+description: "Apply to any non-trivial work, not just bulk work: edits, migrations, analyses, checks. Build the tool that does it or proves it (codemod, script, generator, or a skill your subagents follow) instead of working by hand. The tool is the artifact a reviewer can rerun."
+disable-model-invocation: true
+---
+# Build the Lever
+
+When the work isn't trivial, build the tool that does it instead of doing it by hand.
+
+A codemod, generator, or script does the work the same way every time and reruns for free. The tool is one artifact a reviewer can read and rerun to check the work. Hand-done changes can only be re-verified by redoing them. A deterministic script turns "trust me" into "run this".
+
+Default to building the lever. Skip it only when the task is trivial, a couple of obvious edits you can see at a glance.
+
+- Do the first unit by hand to learn the recipe, then build the tool. Prove it by rerunning it on that unit and diffing against your hand-done version. Make the lever safe to rerun.
+- Codemod or script for edits, generator for repetitive files, a dump-to-sqlite query for analysis, a rerunnable check for verification.
+- A deterministic lever beats fan-out. If the tool can process every unit in one pass, run it yourself. Don't fan out delegates to hand-apply what a script can do.
+- When you fan work out to subagents, write the lever as a skill they all read: the recipe, the verification contract, and the do-not-touch fences in one artifact. Keep it outside the delegates' write scope so they can't quietly edit the contract.
+- Applying this principle produces a file. If you cited it and there is no codemod, script, generator, or delegate skill in the diff, you didn't apply it.
+- Commit the lever when the work outlives the session.
+
+The bar is triviality, not repetition. A one-off still earns a lever when the lever is what makes the work checkable. Per the [Laziness Protocol](../principle-laziness-protocol/SKILL.md), build the smallest script that does or proves the job, never a framework.
+
+Distinct from [Encode Lessons in Structure](../principle-encode-lessons-in-structure/SKILL.md), which makes a recurring instruction a durable guardrail. This is throughput and reviewability on the work in front of you. For scripting the verification itself, see [Prove It Works](../principle-prove-it-works/SKILL.md).

package/vendor/upstream/0.15.36/pstack/skills/principle-encode-lessons-in-structure/SKILL.md

@@ -0,0 +1,11 @@
+---
+name: principle-encode-lessons-in-structure
+description: "Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text."
+disable-model-invocation: true
+---
+
+# Encode Lessons in Structure
+
+If the lesson needs judgment and cannot be encoded, make the instruction more prominent and add an example of the failure mode.
+
+**Corollary:** If the fix is structural, only use the structural fix. The instruction is the symptom.

package/vendor/upstream/0.15.36/pstack/skills/principle-exhaust-the-design-space/SKILL.md

@@ -0,0 +1,9 @@
+---
+name: principle-exhaust-the-design-space
+description: "Apply when facing a novel UI interaction or architectural decision with no precedent in the codebase. Build 2-3 competing prototypes and compare side by side before committing."
+disable-model-invocation: true
+---
+
+# Exhaust the Design Space
+
+It also applies to product design decisions where user experience depends on feel, not logic.

package/vendor/upstream/0.15.36/pstack/skills/principle-experience-first/SKILL.md

@@ -0,0 +1,19 @@
+---
+name: principle-experience-first
+description: "Apply when product, UX, or feature-scope tradeoffs come up. Choose user delight over implementation convenience; ship fewer polished features over more rough ones."
+disable-model-invocation: true
+---
+
+# Experience First
+
+When implementation convenience conflicts with user delight, choose delight.
+
+- Every feature, control, and option must be justified
+- Ship less, ship better (polished experience with three features beats rough one with ten)
+- Prototype before committing (design decisions are cheaper in throwaway HTML than production code)
+- Get the details right (transitions, alignment, spacing, feedback, error states)
+- Tighten the core loop (every feature should serve the central workflow or get out of the way)
+
+The user is whoever consumes the work. For a UI that is the end user. For a library or an internal API it is the colleague who imports it. The engineer who maintains the code next is a user too. Weigh their experience the same way, and explain impact from their perspective.
+
+Foundations should serve the experience. Foundational thinking governs the *sequence* of work. This principle governs the *target*.

package/vendor/upstream/0.15.36/pstack/skills/principle-explain-the-number/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: principle-explain-the-number
+description: "Apply before you measure, and before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think."
+disable-model-invocation: true
+---
+
+# Explain the Number
+
+- **Write the decision before you run.** Name the result that would change a decision, and the noise floor. Stop when the run-to-run spread is larger than the effect.
+- **Ask "why not double?"** Name the resource or code path that bounds the result, such as a core, a lock, the disk, the network, or the load generator itself. Get it from a profile or from system counters taken during a run, then map it to source. A guess from reading the code is not a limiter. If you cannot say why the number is not twice as good, you do not know what you measured.
+- **List what else the number could be measuring, and rule out each one with evidence.** The usual suspects are errors, skipped or cached work, code that never ran, an untuned side (one left on default settings), noise, and a piece too small to matter end to end.
+- **Keep the evidence with the number.** Put the run count, the spread, and the limiter in the notes or a linked artifact.
+
+For a performance number, run the full procedure with the [benchmark-checklist](../benchmark-checklist/SKILL.md) skill. For an eval result, ask the same of the trials: did every run do the task, does the gap hold across trials and models, and does the scenario matter.
+
+You skipped this when a run started without the result that would change a decision, when the evidence behind a number has no run count, no spread, or no named limiter, or when the time saved is larger than the time the changed piece took.
+
+Distinct from [Prove It Works](../principle-prove-it-works/SKILL.md), which checks that an output is real.

package/vendor/upstream/0.15.36/pstack/skills/principle-fix-root-causes/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-fix-root-causes
+description: "Apply when debugging. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate."
+disable-model-invocation: true
+---
+
+# Fix Root Causes
+
+When debugging, fix the fault, not the place where it surfaced. The symptom is where a wrong state became visible. The root cause is the first place the system did something it should not do, or failed to handle a state it should handle.
+
+**Why:** A symptom fix hides the evidence and leaves the fault free to surface somewhere else. Each one makes the system harder to reason about, because the code now carries a workaround for a bug that nobody named.
+
+**Pattern:**
+- Reproduce first.
+- Ask "why" at each step until the answer is a wrong decision in the code, not a consequence of an earlier one.
+- When stuck, instrument. Read the actual error and the actual state. Do not guess.
+- Ask whether the state that triggered the symptom is legitimate. If the system may be in that state, the code that broke on it is the root cause, and handling the state there is the fix. If the state should never exist, a check where it broke hides the bug. Find what produced the state. Guards, retries, swallowed errors, clamped values, and discarded state are the usual ways to hide a bug.
+- When something fails only after a restart, suspect persisted state first: config files, caches, lock files, serialized state.
+- Check for the pattern, not just the instance. Find every place with the same fault and fix them all.
+- If a workaround needs a paragraph-long comment to justify it, the code is wrong. Fix the code, not the comment.
+- If the deciding fact took a deep dig to find, propose the cheap, always-on signal that would have shown it at first look.

package/vendor/upstream/0.15.36/pstack/skills/principle-foundational-thinking/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-foundational-thinking
+description: "Apply before writing logic: choosing core types and data structures, sequencing scaffold-vs-feature work, asking what concurrent actors share. Get the data structures right so downstream code becomes obvious."
+disable-model-invocation: true
+---
+
+# Foundational Thinking
+
+**Structural decisions** protect option value. **Code-level decisions** protect simplicity.
+
+**Data structures first.** Get the data shape right before writing logic. Define core types early, trace every access pattern, and choose structures that match the dominant paths.
+
+At code level, DRY the structure, not every line. Types and data models should converge. Three similar statements still beat a premature abstraction. Prefer explicit over clever. Test behavior and edge cases, not line counts.
+
+**Concurrency corollary.** Before sharing state between actors, ask "what happens if another actor modifies this concurrently?" If not "nothing", isolate.
+
+**Scaffold first.** If something helps every later phase, do it first. Ask "does every subsequent phase benefit from this existing?" CI, linting, test infrastructure, and shared types are scaffold. Sequence for option value: setup before features, tests before fixes. Keep commits small and single-purpose.
+
+Each increment should land a coherent abstraction or deepen one that exists. Do not spread a new capability across callers as special-case coordination.
+
+Subtraction comes before scaffolding. Remove dead code first, then lay foundations.

package/vendor/upstream/0.15.36/pstack/skills/principle-guard-the-context-window/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: principle-guard-the-context-window
+description: "Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads."
+disable-model-invocation: true
+---
+
+# Guard the Context Window
+
+**Why:** Context overflow degrades reasoning quality, creates compression artifacts, and halts progress.
+
+**Pattern:**
+- **Size phases and cap scope.** Limit files per phase, set turn budgets, account for mechanism costs.

package/vendor/upstream/0.15.36/pstack/skills/principle-laziness-protocol/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: principle-laziness-protocol
+description: "Apply when refactoring, evaluating diff size, or tempted to add abstractions, layers, or signal threading. Bias toward deletion and the smallest change that solves the problem."
+disable-model-invocation: true
+---
+
+# Laziness Protocol
+
+- **Consolidate decisions.** Do not repeat the same choice in several places. Put it behind one source of truth and pass the result as a simple flag.
+- **Minimize the diff.** Make the smallest change that solves the problem. Fewer lines beat "elegant" boilerplate.

package/vendor/upstream/0.15.36/pstack/skills/principle-make-operations-idempotent/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: principle-make-operations-idempotent
+description: "Apply when designing commands, lifecycle steps, or processing loops that run amid crashes, restarts, and retries. Converge to the same end state regardless of partial prior runs."
+disable-model-invocation: true
+---
+
+# Make Operations Idempotent
+
+Design operations so they converge to the correct state regardless of how many times they run or where the previous run stopped. Every state-mutating operation should answer: "What happens if this runs twice? What happens if the previous run crashed halfway?"
+
+**Why:** Commands, lifecycle operations, and processing loops run where crashes, restarts, and retries are normal. If partial state changes the next run's outcome, every restart becomes a debugging session.
+
+**The idea:** derive each step from the state that exists, not from what the previous run meant to do. Read the current state, compare it to the goal, and apply only the difference. A step written this way is safe to repeat, because a repeat finds nothing left to do.
+
+Anything a run leaves behind, such as a lock, a temporary file, a half-written record, or a claimed job, must be recognizable as stale by the next run. Judge staleness by evidence that stays true wherever the previous run could have stopped, not only in the common case. A marker that the next run cannot judge turns every crash into manual cleanup. For example, write to a temporary path and rename it into place, or compare artifacts by content instead of by creation order.
+
+**The test:**
+1. What happens if this runs twice in a row?
+2. What happens if the previous run crashed at every possible point?
+3. Does re-execution converge to the same end state?
+
+If any answer is "it depends on what state was left behind," the operation needs a reconciliation step.

package/vendor/upstream/0.15.36/pstack/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: principle-migrate-callers-then-delete-legacy-apis
+description: "Apply when introducing a new internal API while old callers still exist. Migrate callers and delete the old API in the same wave instead of preserving compatibility layers."
+disable-model-invocation: true
+---
+
+# Migrate Callers Then Delete Legacy APIs
+
+- Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details
+
+**When this applies:**
+- No external users depend on backward compatibility
+- The project can absorb coordinated breaking changes
+- The new API is part of a simplification or refactor initiative

package/vendor/upstream/0.15.36/pstack/skills/principle-minimize-reader-load/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: principle-minimize-reader-load
+description: "Apply when reviewing or shaping code that's hard to trace. Count layers between question and answer, and hidden state in the reader's head; collapse one-caller wrappers and shrink mutable scope."
+disable-model-invocation: true
+---
+
+# Minimize Reader Load
+
+Maintainability is the work a reader must do to understand code. Track two axes: **layers to trace** (indirections between the question and the answer) and **state to hold** (hidden or mutable context the reader must keep in their head). LOC, cyclomatic complexity, and "clean architecture" are proxies. Reader load is the thing that matters. The two axes are independent. A flat file with 50 globals can be as hard to reason about as a 6-layer adapter stack. Guard both. This is the human analog of [Guard the Context Window](../principle-guard-the-context-window/SKILL.md). Working memory is finite for readers too.
+
+- **Collapse layers** that cost more than they save: wrappers with one caller, adapters with no second implementation, speculative indirection that was never needed. Inline them.
+- **Make adjacent layers change the abstraction.** A layer that repeats the same methods and arguments adds reader load without compression. Collapse pass-through layers.
+- **Demand interface compression.** A broad interface that hides little complexity makes readers learn both the surface and the implementation. Prefer boundaries that hide meaningful decisions.
+- **Shrink state scope:** prefer pure functions (returns over mutations), locals over fields, fields over module state, and module state over globals. Derive instead of sync.
+- **Name the invariant at the boundary,** not in every consumer, so the reader learns it once.
+- Before adding a layer or a piece of state, ask: does it reduce reader load elsewhere by at least as much?
+
+**The test:** can a new reader answer "where does X come from?" and "what can change X?" in under 30 seconds? If not, cut layers or cut state.

package/vendor/upstream/0.15.36/pstack/skills/principle-model-the-domain/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: principle-model-the-domain
+description: "Apply when writing stateful logic, or when code branches a lot or repeats a shape assumption across files."
+disable-model-invocation: true
+---
+
+# Model the Domain
+
+Encode the real domain in a data structure instead of scattering it across conditionals. A structure that matches the domain makes invalid states unrepresentable and deletes branches. Choosing it at write time is cheap. Recovering it later reads as a refactor and gets deferred.
+
+Reach for:
+
+- A state machine instead of scattered booleans, phases, or lifecycle checks.
+- A typed model instead of loose parameters or repeated shape assumptions.
+- A map, registry, lookup table, or discriminated union instead of branching spread across files.
+- A reducer or command/event model instead of ad hoc state mutations.
+- A module organized around one body of domain knowledge instead of a sequence such as load, validate, transform, and save. Execution order is not ownership.
+- A small module boundary that gathers repeated behavior, ownership, or invariants.
+- A queue, cache, index, graph, tree, or normalized collection where the access pattern calls for it.
+- Any other structure that fits. When none fits, work out what the code must never allow and how the data gets read, then find the structure that encodes exactly that.
+
+Do not force an abstraction. Prefer boring code if the current shape is already clear, local, and unlikely to grow. Be skeptical of an abstraction that adds indirection without removing branches, duplicated rules, invalid states, or lifecycle risk.
+
+The sign that you skipped this is a new feature that grows an existing if/else chain by one more branch, or a second boolean that must stay in sync with the first. Temporal decomposition is another sign. Phase-named modules repeat the same domain rules across steps.

package/vendor/upstream/0.15.36/pstack/skills/principle-never-block-on-the-human/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: principle-never-block-on-the-human
+description: "Apply when tempted to ask 'should I do X?' on reversible work."
+disable-model-invocation: true
+---
+
+# Never Block on the Human
+
+The human supervises asynchronously. Agents must stay unblocked. Make reasonable decisions, proceed, and let the human course-correct after the fact. Since code changes are reversible and reviewable, a wrong decision usually costs less than blocking.
+
+- Proceed, then present. Do the work, show the result. Don't ask "should I do X?" Do X, explain why.
+- Make the system self-healing. When you notice a problem, log it and fix it in the next round.
+- Irreversible actions (force-push, delete production data, send external messages) still require confirmation.
+- Reversible actions (write code, edit notes, split tasks) should proceed without blocking.
+- Product direction comes from the human. Execution should not block.

package/vendor/upstream/0.15.36/pstack/skills/principle-outcome-oriented-execution/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: principle-outcome-oriented-execution
+description: "Apply during planned rewrites and migrations with explicit phase boundaries. Converge on the target architecture; don't preserve smooth intermediate states with throwaway compatibility code."
+disable-model-invocation: true
+---
+
+# Outcome-Oriented Execution
+
+Optimize for the intended, verifiable end state rather than preserving smooth intermediate states.
+
+**Why:** Keeping every intermediate step fully stable often creates temporary compatibility code that becomes long-lived debt. Converge on the target architecture and prove correctness at explicit verification boundaries.
+
+**Core rule:**
+- Prioritize end-state integrity over transitional stability
+- Intermediate breakage is acceptable when it is planned, scoped, and reversible
+
+**Guardrails:**
+- Use this for planned rewrites and migrations with explicit phase boundaries
+- Declare where temporary breakage is acceptable
+- Keep high-signal checks for actively touched areas while migrating
+- Require full static and runtime verification at plan completion

package/vendor/upstream/0.15.36/pstack/skills/principle-prove-it-works/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: principle-prove-it-works
+description: "Apply after completing a task, before declaring done. Verify against the real artifact (run the feature, read the actual value, inspect the diff), not a proxy, self-report, or 'it compiles.'"
+disable-model-invocation: true
+---
+
+# Prove It Works
+
+Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or "it compiles."
+
+**Why:** Unverified work has unknown correctness. Indirect verification (file mtimes, output freshness, agent self-reports, cached screenshots) feels cheaper than direct observation. Acting on a wrong inference costs far more than checking the source.
+
+Check the real thing, not a proxy:
+- Check process liveness directly, not indirectly through derived state
+- Read the actual value, not a cached or derived representation
+- When verification fails, suspect the observation method before suspecting the system
+
+## Script the check when you can
+
+The strongest proof is a deterministic script that re-runs the same comparison, not a one-time eyeball. Write the script, run it, and keep its output as an artifact a reviewer can re-run instead of trusting your word.
+
+Keep the artifact visible for the human. Commit it only for large or complex work where the trail has to be auditable later, like a big port or migration (the **show-me-your-work** skill).

package/vendor/upstream/0.15.36/pstack/skills/principle-redesign-from-first-principles/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: principle-redesign-from-first-principles
+description: "Apply when integrating a new requirement into an existing design."
+disable-model-invocation: true
+---
+
+# Redesign From First Principles
+
+When integrating a change, don't bolt it onto the existing design. Redesign as if the requirement had been a foundational assumption from the start.
+
+- Read all affected files and understand the current design
+- Ask: "if we were writing this from scratch with this new requirement, what would we build?"
+- Propagate the change through every reference: types, docs, examples, rationale sections
+- Think about the whole redesign, then deliver it incrementally
+
+This is the method for preserving option value when integrating changes into an existing design.

package/vendor/upstream/0.15.36/pstack/skills/principle-separate-before-serializing-shared-state/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: principle-separate-before-serializing-shared-state
+description: "Apply when concurrent actors might write to the same file, branch, key, or state object. Eliminate the sharing first; serialize structurally only when one shared writer is a real invariant."
+disable-model-invocation: true
+---
+
+# Separate Before Serializing Shared State
+
+When concurrent actors might share mutable state, first ask whether they need the same mutable object. If not, eliminate the sharing. When sharing is real, enforce serialization structurally: lockfiles, sequential phases, exclusive ownership. Instructions and conventions are not concurrency control.
+
+**Why:** Concurrent writes to shared state create race conditions that are intermittent, hard to reproduce, and expensive to debug.
+
+**Pattern:**
+1. **Identify shared mutable state** (files both read and write, branches both push to, APIs both define and consume).
+2. **Default: eliminate the shared write target.** Ask: do these actors need one canonical object, or are they publishing independent facts? Give each actor its own owned file, key, branch, or state directory, and merge only at the read/reporting boundary. Two workers writing their own `lastX` field into one `state.json` is still shared mutation. `indexer-state.json` + `metrics-state.json` is not.
+3. **Only when one shared write target is a real invariant, serialize access structurally** (lockfiles, sequential phases, single-writer actor, or atomic compare-and-swap). Treat "we need a lock" as a design smell to check, not as the default answer.

package/vendor/upstream/0.15.36/pstack/skills/principle-sequence-verifiable-units/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: principle-sequence-verifiable-units
+description: "Apply to multi-step work (sweeps, migrations, runs of similar edits) and to how you stack commits and PRs. Break work into small units that each end in a verifiable state, check each before the next, and order delivery so the sequence proves itself to a reviewer."
+disable-model-invocation: true
+---
+
+# Sequence work into verifiable units
+
+Order work as a sequence of small units, each ending in a state you can check, and don't advance until the current one is green.
+
+**Why:** A break caught at the unit that caused it is cheap to localize. A break caught after a batch is buried, and you have already built further on a broken base. Sequencing those same units into a delivery a reviewer can replay turns "trust me" into "watch it go red, then green."
+
+**Execution.** In a sweep, migration, or any run of similar edits, verify each change before starting the next. Each unit is a before/after bracket: known-good state, one change, run the check, then proceed. Rebase onto clean trunk first so every check measures against the real baseline. When a lever does the edits, the per-unit check is nearly free. Run it anyway.
+
+**Delivery.** Stack commits and PRs in the order that proves the work. The canonical shape is the failing test first, then the fix on top. Other story orders are a subtraction before the reshape, a baseline capture before the treatment, the scaffold before the feature. Each commit lands on its own and the sequence reads as an argument.
+
+The sequencing complement to the **prove-it-works** principle skill, which keeps each check real, and the **build-the-lever** principle skill, which makes the per-unit check cheap.

package/vendor/upstream/0.15.36/pstack/skills/principle-subtract-before-you-add/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: principle-subtract-before-you-add
+description: "Apply when sequencing an addition, refactor, or rewrite. Remove dead code, redundant validators, and stub references first, then build on the simpler base."
+disable-model-invocation: true
+---
+
+# Subtract Before You Add
+
+When evolving a system, remove complexity first, then build. Default to subtraction.
+
+Make simplification a continual investment. Leave the design slightly simpler and more capable behind the same or smaller surface than you found it.
+
+- Sequence removal before construction
+- Cut before you polish (get to the minimum before investing in quality)
+- Design for observed usage, not speculative edge cases
+- No speculative validators, parsers, or guards beyond what the spec demands
+- Simplify prompts (remove redundant instructions, excessive templates)
+- When a reference has no novel content, delete it rather than leaving a stub