Record unsafe-migration lessons in the workflow skills

cursor-team-kit/skills/deslop/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: deslop
-description: Remove AI-generated code slop and clean up code style
+description: "Remove AI-generated code slop and clean up code style. Before commit, align the pull request title and scope with the falsifiable done predicate, so a harness-only change is not described as the finished migration."
 ---
 
 # Remove AI code slop
@@ -14,6 +14,7 @@ Check the diff against main and remove AI-generated slop introduced in the branc
 - Casts to `any` used only to bypass type issues
 - Deeply nested code that should be simplified with early returns
 - Other patterns inconsistent with the file and surrounding codebase
+- A pull request title or scope that claims the finished migration while the falsifiable predicate is still a harness, an allowlist, or an unwired library
 
 ## Guardrails
 

cursor-team-kit/skills/fix-ci/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fix-ci
-description: Find failing PR checks, inspect logs or external check links, and apply focused fixes
+description: "Find failing pull request checks, inspect logs or external check links, and apply focused fixes. When a check excerpt or shared pull request context already names the failing paths, fix from that evidence. Reserve a parallel investigator per check for ambiguous or multi-root failures."
 ---
 
 # Fix CI
@@ -21,6 +21,7 @@ Branch or PR CI is failing and needs a fast, iterative path to green checks.
 - Fix one actionable failure at a time.
 - Prefer minimal, low-risk changes before broader refactors.
 - Keep `gh pr checks` as the source of truth for overall PR CI state.
+- When the check excerpt already names the failing files, fix from that excerpt. Spawn one investigator per check only when the failure is ambiguous or has more than one root.
 
 ## Output
 

cursor-team-kit/skills/verify-this/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: verify-this
-description: "Verify a claim with fresh local evidence: restate it falsifiably, capture baseline and treatment, compare artifacts, and return VERIFIED, NOT VERIFIED, or INCONCLUSIVE."
+description: "Verify a claim with fresh local evidence: restate it falsifiably, capture baseline and treatment, compare artifacts, and return VERIFIED, NOT VERIFIED, or INCONCLUSIVE. Use when sizing or gating on the unsafe keyword, and count with a comment- and string-aware scan that treats lifetimes apart from character literals."
 ---
 
 # Verify This
@@ -13,6 +13,7 @@ Verification is not a recap. It proves or disproves a specific claim with repeat
 - A bug fix needs a before/after repro.
 - A UI, CLI, API, performance, or memory claim needs measurement.
 - A test passes but the user-visible behavior still needs confirmation.
+- The claim is a count or a gate on the `unsafe` keyword. Use a comment- and string-aware scan. A lifetime like `'static` is not a character literal, and `UnsafeCell` is not the keyword.
 
 Do not use this for vague claims like "the code is cleaner". Ask for a measurable claim first.
 

pstack/skills/architect/SKILL.md

@@ -22,6 +22,8 @@ Open a todolist with one entry per phase before starting.
 
 Build a real mental model of every system the new code touches. Run the **how** skill over the relevant subsystems. Naming a file isn't grounding. Produce the architectural explanation `how` prescribes. If the design redefines ownership or layering, also run the **why** skill on the existing shape so the rationale becomes a constraint, not a guess.
 
+Before a layout that puts every `unsafe` operation in one file, list the tokens the language pins to an exported item. `no_mangle`, `unsafe extern`, and an `unsafe impl` that orphan rules block on a foreign type stay on that item. The one file owns the dereferences.
+
 Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate.
 
 ## Phase B: Sketch

pstack/skills/architect/references/runner-prompt.md

@@ -13,6 +13,7 @@ Apply the following discipline. The orchestrator compares candidates on these ax
 - Make boundaries visible. `not implemented` errors for bodies, `// TODO` pseudocode for tricky logic, doc comments stating intent and invariants. A reader should trace data from input to output by reading types and signatures alone.
 - Encode invariants in types: hard-to-misuse types > runtime checks > prose comments, per the **encode-lessons-in-structure** principle skill.
 - Validate at boundaries, trust types inside, per the **boundary-discipline** principle skill. Business logic as pure functions. The shell stays thin.
+- When the design hides `unsafe` inside a macro, prove a caller with `forbid(unsafe_code)` still compiles. That compile shows the lint stays quiet at the call site. It does not by itself show a maintainer should extend the shape.
 - Single source of truth per invariant. Derive instead of sync.
 - Idempotent state transitions where applicable, per the **make-operations-idempotent** principle skill. Ask what happens if the operation runs twice or crashes halfway.
 - Short call chains. If tracing the flow needs more than three files, flatten the hierarchy, per the **laziness-protocol** and **minimize-reader-load** principle skills.

pstack/skills/arena/SKILL.md

@@ -33,6 +33,8 @@ Read every candidate end to end before picking. Score each against the rubric cr
 
 Pick the base a future maintainer can extend most easily without breaking invariants. When two feel tied, prefer the cleaner boundary or smaller API, per the Laziness Protocol.
 
+When a rubric criterion depends on compiler or lint behavior, run a minimal compile repro before you let the cross-judge decide that criterion. A prose claim about where a macro's `unsafe` text lands is one of those criteria.
+
 ## Phase E: Graft
 
 Walk each losing candidate once more for what is worth porting into the base, usually one or two things per candidate, not most of it. Fold each graft in by hand, per the **redesign-from-first-principles** principle skill, so the result stays coherent under one mental model. Don't paste mechanically.
@@ -43,6 +45,8 @@ If the candidates converge on one shape, that is strong agreement. Note it and s
 
 Verify the synthesized artifact like any other output, per the **prove-it-works** principle skill. If verification finds a problem the arena missed, either Phase A was wrong (re-frame and re-run) or a candidate caught it and you missed the graft (go back to Phase E). Don't paper over it.
 
