TheOnlyFusionCube/potetos-for-everyone

# Reproduce and fix issues

1. Work in an isolated branch/worktree/sandbox when the host can provide one.
2. Reproduce the exact reported behavior and save the smallest durable evidence.
3. If reproduction fails, vary only evidence-backed environment assumptions; return the blocker instead of guessing.
4. Trace root cause. If a cheap behavioral regression test exists, see it fail for the same reason.
5. Make the smallest fix that explains the reproduction, then rerun the reproduction and targeted checks.
6. Prepare a draft change/PR only when authorized. Post status back to the source thread/ticket with proof and remaining uncertainty.

# Triage issue reports

1. Normalize the report into product area, environment, steps, expected behavior, observed behavior, frequency, and supplied evidence.
2. Search for duplicates and known limitations when issue/search capabilities exist.
3. Inspect the relevant code/feature map enough to judge plausibility without making edits.
4. Classify as confirmed-enough-to-reproduce, needs-reporter-information, duplicate, expected behavior, or currently untriageable.
5. Reply in the source thread/ticket when available with concise rationale and the next action. Do not invent a reproduction.

# Architect

Read the caller first. Architecture starts from use, not from an isolated abstraction.

1. Name the domain data shape and invariants.
2. Map ownership and lifecycle. For concurrency, identify what is truly shared before proposing synchronization.
3. Draft 2-3 boundary shapes when the decision is contested. If `delegate` is available, assign independent designs; otherwise keep alternatives explicit and sequential.
4. Compare on reader load, invalid states, migration cost, idempotence, testability, and fit with existing architecture.
5. Select the smallest coherent shape and write the caller-facing signature/contract before implementation.
6. Use `interrogate` for high-risk or contested decisions.

# Arena

Fan out N parallel attempts at the same task, score them against concrete criteria, pick a base, and graft the best ideas from the others.

1. Frame: Define the artifact contract, 3-6 concrete rubric criteria, and isolated candidate output paths.
2. Fan out: Run parallel candidate attempts on isolated workers (via `delegate` when supported, or labeled sequential passes). Require a concrete artifact and short rationale from each.
3. Cross-judge: Score each candidate against the rubric criteria, compare trade-offs, and recommend the strongest base.
4. Pick a base: Select the implementation that is cleanest, easiest to maintain, and safest under domain invariants.
5. Graft: Port the best independent ideas or edge-case handling from losing candidates into the base by hand.
6. Verify: Validate the synthesized result against the full test and verification suite.

# Automate Me

1. Gather a representative sample of the user's actual completed workflows from available, authorized history. Do not infer private history you cannot access.
2. Extract repeated triggers, decisions, quality gates, preferred artifacts, and successful repair loops. Ignore one-off stylistic quirks unless explicitly requested.
3. Separate universal engineering principles from user-specific routing preferences.
4. Draft a `<name>-mode` Agent Skill that routes through existing skills rather than duplicating them.
5. Validate triggers against positive and negative examples, then present the generated skill and evidence behind each rule.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available workspace, execution, and observation capabilities. When a tool is unavailable, preserve the procedure where possible and report evidence gaps rather than claiming verification.

# Benchmark checklist

Use this when you produce a performance number: a PR's before and after, a regression claim, a hillclimb harness, or a library or config choice. Answer each question with evidence from a run, not a guess about the code.

For a quick ballpark the user asked for, one run is enough. Still check questions 4 and 7, and say that it is one run. Skip the rest unless that run looks wrong. A choice between options is never a ballpark.

## Before you run anything

- Write down the claim you expect to make, in the words you would ship ("export is 30% faster at p50 on the 60k-row dataset"). The questions test that sentence.
- Read the measurement script. Note what it times, counts, and ignores.
- Check the load average with `uptime` and the core count with `nproc`. If the machine is busy, find out what is running. If you cannot stop it, interleave the sides so both see the same noise, and say so in the report.

