From 4d878d5920c94379d22677a012806d523ceebe84 Mon Sep 17 00:00:00 2001 From: Julian le Roux <78623349+julerex@users.noreply.github.com> Date: Wed, 21 Oct 2026 14:06:53 +0200 Subject: [PATCH] Teach port and smoke proof in the pstack workflow skills. Guest logs, cross-target checks, and composite device tables were treated as delegate summaries. These edits make the next port read the artifact and keep failed premises out of the tree. Co-authored-by: Cursor --- pstack/skills/architect/SKILL.md | 2 ++ pstack/skills/arena/SKILL.md | 2 +- pstack/skills/figure-it-out/SKILL.md | 6 ++++-- pstack/skills/how/SKILL.md | 2 +- pstack/skills/poteto-mode/SKILL.md | 2 ++ pstack/skills/poteto-mode/playbooks/feature.md | 2 +- pstack/skills/principle-attack-the-premise/SKILL.md | 2 +- pstack/skills/principle-laziness-protocol/SKILL.md | 1 + pstack/skills/principle-model-the-domain/SKILL.md | 2 ++ pstack/skills/principle-prove-it-works/SKILL.md | 5 ++++- pstack/skills/principle-sequence-verifiable-units/SKILL.md | 4 ++-- 11 files changed, 21 insertions(+), 9 deletions(-) diff --git a/pstack/skills/architect/SKILL.md b/pstack/skills/architect/SKILL.md index 88e23ca10..ea870ecbb 100644 --- a/pstack/skills/architect/SKILL.md +++ b/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. +When an image combines multiple devices on one bus, validate interrupt and scheduling tables for that composition. Do not copy them from a standalone image of one of the devices. + Skip Phase A only when the work is genuinely greenfield with no surrounding system to integrate. ## Phase B: Sketch diff --git a/pstack/skills/arena/SKILL.md b/pstack/skills/arena/SKILL.md index b198b9e42..b32b75619 100644 --- a/pstack/skills/arena/SKILL.md +++ b/pstack/skills/arena/SKILL.md @@ -12,7 +12,7 @@ Open a todolist with one entry per phase (Frame, Fan out, Cross-judge, Pick, Gra Every candidate gets the same prompt, so the prompt is the contract. -1. State the artifact each candidate is producing. +1. State the artifact each candidate is producing. Write the shared grounding before the runners start. Name which features split host or generator tables from the default build the other consumers compile. State the invariants that are already true in the tree, including what the generator emits today and which metadata is stale. 2. Derive the rubric, 3-6 concrete gradeable criteria for what success looks like on *this* task. It is the picker's tool in Phase D. Candidates only see the task. 3. Pick the runners. Use the `arena runners` line in `~/.cursor/rules/pstack-models.mdc`. If the rule or that line is missing, default to one each on `claude-opus-5-5-xhigh` and `grok-4.7-xhigh-fast`. An `auto` or `inherit-parent` entry in this line or the cross-judge line means the parent model, so omit `model` for it. If the Task tool rejects a configured entry, run that seat on its family's default and say so. Families go by prefix: `claude-*`, and `grok-*` with `cursor-grok-*` and `composer-*`. A refused `composer-*` entry runs on `grok-4.7-xhigh-fast`. With no family match, use `claude-opus-5-5-xhigh`. If it rejects a default, use the closest valid slug of the same family from its error message. Spawn more runners when the arena covers multiple design directions. Use the same model N times when the work is generation-bound rather than judgment-sensitive. Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section of the **poteto-mode** skill. 4. Give each candidate its own output location (a git worktree where possible, otherwise `/tmp/arena-/candidate-/`), per the **separate-before-serializing-shared-state** principle skill. diff --git a/pstack/skills/figure-it-out/SKILL.md b/pstack/skills/figure-it-out/SKILL.md index 0d04c2e69..3f09f8160 100644 --- a/pstack/skills/figure-it-out/SKILL.md +++ b/pstack/skills/figure-it-out/SKILL.md @@ -30,6 +30,7 @@ Decompose into atomic, independently-landable units. Sequence riskiest-unknown-f - 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. - Write the designed phase list down. That list is what the human reviews. +- When the unknown is operational (reset behavior, interrupt routing, capture plumbing), run a small host-side probe before a large delegated smoke. 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. @@ -40,13 +41,14 @@ Each unit is an experiment. State the hypothesis, make the smallest change, meas - Verify by inspecting the artifact, never a self-report. When something passes too easily, suspect the observation method before the system. - Pair delegated work with a judge. 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. +- Serialize jobs that invoke the same build driver against one target directory. Isolate host-only tests with a separate target directory when delegates run in parallel. ## Phase D: Keep the audit trail -Log the run via the **show-me-your-work** skill. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR. The trail plus the diff is what lets the human come back and trust the work. +Log the run via the **show-me-your-work** skill. figure-it-out's work is usually ambitious enough to commit the trail so the reviewer can read it in the PR. The trail plus the diff is what lets the human come back and trust the work. Cancelling this phase requires an explicit operator waiver. Otherwise commit the trail, or the equivalent show-me-your-work record, before handoff. ## 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 (the **encode-lessons-in-structure** principle skill). +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). When exploration proves configuration metadata is stale relative to the generator, leave a forward pointer: an issue, a plan note, or a decision record. **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. diff --git a/pstack/skills/how/SKILL.md b/pstack/skills/how/SKILL.md index 67edc340d..1f392fc33 100644 --- a/pstack/skills/how/SKILL.md +++ b/pstack/skills/how/SKILL.md @@ -25,7 +25,7 @@ Decompose the question into 2 to 4 angles, each a distinct slice of the subsyste ## 3. Synthesize (complex only) -Once all explorers have returned, spawn one explainer with `references/explainer-prompt.md` and every explorer's findings filled in. +Once all explorers have returned, harvest each explorer's final report into one scratch file by path, then point the explainer at that file only. Reconcile each explorer claim against a traced call path, the generator entry versus config-only strings, before synthesis. Spawn one explainer with `references/explainer-prompt.md` and that scratch file filled in. ## 4. Present diff --git a/pstack/skills/poteto-mode/SKILL.md b/pstack/skills/poteto-mode/SKILL.md index 21993f546..b6bb4cc26 100644 --- a/pstack/skills/poteto-mode/SKILL.md +++ b/pstack/skills/poteto-mode/SKILL.md @@ -92,6 +92,8 @@ Read the leaf skill in full for any principle you apply. Each entry names when i **Use `subagent_type: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). The chat that receives `/poteto-mode` runs the playbook. Never spawn a `poteto-agent` to run the playbook itself. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`, `swarm`) set their own `subagent_type` for diverse-model review. Respect what the skill prescribes, don't override to `poteto-agent`. +**Ports of a context switch.** Match the recorded upstream register layout. Stop if that pin cannot be found. Prove the switch with the project's canonical log strings. + **Defaults for every `Task` call.** `run_in_background: true`, agent mode (readonly strips MCP), file pointers not inlined context, explicit model per role (configurable via `/setup-pstack`. Defaults `grok-4.7-xhigh-fast` for code, `claude-opus-5-5-xhigh` for prose and judgment). Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (`claude-opus-5-5-xhigh`), whether the task needs judgment on vague intent or is a precisely specified sequence of steps to execute to the letter. Trivial mechanical edits go to your fast code model. Per-role lines in the `/setup-pstack` rule override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`). A role with no line keeps its default, and a role line of `inherit-parent` or `auto` runs that role on the parent chat model (omit Task `model`). Each code playbook's configured model comes from its line (`feature, refactoring`, `bug-fix`, `perf-issue`, or `hillclimb`), and the hardest changes read `hardest tasks`. Prose and judgment read `judgment and prose`. **Match the model to the job.** Before each spawn, start from the role's line or default and pick the reasoning level and speed the job needs. The `/setup-pstack` budget sets each role's starting level, xhigh by default. Raise it one step, up to max, for the hardest or subtlest work. Lower it one step for judgment and two or more steps for routine work. Use fast mode only when the job is urgent, meaning CI or trunk is red or a person is blocked on the result right now. Otherwise use standard speed, the same slug without `-fast`. Verification is the exception and stays on the `swarm workers` model and speed (`grok-4.7-xhigh-fast` by default). Change only the effort level and whether the slug is fast, and keep the family the role names, so a diverse panel stays diverse. If the family has no slug at that level and speed, use its nearest slug. A role on `auto` or `inherit-parent` stays on the parent model. If the Task tool rejects the adjusted slug, do not try another adjusted slug. Use the role's line or default and say so. diff --git a/pstack/skills/poteto-mode/playbooks/feature.md b/pstack/skills/poteto-mode/playbooks/feature.md index eb1040cb2..b4432d286 100644 --- a/pstack/skills/poteto-mode/playbooks/feature.md +++ b/pstack/skills/poteto-mode/playbooks/feature.md @@ -10,7 +10,7 @@ - **Shared mutable state.** Default to splitting the target (the **separate-before-serializing-shared-state** principle skill). Serialize only for real invariants. - **Smallest safe decomposition.** If one worker is best, name why. 4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.7-xhigh-fast`) with a specific scope (file paths, named data shape and its organizing structure per **principle-model-the-domain**, a state machine over scattered booleans, a table/registry over branching, a typed model over repeated shape assumptions, chosen before the delegate writes logic, and success criteria). Pick each subagent's reasoning level and fast or standard speed for the job, per the Subagents section. When the implementation admits multiple valid shapes (error handling, abstraction layer, test structure), delegate via the **arena** skill instead so the runners surface the alternatives and the cross-judge guards the pick. Mandatory: no skip-with-reason escape, and Laziness Protocol does not override it (the gain is review separation, not lines saved). A subagent forbidden to spawn satisfies this by owning the diff directly with the same review separation. No "standing by" reply that waits on a nested agent. Comments per **Comments**. Surgical edits, re-ground against the source for upstream-derived files. Port shared-primitive improvements to all consumers and verify each. Commit liberally. -5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass. Flag it. +5. Verify on the matching surface. "Inconclusive" or wrong-surface is not a pass. Flag it. After any delegate or smoke, read the serial log or equivalent capture for the expected strings before advancing the checkpoint. Do not mark the work done, push it, or update a plan status until the host check and the cross-target protection-domain check both exit zero on the same tree. 6. Rebase into small, ordered commits. Stack follow-ups. Use the **sequence-verifiable-units** principle skill, building, verifying, and committing each small unit before the next. 7. If the design is contested, `interrogate` before shipping. diff --git a/pstack/skills/principle-attack-the-premise/SKILL.md b/pstack/skills/principle-attack-the-premise/SKILL.md index e9a6d4996..7b28150b9 100644 --- a/pstack/skills/principle-attack-the-premise/SKILL.md +++ b/pstack/skills/principle-attack-the-premise/SKILL.md @@ -16,6 +16,6 @@ When two or more fixes that share one premise have failed the same gate, suspect - **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. +**Stop:** Do not start the next fix before the premise is written down and tested. When the investigation moves to a new premise, revert or drop the edits that only served the discarded premise before the next smoke. 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. diff --git a/pstack/skills/principle-laziness-protocol/SKILL.md b/pstack/skills/principle-laziness-protocol/SKILL.md index 016c3c7c8..5c11f7b09 100644 --- a/pstack/skills/principle-laziness-protocol/SKILL.md +++ b/pstack/skills/principle-laziness-protocol/SKILL.md @@ -8,3 +8,4 @@ disable-model-invocation: true - **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. +- **Parameterize the boundary.** When a queue or config struct has no address or transport field, change the machine description and the device backends. Do not add a parallel role graph per architecture. diff --git a/pstack/skills/principle-model-the-domain/SKILL.md b/pstack/skills/principle-model-the-domain/SKILL.md index 09b7c7399..de7c6bfec 100644 --- a/pstack/skills/principle-model-the-domain/SKILL.md +++ b/pstack/skills/principle-model-the-domain/SKILL.md @@ -21,4 +21,6 @@ Reach for: 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. +When one table cannot express rules that depend on which devices share a bus, write those rules as explicit invariants of the image kind. Leave them out of scattered one-off branches. + 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. diff --git a/pstack/skills/principle-prove-it-works/SKILL.md b/pstack/skills/principle-prove-it-works/SKILL.md index 5dc14a3b0..d7d81eb49 100644 --- a/pstack/skills/principle-prove-it-works/SKILL.md +++ b/pstack/skills/principle-prove-it-works/SKILL.md @@ -6,7 +6,7 @@ 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." +Verify every task output by checking the real thing directly. Do not infer from proxies, self-reports, or "it compiles." For a firmware or multi-architecture port, a guest smoke is necessary and it is not sufficient until the cross-target protection-domain check has finished green. **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. @@ -14,6 +14,9 @@ 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 +- Grep the captured serial transcript for the load-bearing strings. A delegate summary is not the transcript. +- A recipe exit code is unreliable when the shell pipeline ends in `tail` or `echo`. Read the recipe status line and the log. +- A subagent completion notice is a prompt to read the log, not a pass. ## Script the check when you can diff --git a/pstack/skills/principle-sequence-verifiable-units/SKILL.md b/pstack/skills/principle-sequence-verifiable-units/SKILL.md index 986371260..b09df9814 100644 --- a/pstack/skills/principle-sequence-verifiable-units/SKILL.md +++ b/pstack/skills/principle-sequence-verifiable-units/SKILL.md @@ -10,8 +10,8 @@ Order work as a sequence of small units, each ending in a state you can check, a **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. +**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. Before scheduling a role on a new architecture, grep for compile gates and which protection domains link the dependency, and order units behind that proof. Close a unit with host tests that compare rendered artifacts, including an unchanged baseline architecture, before the next unit's guest smokes. -**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. +**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. Multi-unit work commits or opens a pull request per green unit unless the operator explicitly defers landing. 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.