+A compile that stays quiet under `forbid(unsafe_code)` shows the call site is lint-quiet. It does not show a maintainer should extend that shape. Say which of the two you measured.
+
 ## Outputs
 
 One synthesized artifact, with a short synthesis note alongside naming the base and why, the cross-judge's verdict, each graft with its source candidate, what was rejected and why, any convergence or dropouts, and the verification result.

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

@@ -19,6 +19,9 @@ 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).
 - Scope, quantified: rough units and effort, plus the blockers grounding surfaced.
 - 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".
+- When done is a mechanical gate, the predicate is that gate's pass or fail on the tree the check scans. A clean compile is not that predicate.
+- An allowlist that freezes today's offenders is interim anti-growth. Say so in the predicate unless it also requires the count to fall, or names the wave that moves callers.
+- A repo-wide sweep of `unsafe` leaves pinned git dependencies and vendor driver crates out of scope. First-party code owns construction, claims, and queue edges.
 
 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.
 
@@ -29,6 +32,7 @@ Decompose into atomic, independently-landable units. Sequence riskiest-unknown-f
 - 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**). 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 seams, and give each worker its own worktree or branch (the **separate-before-serializing-shared-state** principle skill). Don't over-fan. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill.
+- When poteto mode is in play, ad-hoc playbook workers are `poteto-agent`. A routed skill that names another `subagent_type`, such as the how skill's explorers, keeps that type.
 - Write the designed phase list down. That list is what the human reviews.
 
 Then execute the design. Add its steps to the todolist as concrete items between the Phase C and Phase D entries. 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.
@@ -49,4 +53,4 @@ Log the run via the **show-me-your-work** skill. figure-it-out's work is usually
 
 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 (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.
+**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. An opened pull request is not this handback while a predicate is still open, unless the reply defers that predicate in plain words.

pstack/skills/how/SKILL.md

@@ -27,6 +27,8 @@ Decompose the question into 2 to 4 angles, each a distinct slice of the subsyste
 
 Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in.
 
+If an explorer's report is redacted or missing, mark that lane INCONCLUSIVE in the explainer prompt and pass only facts the parent verified. Do not fill the gap with the longest remaining message.
+
 ## 4. Present
 
 Present the explainer's output. Light edits for clarity or context from the conversation are fine. Do not substantially rewrite it.

pstack/skills/poteto-mode/playbooks/opening-a-pr.md

@@ -4,7 +4,7 @@ Invoked at the end of every other playbook.
 
 **Worktree.** Work from a git worktree off main. Subagents inherit it. Multiple `Task` calls on the same branch each get their own worktree, or `git fetch && git reset --hard origin/<branch>` between them. Dirty branch with unrelated work: patch out, fresh worktree, apply. Snarled worktree: reset from main, redo minimally.
 
-**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit. New commit when separable. Commit bodies don't restate the subject.
+**Commits.** Commit liberally. Rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit. New commit when separable. Commit bodies don't restate the subject. A commit that lands a structural gate leaves out audit logs and decision trails unless the user asked for them in that change.
 
 **PRs.** Run `/deslop` from `cursor-team-kit` over the diff before commit and `/no-comments` before review. Write every PR title, description, and commit body with `/technical-writing` (every layer except Diátaxis, and apply the STE vocabulary rules: one word per action, keep articles, a plain verb over `-ing` where one works), then apply `/unslop`.
 

pstack/skills/principle-boundary-discipline/SKILL.md

@@ -23,6 +23,10 @@ Validation and error handling:
 - 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
 
+Unsafe surfaces:
+- A public function that accepts an arbitrary raw pointer fails this boundary even when the `unsafe` block sits in the callee. Name a linker symbol, a claimed window, or a macro whose text lives in the audited file.
+- When the goal is one audited home, compare the reviewer's walk through the macro with the walk through that raw-pointer function. File count alone is the wrong comparison.
+
 Code organization:
 - Business logic in pure functions with no framework dependencies
 - Parse functions: pure transforms from raw bytes to typed state

pstack/skills/principle-guard-the-context-window/SKILL.md

@@ -10,3 +10,4 @@ disable-model-invocation: true
 
 **Pattern:**
 - **Size phases and cap scope.** Limit files per phase, set turn budgets, account for mechanism costs.
+- **Read a subagent report from its transcript.** Concatenate the assistant text parts under `agent-transcripts/<parent>/subagents/<child>.jsonl`. The last line may be a tool call, not the report.

pstack/skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md

@@ -9,6 +9,7 @@ disable-model-invocation: true
 - Update tests to assert the new contract, and delete tests that only protect pre-refactor implementation details
 
 **When this applies:**
+- Landing the new API with no caller moved is a harness step. It does not finish this wave.
 - 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

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

@@ -14,6 +14,7 @@ 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
+- When the claim covers a guest image or a protection domain, run the cross compile, the host check, or the board smoke that matches that blast radius. A host test of a library nothing boots is a smaller claim.
 
 ## Script the check when you can
 

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

@@ -19,7 +19,7 @@ Copy `references/decision-log-template.tsv` (the header row) to start a clean lo
 - **decision.** What was chosen or done, one line.
 - **why.** The reason in plain words. If a principle drove it, say it plainly, 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`.
+- **result.** The outcome or predicate state: `tests green`, `reverted`, `pixel-diff 0`, `INCONCLUSIVE`, `open`. A result cell that cites a count uses the same counting rule as the framing predicate. Do not mix a substring count with a later file count.
 
 An example, plain-spoken so a reviewer reads it at a glance.