# Blast Radius

1. Name the changed contract: type, value, state transition, API, storage shape, timing, style token, or side effect.
2. Enumerate direct readers/writers/callers and any serialized/public boundaries.
3. Trace transitive assumptions by search, type references, tests, runtime wiring, and history as available.
4. Identify the strongest fact that would make the change safe and prove that fact by running or inspecting code when possible.
5. Return affected surfaces grouped as definite, plausible, and ruled out with evidence. Never write "safe" without the proof behind it.

# Bro

Restate the answer in ordinary language. Keep the causal chain and the important caveat. Replace jargon with a concrete example where possible. Do not dumb down the actual conclusion or add new claims.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available workspace, execution, and observation capabilities. When a tool is unavailable, preserve the procedure where possible and report evidence gaps rather than claiming verification.

# Correct

The operator keeps correcting agents in this repo for the same mistakes. Change the repo so the next agent can't make them.

Assume every contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Design the repo so a change that looks right from one file is right for the whole repo.

## Find the mistake classes

First, read recent commits, reverts, review comments, agent instruction files, and comments that explain workarounds. Group the mistakes into classes. A class counts once it has happened twice.

## Fix each class at the highest level that works

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available workspace, execution, and observation capabilities. When a tool is unavailable, preserve the procedure where possible and report evidence gaps rather than claiming verification.

# Create a formal verification skill

A test checks the cases that someone thought to write. Formal verification checks every case in a stated scope: every order of steps in a model, every input up to a bound, or every input. This skill finds the part of the repo where that matters most, verifies one property of it, and leaves a project-local skill that lets the next agent check a change against that property. Write that skill for an agent who reads it cold, mid-change, and has never seen your work. The user must be able to trust the result and act on it without learning the verification language.

## Choose the target from the code

Answer from the codebase, and ask the user only what you cannot observe. If the user named an area or a bug, start there.

A good target is a promise the code makes, where a break harms users and tests rarely reach the case that breaks it. Choose the strongest such target in the repo, not the one that is easiest to verify.

## Let the question choose the tool

# Create Verification Skill

1. Interview the repository to discover primary user-facing surfaces (web UI, CLI, API, app).
2. Identify the canonical local start command, ports, environment variables, and required seed data.
3. Determine how an agent can programmatically drive the system (browser/CDP, PTY/CLI, HTTP requests) and capture evidence (screenshots, transcripts, logs, exit codes).
4. Verify isolation requirements: identify if instances can run concurrently or need dedicated ports/profiles.
5. Create `.agents/skills/verify-<app>/SKILL.md` with explicit launch, drive, observe, and cleanup instructions.

# Figure It Out

1. Define the completion predicate and non-goals.
2. Inventory uncertainty. Split it into factual questions, empirical forks, product preferences, and irreversible decisions.
3. Resolve facts by investigation and empirical forks by prototype instead of asking the human when tools can decide.
4. Build a dependency graph of verifiable work units with a proof attached to every node.
5. Identify which units can safely fan out and which share mutable state.
6. Write the bespoke playbook, then execute it using existing skills rather than improvising around its gates.
7. Maintain a decision trail for work that can outlive the current session.

# How

Build an evidence-backed explanation of how the requested subsystem works.

1. Find the public/consumer entry point, then trace data and control flow toward the effect. Do not start from filenames guessed by name alone.
2. Read the core types and state ownership before narrating individual functions.
3. Use `vcs`, tests, or `observe` when they resolve an ambiguity. If `delegate` exists, split independent exploration areas and reconcile them yourself.
4. Draw a compact text or Mermaid diagram when it reduces reader load.
5. Test at least one claim that could easily be wrong by running or inspecting the real path.
6. Explain in consumer order: trigger -> boundary -> state/transform -> side effect -> observable result. Name file/symbol evidence and uncertainty.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available workspace, execution, and observation capabilities. When a tool is unavailable, preserve the procedure where possible and report evidence gaps rather than claiming verification.

