pstack: add session-pickup and trace-forensics playbooks (#83)

lauren committed 5 months ago

Commit 0c273941 parent 6b549693 files · +29 −0Browse files

Unified · Split

3 files

skills/poteto-mode/SKILL.md +2 −0
skills/poteto-mode/playbooks/session-pickup.md +13 −0
skills/poteto-mode/playbooks/trace-forensics.md +14 −0

 - **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`.
 - **Runtime forensics.** Diagnosing a runtime symptom (leak, idle-CPU spin, glitch) from live instrumentation; the deliverable is a diagnosis, not a fix. Full steps: `playbooks/runtime-forensics.md`.
+- **Trace forensics.** Diagnosing a captured profiling artifact (cpuprofile, trace, spindump, heap snapshot) handed to you after the fact; the deliverable is a diagnosis, not a fix. Full steps: `playbooks/trace-forensics.md`.
 - **Feature.** New or changed behavior, built from a named data shape. Full steps: `playbooks/feature.md`.
 - **Refactoring.** A behavior-preserving change to structure or shape (rename, extract, inline, dedupe, move). Full steps: `playbooks/refactoring.md`.
 - **Prototype.** A throwaway sketch to make a design decision cheaply before building it for real ("prototype", "mock it up", "try this layout"). Full steps: `playbooks/prototype.md`.
 - **Authoring or modifying a skill.** Writing or editing a SKILL.md. Full steps: `playbooks/authoring-a-skill.md`.
 - **Eval.** Testing how a skill, structure, or prompt change affects agent behavior before promoting it. Full steps: `playbooks/eval.md`.
 - **Autonomous run.** A long task to drive to completion without stopping ("run until done", "/loop until X"). Full steps: `playbooks/autonomous-run.md`.
+- **Session pickup.** Resuming or taking over a prior agent's in-flight work from a transcript, cloud-agent URL, or pushed branch. Full steps: `playbooks/session-pickup.md`.
 - **Multi-phase or multi-PR plan.** Work that spans phases or stacked PRs. Full steps: `playbooks/multi-phase-plan.md`.
 - **Opening a PR.** Invoked at the end of every other playbook. Full steps: `playbooks/opening-a-pr.md`.

skills/poteto-mode/playbooks/session-pickup.md+13−0

@@ -0,0 +1,13 @@
	1	### Session pickup
	2
	3	You own the resume point. Read the prior trail, don't redo it. For "take over this", "resume this conversation", "continue from <transcript path>", "you're taking over", "pick up where X left off", a cloud-agent URL handoff, or a pushed branch you're meant to continue.
	4
	5	A pickup is inheritance. The prior agent already paid the cost of reading the code, running the repros, and making the design choices. Redoing that work loses the bias check the prior trail gives you and burns context on state you already have. Resist the urge to re-derive; read.
	6
	7	1. Locate the prior trail. A local transcript under the active workspace's `agent-transcripts/` directory (the system prompt names the path; do not glob across `~/.cursor/projects//`, that crosses workspace boundaries and reads private chats from unrelated projects), a cloud-agent URL, or a pushed branch. Read the metadata overview and the last messages first, then scan back for the decision points. Parse a long transcript in a subagent and keep the reduced timeline in the main thread (the principle-guard-the-context-window* skill).
	8	2. Reconstruct operational state. The branch and worktree, what already landed (`git log`, `git diff` against the base), the open todos, the decisions already made. The prior trail is authoritative input. Resist the bias to re-derive it.
	9	3. Diff done vs pending. Compare what shipped against what was planned, name the resume point, and do not re-run the prior repro or redo completed work. A "let me verify from scratch" pass is the tell that you're treating the trail as untrustworthy when it's actually authoritative.
	10	4. Route the remaining work to the matching playbook and pick the verdict. Continue the execution, ship a finished recommendation, ratify or override a prior conclusion, or postmortem a failed run. The pickup playbook ends here; the routed playbook owns the rest.
	11	5. Verify the inherited claims against the original goal on the real artifact (the principle-prove-it-works skill). You are inheriting unverified work, and a passing prior self-report is not the proof.
	12
	13	Reply: where the prior agent stopped, what you inherited vs redid (ideally nothing redone), the resume point, and the outcome.

skills/poteto-mode/playbooks/trace-forensics.md+14−0

@@ -0,0 +1,14 @@
	1	### Trace forensics
	2
	3	You own the diagnosis from the artifact. Load it, shape it for analysis, narrow to the cause, attribute to source. For a dropped `.cpuprofile`, `Trace-*.json.gz`, `Spindump.txt`, or `.heapsnapshot` paired with "why is this slow / unresponsive / leaking / crashing".
	4
	5	Distinct from Runtime forensics, which instruments the live process. Here the capture already exists and the live system may be gone; the artifact is a fixed dataset and your job is to read it, not to re-run it. Keep tooling references generic. Use the right tool for the format (a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot), so the playbook stays portable across surfaces.
	6
	7	1. Identify the format and load it with the right tool for that format. Parse large artifacts in a subagent (the principle-guard-the-context-window skill) and keep the reduced finding in the main thread; a multi-megabyte trace inlined into your context is the failure mode.
	8	2. Transform the raw artifact into a form you can query. Dump the trace or heap snapshot into sqlite, one row per sample, frame, or node, so you can aggregate and sort instead of scrolling a huge file by eye. Get to the queryable shape before you start reading.
	9	3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree down to the hot path. For a leak, follow the retainer chain from the leaked object to a GC root. For a spindump, find the thread stuck on-CPU or blocked and its wait reason.
	10	4. Attribute to source. Map the hot frame to file, symbol, and line via the artifact's own symbols. A frame with no source mapping is not yet a diagnosis; resolve the symbols, or say plainly the artifact does not carry them.
	11	5. Confirm against a paired capture when you have one. Diff a before and after artifact so the attribution is the real regression, not background noise. Without a paired capture, mark the finding as the strongest hypothesis the artifact supports, not a confirmed cause.
	12	6. Hand back a cited diagnosis, no fix unless asked. Route to Bug fix or Perf issue once the cause is known. The throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`.
	13
	14	Reply: the artifact and format, the reduced finding, the source location, the artifact paths, and whether a paired capture confirmed it.