pstack: add figure-it-out and show-me-your-work skills (#78)

* pstack: add figure-it-out and show-me-your-work skills

* pstack: plain-spoken decision log template + guidance

* pstack: add end-of-run transcript audit to show-me-your-work

* pstack: figure-it-out adds designed workflow as todos with woven logging

* pstack: prove-it-works gains script-the-check verification practice

* pstack: header-only decision log template + unslop pass on the new skills

* pstack: strengthen figure-it-out routing and show-me-your-work triggers

pstack/README.md

@@ -55,6 +55,8 @@ the rest are useful when you want to specifically invoke them:
 | `/reflect` | a long task landed and you want the recipe captured as a skill edit. |
 | `/tdd` | you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix. |
 | `/typescript-best-practices` | you're reading or editing typescript. grounds the type-system-discipline principle in syntax. |
+| `/figure-it-out` | no bundled playbook fits. designs a rigorous, auditable playbook for the task. |
+| `/show-me-your-work` | you want a reviewable decision trail. logs decisions to a tsv you can commit. |
 | `/unslop` | you're cleaning up writing. removes AI tells. |
 
 ### examples

pstack/skills/figure-it-out/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: figure-it-out
+description: "Design a rigorous, auditable playbook for a task too large or cross-cutting for a single bundled playbook, or that no playbook fits: a migration across many call sites, an ambitious multi-part change, novel or ambiguous multi-phase work, or anything a human reviews after stepping away. Scales rigor to the task and biases toward more, runs a hypothesis-driven loop, and keeps a decision trail via show-me-your-work. Use for /figure-it-out, 'figure it out', a large migration, or when no narrower playbook is a good fit."
+disable-model-invocation: true
+---
+
+# Figure it out
+
+When the task matches no playbook, design one. The deliverable before any code is the workflow itself: a sequence of phases that scales rigor to the task, runs the scientific method, and leaves a decision trail a human can audit after stepping away. Bias toward more rigor. The cost of building the wrong thing dwarfs the cost of being careful.
+
+Don't reinvent a playbook you already have. A focused single-unit task that matches Bug fix, Perf, Feature, Visual parity, Eval, or Multi-phase plan routes there. But a large or cross-cutting version of one (a migration across many call sites, an ambitious multi-part change), or work the user reviews after stepping away, belongs here even though a single-unit version would be a Feature. The rigor and the audit trail are the point.
+
+## Start
+
+Open a todolist whose first item is to read the Principles section of the **poteto-mode** skill. Then add the phases below as todos.
+
+## Phase A: Frame
+
+Ground first, then commit. Don't start the run until you can state:
+
+- The definition of done as a falsifiable predicate (the **prove-it-works** principle skill). "Done well" has to be checkable.
+- Scope, quantified: rough units and effort, plus the blockers grounding surfaced. Raise them before spending hours, not after fifty doomed commits.
+- The rigor level, biased high. One-way doors and high blast radius get more; reversible low-stakes steps get less. Rigor is gates and artifacts, not "try harder".
+
+Present the framing and tradeoffs before committing to a long run. Reversible work proceeds (the **never-block-on-the-human** principle skill), but a multi-hour run earns one checkpoint.
+
+## Phase B: Design the workflow
+
+Decompose into atomic, independently-landable units. Sequence riskiest-unknown-first so option value stays high. Scaffold and verification come before features (the **foundational-thinking** principle skill).
+
+- Build the verification harness before the work, with the baseline captured from the pre-change state, so the check reads as "old value vs new value".
+- For one-way-door design decisions, run the **architect** skill (it runs **arena**) with diverse, isolated, opinionated candidates and a read-only judge on a different model family. Skip it for mechanical work whose shape is already concrete. A second arena over a settled design is over-engineering (the **laziness-protocol** principle skill).
+- Decide what fans out. Parallelize only across genuine seams, and give each worker its own worktree or branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan.
+- Write the designed phase list down. That list is what the human reviews.
+
+Then put the design into motion. Add its steps to the todolist as concrete items, after the Phase C entry and before Phase D. Run each under the Phase C loop discipline, and weave the Phase D log through them, a row as each step lands, rather than saving the whole trail for the end.
+
+## Phase C: Run the loop
+
+Each unit is an experiment: state the hypothesis, make the smallest change, measure against the predicate on the real artifact, keep it if it advanced, revert it if it didn't.
+
+- Verify by inspecting the artifact, never a self-report. When something passes too easily, suspect the observation method before the system. A blank screenshot passes a lazy gate.
+- Pair delegated work with a judge and audit the delegates' artifacts yourself before trusting them. If a worker games the gate, reset and harden the contract. If the gate itself is wrong, fix the gate in its own change rather than routing around it.
+- A verdict is VERIFIED, NOT VERIFIED, or INCONCLUSIVE. Inconclusive is not a pass. Don't hide a negative.
+
+## Phase D: Keep the audit trail
+
+Log the run via the **show-me-your-work** skill, one canonical TSV with a row per decision and per unit, evidence as links. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR; commit it when confidence has to be shown. Prefer evidence produced by committed scripts so a reviewer can re-run it. The trail plus the diff is what lets the human come back and trust the work.
+
+## Phase E: Verify and hand back
+
+Check the whole against the Phase A predicate on the real product, not just the harness. Encode any recurring correction as a gate, a lint rule, a check, or a script, so the win can't silently regress (the **encode-lessons-in-structure** principle skill).
+
+**Reply:** the playbook you designed, the rigor level and why, the decision-trail path, what's verified against the predicate, and what's still open.

pstack/skills/poteto-mode/SKILL.md

@@ -22,6 +22,7 @@ The remaining triggers live only here:
 - Shipping UI / IDE / CLI → use the matching control skill for your surface. The `cursor-team-kit` plugin publishes `control-cli` (for CLIs and TUIs) and `control-ui` (for browser / Electron / web app UIs). For bug fixes you reproduce first on the same surface yourself; hand it to the user only under the narrow exception in Bug fix step 1.
 - After opening a PR → Cursor's built-in **babysit** skill.
 - Broken skill mid-task → fix it in its own PR. Don't block. Don't silently work around it.
+- Long, autonomous, or multi-phase work, or any task the user steps away from to review later ("going to bed", "trust it when i'm back", "/loop until X") → keep a decision trail via the **show-me-your-work** skill. Commit it when the stakes need an auditable record; keep it local otherwise.
 
 ## Principles
 
@@ -100,6 +101,8 @@ Your first todolist actions are the matched playbook's steps, copied in verbatim
 
 Match the task to a playbook below, open its file, and copy its steps into your todolist verbatim before reasoning about the task.
 
+A large or cross-cutting effort (a migration across many call sites, an ambitious multi-part change), or work the user steps away from to trust later, routes to the **figure-it-out** skill even when a narrower playbook like Feature looks like a fit. Use **figure-it-out** whenever no bundled playbook is a good fit. It designs a bespoke, rigorous playbook for the task.
+
 - **Investigation.** A read-only question: how does X work, why was Y built this way, are we sure about Z, should we do X or Y. Full steps: `playbooks/investigation.md`.
 - **Bug fix.** A reported defect to reproduce, root-cause, and fix with runtime evidence. Full steps: `playbooks/bug-fix.md`.
 - **Perf issue.** A measured slowness to trace and improve against a baseline. Full steps: `playbooks/perf-issue.md`.

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, and discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride.
-4. Checkpoint every iteration in one line: what changed and whether the predicate moved. A run with no trail can't be audited or resumed.
+4. 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.
 5. Stop when the predicate is met, or when two consecutive iterations make no progress. You are stuck then; surface it, don't spin. Never relax the predicate to declare victory.
 
 **Reply:** the exit condition, iterations run, what landed, what was discarded, final predicate state.

pstack/skills/poteto-mode/references/plan.md

@@ -99,6 +99,7 @@ In the overview, name which poteto-mode non-negotiables the implementer must app
 - the **how** skill over each unfamiliar subsystem before changing it.
 - the **interrogate** skill for adversarial review on contested designs before shipping.
 - `/deslop` over each diff before commit. the **unslop** skill over any prose surface.
+- the **show-me-your-work** skill to keep a decision trail when the plan is large enough to need an auditable record.
 - Cursor's built-in **babysit** skill after opening the PR.
 
 ## 7. Hand back

pstack/skills/principle-prove-it-works/SKILL.md

@@ -25,3 +25,9 @@ Code and features:
 
 Delegation: trust artifacts, not self-reports.
 When verifying delegated work, inspect the actual output artifact (git diff, file contents, runtime behavior), not the delegate's summary. Agents report what they intended, not always what happened.
+
+## 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. A script comparing the old and new compiled output catches what a glance misses.
+
+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). Most work just needs it visible, not committed.