Restate in your own words what you think the user's goals are and what problem they're trying to solve.

# Interrogate

Reviewers are attackers, not style voters.

1. Freeze the exact artifact/revision and acceptance criteria.
2. Cover at least these lenses: correctness/invariants, boundary/API compatibility, concurrency/state, tests/verification quality, and maintainability/reader load. Add security/performance when relevant.
3. Use independent workers/models when `delegate` exists. Otherwise run separate sequential lenses and disclose they share context.
4. Require each finding to include a concrete failure mode and evidence or a reproducible check. Reject unsupported nits.
5. The owning agent adjudicates every finding as fix, dismiss, or investigate. Never pass reviewer prose through unexamined.
6. Re-run targeted proof after accepted fixes.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available host capabilities and the fallbacks in PORTABILITY.md; do not claim unavailable tools, subagents, or runtime evidence.

# Ketchup

Catch the user up on what changed in this chat since the last message they wrote before `/ketchup`, and help them understand each change, not only where it stands. Then lay out every call waiting on them so they can make it from your reply alone. Notifications and subagent results are not their messages. Assume the user remembers their last message and nothing after it.

Use [`/bro`](../bro/SKILL.md)'s voice, not its task: plain words, short sentences, no jargon, like one person catching up another. Say what changed for the user, not how you did it. Say "the tests pass", not "CI is green". Leave out hashes, file paths, commands, build numbers, and test counts unless the user needs one to act. Call each PR, branch, or agent by a name the user would know, not by a label you invented. If a fact needs context to make sense, give the context or leave the fact out.

## Gather what changed

Keep this turn read-only. Make visuals only from what you already have: do not change code, start an app or a job, or post anything. Collect your own work since that message, reports from subagents, and messages from anyone else in this chat. Check the current state of each PR, CI run, or agent this chat touched. Check each number you will show against the facts it comes from, and say so when you correct one.

An action item is a call or step only the user can take, such as a product choice, an approval, an irreversible action, or access you lack. Include any still waiting on the user, even one raised before their last message. Work you can still do yourself is not an action item. Never make up a call to fill the reply. A step the user did not ask for and the work does not need is not an action item, unless it is irreversible and waiting on the user: give it one line and no visual.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available host capabilities and the fallbacks in PORTABILITY.md; do not claim unavailable tools, subagents, or runtime evidence.

# Maintain a formal verification skill

A formal check proves a property of what it describes. When the code changes and the verification does not, the check can keep passing while it describes code that no longer exists. That pass is the dangerous case, because it looks like a proof. This skill is the upkeep loop for a verify skill that `/create-formal-verification-skill` generated, or for any project-local skill that runs a model checker, prover, or code-level verifier against named code. The project-local skill handles a change that an agent makes while it uses that skill. This skill handles the changes that skipped it: merges, edits made without the skill, and drift that builds up across many commits.

## Outcomes

Give each check one outcome, and say which:

- **in sync**: no change since the last sync alters what the check describes, and the check passes.
- **updated**: the code changed, the verification now describes the new code, and the check passes.
- **bug**: the verification describes the current code, and the code breaks the property. This is a finding about the code. It is not drift.
- **blocked**: the check could not be brought back in line or could not run. Say exactly why.

# Maintain Verification Skill

1. Diff the current product surfaces against the verification feature map.
2. Run one representative live pass before changing the skill so drift is observed, not guessed.
3. Classify differences as product regression, intentional product change, environment drift, or verifier bug.
4. Update only proven verifier drift. Do not rewrite expectations to make a product regression green.
5. Re-run affected features plus one untouched control feature.

# Make Bot UI

1. Define the operator actions, payload schema, authentication boundary, and observable completion state before UI code.
2. Keep secrets server-side. Treat webhook URLs/tokens as credentials.
3. Implement the thinnest UI that exposes state, errors, retries, and idempotent request IDs.
4. Make every action safe under duplicate delivery or refresh.
5. Verify one full round trip through the real backend when `observe`/network access exists. Otherwise ship a deterministic local mock plus an explicit integration gap.

# No Comments

1. Identify comments that explain obvious code, restate syntax, or explain temporary workarounds that should be deleted.
2. Distinguish legitimate constraints (hard external requirements, regulatory/spec references, non-obvious invariants) from redundant explanations.
3. Convert valid constraint comments into types, tests, assertions, or lints whenever possible.
4. Delete redundant commentary, commented-out dead code, and speculative notes.
5. Verify that code remains readable and self-documenting through clear naming and small, focused functions.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available host capabilities and the fallbacks in PORTABILITY.md; do not claim unavailable tools, subagents, or runtime evidence.

# Poteto help

Answer the user's question about pstack, hand them a prompt they can send, and link the file the answer came from. For a help question, don't start the work. The user asked how, and a pstack run spends real tokens, so let them send the prompt.

A message that asks for work, such as "use pstack to fix this bug", is not a help question. Read [`poteto-mode`](../poteto-mode/SKILL.md), do the work under it, and mention once that a Custom Mode keeps it on.

This file maps questions to the skills and guide pages that hold the answers. Those files own the details. Read the file you route to before you quote it, and trust it when it disagrees with this map. The links here point into the installed plugin, which the user may not be able to open, so give the user the file's public copy: `https://github.com/cursor/plugins/blob/main/pstack/` followed by its path.

## Find out what they need

Infer the need from the message and the conversation. A named situation, such as "which skill reviews a PR?", goes straight to its section. If the need is still unclear, ask one multiple-choice question with these options, then answer only the section they pick:

# Poteto Mode, portable edition

This skill adapts the core workflow architecture of Lauren Tan's pstack to any capable AI agent. Credit and provenance live in the repository `NOTICE.md`.

## Non-negotiables

1. **Classify before acting.** Match the request to one playbook below. For large cross-cutting work with no clean match, use `figure-it-out`. For program-scale standing work, use `orchestrate`.
2. **Name the data shape before non-trivial code.** Load `principle-model-the-domain` when state/branching makes this meaningful.
3. **Resolve empirical forks empirically.** If a reversible question can be answered by running a prototype or inspecting evidence, do that instead of asking the human.
4. **Cross a boundary deliberately.** Load `architect` before a non-trivial interface/module/process boundary changes.
5. **Use parallelism only when it is real.** `arena`, `swarm`, and `interrogate` may use isolated `delegate` workers. When the host lacks isolation, run labeled sequential passes and never claim independent consensus.
6. **Own delegated work.** Review artifacts and evidence yourself. A worker's "done" is not proof.
7. **Finish with the real proof.** Load `principle-prove-it-works`. Verify through the closest consumer-facing artifact available. Name any missing runtime surface.
8. **Keep the change small.** Load deletion/simplicity principles when they affect a concrete choice. Do not apply principles as decorative slogans.
9. **Write plainly.** For durable docs load `technical-writing`; for any prose, apply `unslop`.

# Attack the Premise

## Trigger

When two or more fixes that share one premise have failed the same gate.

## Rule

Inventory who actually owns or exhibits the imbalance, then challenge the shared premise before writing another patch.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Boundary Discipline

## Trigger

At parsing, framework, process, network, storage, or user-input boundaries.

## Rule

Validate and normalize at boundaries, trust internal invariants, and keep business logic free of adapter noise.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Build the Lever

## Trigger

For repetitive, large, or verification-heavy work.

## Rule

Prefer a script, codemod, generator, benchmark, or verifier that performs or proves the work repeatably over hand edits.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Encode Lessons in Structure

## Trigger

When the same corrective instruction appears more than once.

## Rule

Turn recurring guidance into a type, lint, test, metadata flag, generator, runtime check, or skill so the system carries the lesson.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Exhaust the Design Space