pstack/skills/show-me-your-work/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: show-me-your-work
+description: "Keep a reviewable decision trail for non-trivial, long-running, or unattended work. A TSV log with one row per decision (what, why, evidence, result). Kept local by default; commit it for ambitious, high-stakes work where a reviewer needs the trail to trust the result (a large port, a multi-week migration), where GitHub renders it as a table. Use for /show-me-your-work, autonomous or multi-phase runs, or work a human reviews after stepping away. Composed by figure-it-out, autonomous-run, and multi-phase plans."
+disable-model-invocation: true
+---
+
+# Show me your work
+
+For work a human reviews after the fact, a decision trail lets them reconstruct what was decided, why, and on what evidence, without rerunning the work or reading the whole transcript. Keep one canonical log so the trail is consistent and a future agent can find it.
+
+## The format
+
+A single TSV file, one row per decision. TSV because GitHub renders it as a sortable table, `column -s$'\t' -t` and spreadsheets read it, and a row appends with one command. Cells stay single-line. Evidence is a pointer, not prose.
+
+Copy `references/decision-log-template.tsv` (the header row) to start a clean log. Columns:
+
+- **ts.** ISO8601 timestamp. The timeline axis.
+- **phase.** The phase or workstream.
+- **decision.** What was chosen or done, one line.
+- **why.** The reason in plain words. If a principle drove it, say it plainly (`explored options first, this was a one-way door`), not as a jargon tag.
+- **evidence.** A link or path that proves it: commit SHA, PR number, `file:line`, or an artifact, trace, or screenshot path. Never a paragraph.
+- **result.** The outcome or predicate state: `tests green`, `reverted`, `pixel-diff 0`, `INCONCLUSIVE`, `open`.
+
+An example, plain-spoken so a reviewer reads it at a glance. This is illustration only; don't copy these rows into a real log.
+
+```
+ts	phase	decision	why	evidence	result
+2026-05-24T09:02:00Z	frame	counted the work first, about 100 components and roughly 75 hours	wanted to know the size before starting a long run	commit 3a9f1c2	found 5 things to sort out before starting
+2026-05-24T09:40:00Z	harness	took screenshots of the old version before changing anything	so we can compare old against new and catch any visual change	scripts/snapshot.sh, baseline/	saved 120 reference screenshots
+2026-05-24T11:15:00Z	widget	moved the widget styles over without changing how it looks	keep the change small and the result identical	commit 7c21e0a, pixel-diff 0	looks identical, tests pass
+2026-05-24T12:30:00Z	widget	threw out a helper's work because its screenshots were blank	checked the real files instead of trusting its summary	worktree reset	reverted, tightened the instructions for next time
+```
+
+## Logging a row
+
+Write each entry the way you'd tell a teammate what you did. Plain words, concrete actions, no AI speak or abstract jargon (the **unslop** skill applies to log text too). A reviewer should understand each row without decoding it.
+
+Use the helper so rows stay well-formed: `scripts/log.sh <logfile> <phase> <decision> <why> <evidence> <result>`. It stamps `ts`, writes the header on first use, and strips stray tabs. A bare `printf` appending a row works too.
+
+Log decision points and checkpoints, not every action: a fork chosen, a unit completed with its verification result, a pivot or revert with its trigger, a blocker surfaced, a gate fixed. For loop runs, one row per iteration. Skip the trivial and self-evident.
+
+## Where it lives
+
+By default the log is a working artifact, not committed. Keep it at `decisions.tsv` in the work dir, or `.audit/<task-slug>.tsv` when several efforts run at once, and leave it out of git. Most work doesn't need a committed trail; the local log still keeps the run honest and can be discarded after.
+
+Commit it only when the work is ambitious enough that a reviewer needs the trail to trust the result: a large cross-language port, a multi-week migration, anything where confidence has to be shown rather than assumed. A committed log renders as a table in the PR.
+
+## Rules
+
+- One row is one decision or checkpoint. If it doesn't fit on one line, the decision isn't crisp yet.
+- Append-only. A wrong call gets a new row that supersedes it. Never edit or delete history.
+- Prefer evidence produced by committed scripts over hand-made one-offs, so a reviewer can re-run it (the **encode-lessons-in-structure** principle skill).
+
+## Audit the log against the transcript
+
+At the end of the run, before handing back, check the log told the truth. Read this run's transcript under the active workspace's `agent-transcripts/` directory (the system prompt names the path). Don't glob across `~/.cursor/projects/*/`; that reads unrelated private chats. Walk the log against what actually happened:
+
+- Every row maps to a real action. Cut invented or aspirational entries.
+- Each row's evidence resolves and shows what the row claims.
+- A fork, pivot, or abandoned approach that shaped the work but isn't logged is a gap. Add it.
+- Drop padding. If nobody would audit a row, it doesn't earn its place.
+
+Fix the log, not the story. If the work diverged from what a row claims, the row is wrong.
+
+## Reviewing the trail
+
+Read top to bottom, follow the evidence pointers, spot-check. GitHub renders a committed TSV as a table; `column -s$'\t' -t decisions.tsv` renders it in a terminal. A row whose evidence doesn't resolve, or whose result is unverified, is the audit catching a gap.
+
+## Composing this skill
+
+Other skills route their audit trail here instead of inventing one. Reference it by name and let it own the format; don't restate the columns.

pstack/skills/show-me-your-work/references/decision-log-template.tsv

@@ -0,0 +1 @@
+ts	phase	decision	why	evidence	result

pstack/skills/show-me-your-work/scripts/log.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+# Append a well-formed row to a show-me-your-work decision log (TSV).
+# Usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>
+set -euo pipefail
+
+if [ "$#" -ne 6 ]; then
+	printf 'usage: log.sh <logfile> <phase> <decision> <why> <evidence> <result>\n' >&2
+	exit 1
+fi
+
+logfile="$1"
+shift
+
+if [ ! -f "$logfile" ]; then
+	printf 'ts\tphase\tdecision\twhy\tevidence\tresult\n' > "$logfile"
+fi
+
+ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+clean() { printf '%s' "$1" | tr '\t\n' '  '; }
+printf '%s\t%s\t%s\t%s\t%s\t%s\n' \
+	"$ts" "$(clean "$1")" "$(clean "$2")" "$(clean "$3")" "$(clean "$4")" "$(clean "$5")" \
+	>> "$logfile"