## Trigger

For novel interactions or architecture with no strong precedent.

## Rule

Build a few materially different cheap prototypes and compare evidence before committing to one design.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Experience First

## Trigger

When product, UX, API design, or feature-scope tradeoffs arise.

## Rule

Optimize for the end-user experience unless the cost violates an explicit constraint.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available host capabilities and the fallbacks in PORTABILITY.md; do not claim unavailable tools, subagents, or runtime evidence.

# Explain the Number

- **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 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.

# Fix Root Causes

## Trigger

During debugging and incident repair.

## Rule

Reproduce the symptom, trace causality until one mechanism explains it, and fix that mechanism rather than compensating for downstream effects.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Foundational Thinking

## Trigger

Before writing logic, especially when state or concurrency is involved.

## Rule

Choose the core data structures, ownership, and sequencing first so downstream logic becomes simpler.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Guard the Context Window

## Trigger

When reads, logs, fan-out, or generated output threatens to dominate context.

## Rule

Route bulk exploration to isolated workers or files and bring back compact evidence summaries, not raw floods.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Laziness Protocol

## Trigger

When considering adding code, abstractions, dependencies, or speculative features.

## Rule

Bias toward deletion and the smallest change that fully solves the problem.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Make Operations Idempotent

## Trigger

For commands, lifecycle steps, retries, loops, or crash recovery.

## Rule

Design repeated execution to converge on the same correct end state rather than multiplying side effects.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Migrate Callers Then Delete Legacy APIs

## Trigger

When replacing an internal API.

## Rule

Move callers to the new shape and delete the old path in the same migration wave instead of carrying a compatibility layer.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Minimize Reader Load

## Trigger

When code requires too many hops, wrappers, hidden states, or mental joins.

## Rule

Reduce indirection, mutable scope, and one-caller abstractions until the causal path is easy to hold in one mind.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Model the Domain

## Trigger

When stateful logic accumulates branches or repeated shape assumptions.

## Rule

Encode the domain in the right structure: state machine, typed model, table, registry, reducer, boundary, or collection instead of scattered conditionals.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Never Block on the Human

## Trigger

When a reversible empirical or implementation choice can be resolved with available tools.

## Rule

Run the experiment or make the reversible best-effort change, then show the result. Ask only for genuine preference, authority, or irreversible decisions.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Outcome-Oriented Execution

## Trigger

During planned migrations or rewrites with explicit phases.

## Rule

Converge on the target architecture rather than preserving temporary compatibility states as permanent complexity.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Prove It Works

## Trigger

When verifying changes, completing tasks, or claiming something is fixed.

## Rule

Verify the requested behavior against the real artifact or surface whenever possible; a proxy check only proves the proxy.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Redesign from First Principles

## Trigger

When integrating a new requirement into a design that keeps fighting it.

## Rule

Design the shape you would choose if the requirement had existed from day one, then migrate toward that shape.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Separate Before Serializing Shared State

## Trigger

When concurrency, locks, queues, shared state, or complex coordination are being considered.

## Rule

Eliminate unnecessary sharing or partition ownership before adding locks, queues, or coordination.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Sequence Work into Verifiable Units

## Trigger

For migrations, sweeps, repeated edits, and stacks.

## Rule

Break work into small units that each end with a proof and order delivery so every next unit builds on verified state.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Subtract Before You Add

## Trigger

Before an addition, rewrite, or structural refactor.

## Rule

Remove dead weight and obsolete paths first; build on the simpler remaining system.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Test Behavior, Not Implementation

## Trigger

When writing or evaluating tests.

## Rule

Call the system the way its consumer does and assert meaningful observable output; avoid mocks or assertions that only mirror internal calls.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Type System Discipline

## Trigger

At data modeling, API design, or external data ingestion points.

## Rule

Make invalid states hard or impossible to represent and parse external primitives into meaningful internal types at the edge.

## Application

1. Name the concrete decision this principle changes.
2. Apply the rule to that decision, not as a decorative citation.
3. Prefer evidence from the current repository/runtime over generic preference.

# Recall

Rebuild context from durable evidence, not memory theater.

1. Search the sources the host actually exposes: prior chats, decision logs, issues/PRs, branches, commits, docs, or task files.
2. Prefer recent primary artifacts over summaries.
3. Reconcile contradictions against repository/current external state.
4. Return a compact brief: goal, current state, decisions, completed work, open risks, next verified step, and source pointers.
5. If history access is unavailable, say which source is missing rather than fabricating a recollection.

# Reflect

1. Compare the intended workflow with what actually happened using the decision log, diff, test history, and failures.
2. Identify repeated waste, missing checks, bad assumptions, and the earliest point each could have been caught.
3. Prefer structural fixes: scripts, tests, metadata, better boundaries, or narrower skill triggers. Add prose only when it is the right lever.
4. Change the smallest reusable artifact that prevents recurrence.
5. Re-run the scenario or a focused eval to prove the reflection improved behavior.

# Setup pstack, portable

1. Detect host capabilities and available model/delegation options. Do not assume model names.
2. Explain the optional roles: fast mechanical worker, strongest judgment worker, prose/document worker, and review panel.
3. If the host has native delegation, record only routing preferences. If it lacks delegation but agent CLIs are available, configure portable runner profiles using `runtime/config.example.json`; keep secrets in environment variables, not the config file.
4. Write only explicit overrides to `.potetos/config.json`. Missing roles/runners mean inherit the host/parent behavior.
5. Validate the config as JSON and make sure canonical skills remain model-agnostic.
6. Run the installer doctor and a dry invocation of `poteto-mode` discovery. If external runners were configured, run a harmless one-line delegate smoke test.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available host capabilities and the fallbacks in PORTABILITY.md; do not claim unavailable tools, subagents, or runtime evidence.

I want a deeper version of this task, not a bigger one. Before rewriting it, do four things:

1. Say what a top professional in this field would do here that I'm not asking for.
2. Name the rawest material they would start from instead of what has already been digested for me.
3. Name the specific methods and tools they would use.
4. Say what, other than you or me, would show the result is right.

Then rewrite my prompt to ask for exactly that.

Leave choices that are mine to make open instead of deciding them.

# Show Me Your Work

Keep `.potetos/decisions.tsv` with columns:

`timestamp\tunit\tdecision\tevidence\talternatives\tverification\trevision`

Rules:

1. Log decisions that materially change scope, architecture, risk, or the next unit. Do not log every command.
2. Use stable file/commit/test/URL references in evidence fields when available.
3. Record rejected alternatives briefly enough to explain why the chosen path won.
4. Update verification after the evidence exists; never pre-fill success.
5. Keep secrets and private transcript content out of committed logs.

> Portable adaptation of Lauren Tan's pstack v0.15.30. Use available host capabilities and the fallbacks in PORTABILITY.md; do not claim unavailable tools, subagents, or runtime evidence.

# Statechart

The chart shows what an app's user sees. A PM reads it to decide whether that behavior is right. Label each state with what is on the screen, such as "Paying". Label each step with what the user does or sees happen, such as "tap Pay" or "the charge goes through". Keep variable and action names out of labels. The scripts call this user the reader, as in `readerActions` and reader steps.

Run `node <skill dir>/scripts/statechart.mjs --help` for the commands and for how to read a chart. Work in a scratch folder outside the repo. The command writes its files next to its input.

## Pick the direction

Use `from-spec` when a TLA+ model exists or the code is concrete enough to model. Use `from-chart` when there is no model and the PM should agree on the behavior before anyone writes or changes the code.

If the code already has a TLA+ spec, start from a copy of that spec. Add the variables the user sees, and keep the spec's existing invariants. To audit the code against that spec, make the copy model what the code does, and pass the spec unchanged as `--against`. Check it with the config that its authors say it passes, and pass that config as `--against-config` unless it has the spec's file name. One mapping labels both models, so label states and steps only from variables that both have. In a code model or a new spec, tie every variable and action to code that a reviewer can open, and take its name from that code. Make each action one indivisible step in the code. Put the file and line of the code that checks each condition of an action in a comment on that condition, as in `\* pay.ts:120`.

# Swarm

1. Define a partition with minimal shared mutable state and one owner per slice.
2. Give every worker exact scope, output schema, evidence requirements, and stop condition.
3. Use isolated `delegate` workers when available. If not, execute slices sequentially and label the fallback.
4. Collect artifacts and evidence, not only prose summaries.
5. The parent reconciles overlap, conflicts, and missing coverage, then independently checks high-impact findings or integrations.
6. Return one deduplicated result and a coverage map.

# Test-Driven Development (TDD)

1. Understand the exact requirement or bug and identify the narrowest executable check.
2. Write the failing test first. Ensure it fails for the expected reason, not a setup or syntax error.
3. Implement the minimal production code needed to make the failing test pass. Avoid speculative features.
4. Re-run the test to confirm green.
5. Refactor: clean up names, remove duplication, and simplify structure while keeping tests green.
6. Verify adjacent tests and broader contracts to ensure no regressions.

# Teach

1. Run the substance of `how` and, when historical rationale matters, `why`.
2. Start with the smallest mental model that predicts behavior.
3. Add one layer at a time: actors/data, control flow, invariants, edge cases, then rationale/tradeoffs.
4. Use tiny diagrams and concrete examples that can be checked against the code.
5. End with a few prediction questions or "what would happen if" cases that test understanding, with answers only when useful.

# Technical Writing

1. Identify the reader and the action/decision the document should enable.
2. Put prerequisites and outcome before implementation history.
3. Use task-oriented sections for procedures, concept-oriented sections for mental models, and reference tables only for lookup material.
4. Keep terminology stable and sentences concrete. Define unavoidable jargon once.
5. Examples must be runnable or explicitly illustrative. Never fabricate commands, links, benchmarks, or compatibility claims.
6. For change documents, include impact, design/behavior, verification, migration/rollback if relevant, and open risks.

# TypeScript Best Practices

- Parse unknown external data at the boundary; keep `unknown` until validated.
- Prefer discriminated unions for mutually exclusive states and exhaustive handling for closed variants.
- Give domain meaning to primitives when accidental mixing would be costly.
- Avoid widening useful literal information and avoid `any` as an escape hatch.
- Let callers consume one coherent return shape instead of correlated optional fields.
- Use generics only when they express a real relationship between inputs and outputs.
- Keep async/error states explicit at the public boundary.
- Test behavior through exported APIs, not private helper choreography.

# Unslop

1. Scan text and code comments for AI tells: vague attributions, superficial -ing clauses, throat-clearing intros, and repetitive summaries.
2. Remove filler, passive voice, and conversational bloat.
3. State facts, changes, and instructions directly and concisely.
4. Retain technical precision, file links, concrete numbers, and reproduction steps.
5. Audit the final text: ensure every sentence delivers direct information.

# Why

Recover rationale without inventing intent.

1. State the exact decision whose rationale matters.
2. Discover available evidence sources. Prefer source history, code review/PRs, issues, design docs, chat, observability, and analytics in roughly that order of directness for the claim at hand.
3. If `search`/connected systems and `delegate` exist, query independent evidence categories in parallel. Otherwise search sequentially.
4. Separate contemporaneous evidence from later interpretation. A current comment is not proof of an old motive.
5. Triangulate at least two sources for strong intent claims when possible.
6. Return: decision, strongest evidence, inferred rationale, alternatives considered if evidenced, what changed since, and unresolved uncertainty.