diff --git a/docs/guide/01-setup.md b/docs/guide/01-setup.md index 6ab3c2a..122ed4c 100644 --- a/docs/guide/01-setup.md +++ b/docs/guide/01-setup.md @@ -27,7 +27,7 @@ Run: [`/setup-pstack`](../../skills/setup-pstack/SKILL.md) detects the models you have access to, asks for a reasoning budget, shows you each role (code delegates, judgment, the review panels), and asks what you want. Answer the questions. It writes `~/.grok/rules/pstack-models.md`, a small rule every pstack skill reads. -The `large` budget matches the skill defaults: `grok-4.7` for judgment and `grok-4.7-build-fast` for code, when `grok models` lists both. `unlimited` uses the strongest detected slug for every role. `medium` uses `grok-4.6` for judgment when it is detected, and keeps code on the fast slug. `small` uses `grok-4.5` when it is detected, otherwise the cheapest detected slug. Do not invent an effort suffix. If `spawn_subagent` has no `model` argument, `/setup-pstack` sets `[features] subagent_model_inheritance = false` in `~/.grok/config.toml` when no requirements pin or `GROK_SUBAGENT_MODEL_INHERITANCE` blocks it. Role models start in the next session. This session still inherits the parent. +The budgets are `unlimited — max reasoning`, `large — xhigh reasoning`, `medium — high reasoning`, and `small — medium reasoning`. `unlimited`, `large`, `medium`, and `small` set the effort of every real model entry, panel entries included, to `max`, `xhigh`, `high`, or `medium`, on the ladder `max` > `xhigh` > `high` > `medium` > `low`. Effort is a separate field, written after the model id (`grok-4.6 xhigh`). If the model does not offer that effort, use its highest offered effort at or below the target, else mark the role as needing a choice. On grok 1.0.62, `unlimited` keeps `grok-4.6` at `xhigh`, `large` keeps the defaults, and `small` turns them into `grok-4.6 medium` and `grok-4.5 medium`. If `spawn_subagent` has no `model` argument, `/setup-pstack` sets `[features] subagent_model_inheritance = false` in `~/.grok/config.toml` when no requirements pin or `GROK_SUBAGENT_MODEL_INHERITANCE` blocks it. Role models start in the next session. This session still inherits the parent. You only override what you care about. A role with no line in the rule keeps the skill's default. To restore a default, delete that role's line. A rerun of `/setup-pstack` keeps any role whose model differs from the default. When a default changes, a rule written before the change still pins the old default, so delete those role lines, or delete the file, then run `/setup-pstack` again. diff --git a/skills/architect/SKILL.md b/skills/architect/SKILL.md index bcf6835..94d8682 100644 --- a/skills/architect/SKILL.md +++ b/skills/architect/SKILL.md @@ -28,7 +28,7 @@ Skip Phase A only when the work is genuinely greenfield with no surrounding syst Run the **arena** skill with the design-sketch task and the Phase A grounding artifacts. Pass `references/runner-prompt.md` as each runner's prompt. -Take the runners from the `architect runners` line in the `pstack-models.md` rule, in place of the `arena runners` line. If the rule or that line is missing, use `grok-4.7` and `grok-4.7-build-fast`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A. +Take the runners from the `architect runners` line in the `pstack-models.md` rule, in place of the `arena runners` line. If the rule or that line is missing, use `grok-4.6 xhigh` and `grok-4.5 high`. Alias and rejected entries follow the runner rules in the **arena** skill's Phase A. Design it twice. Require at least two structurally distinct candidates before synthesis, even when the first looks sufficient. This is the **exhaust-the-design-space** principle skill made concrete. Whole-shape alternatives, not point fixes inside one shape. diff --git a/skills/arena/SKILL.md b/skills/arena/SKILL.md index b885df5..429cc92 100644 --- a/skills/arena/SKILL.md +++ b/skills/arena/SKILL.md @@ -14,7 +14,7 @@ Every candidate gets the same prompt, so the prompt is the contract. 1. State the artifact each candidate is producing. 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 `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, default to one each on `grok-4.7` and `grok-4.7-build-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 `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Diversity is a different detected slug, not a different vendor. 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. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. +3. Pick the runners. Use the `arena runners` line in `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, default to one each on `grok-4.6 xhigh` and `grok-4.5 high`. An `auto` or `inherit-parent` entry in this line or the cross-judge line means the parent model, so omit `model` for it. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Diversity is a different detected slug, not a different vendor. 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 effort for the job, per the Subagents section. 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. ## Phase B: Fan out @@ -25,7 +25,7 @@ If a candidate produces no output, proceed with N-1 and note the dropout. ## Phase C: Cross-judge -After all Phase B candidates complete, choose one model from the `arena cross-judge pool` line in `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, choose from `grok-4.7` and `grok-4.7-build-fast`. Prefer a detected slug different from the parent's when one exists. Spawn one judge subagent on that model. There is no readonly flag. The prompt forbids file edits. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing. +After all Phase B candidates complete, choose one model from the `arena cross-judge pool` line in `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, choose from `grok-4.6 xhigh` and `grok-4.5 high`. Prefer a detected slug different from the parent's when one exists. Spawn one judge subagent on that model. There is no readonly flag. The prompt forbids file edits. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with your reading in Phase D. Don't spawn it while candidates are still writing. ## Phase D: Pick a base diff --git a/skills/automate-me/SKILL.md b/skills/automate-me/SKILL.md index 4d024db..27c2c39 100644 --- a/skills/automate-me/SKILL.md +++ b/skills/automate-me/SKILL.md @@ -28,7 +28,7 @@ Update mode changes the rest of the flow: Locate the active workspace's transcripts before fanning out. They live under `~/.grok/sessions///chat_history.jsonl`. Percent-encoding turns `/` into `%2F`. `GROK_HOME` overrides `~/.grok`. Use only that workspace directory. Don't glob across `~/.grok/sessions/*/`. That crosses workspace boundaries and reads private chats from unrelated projects. -Survey recent agent conversations within that scope for recurring patterns. Run multiple parallel subagents across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. Each slice mining subagent reads transcripts from the workspace-scoped path the parent provides, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting: +Survey recent agent conversations within that scope for recurring patterns. Run multiple parallel subagents across slices of history (e.g. last 2-4 weeks, split into 3 slices so each has enough material). Pick each subagent's reasoning effort for the job, per the Subagents section. Each slice mining subagent reads transcripts from the workspace-scoped path the parent provides, looks for the signals below, and returns a short structured list of patterns it saw with evidence pointers. Default signals worth hunting: - Response preferences (length, tone, format, "dumb it down" corrections) - Delegation habits (subagents, models, specialized workflows, parallelism) diff --git a/skills/figure-it-out/SKILL.md b/skills/figure-it-out/SKILL.md index 5072415..2d4ff8f 100644 --- a/skills/figure-it-out/SKILL.md +++ b/skills/figure-it-out/SKILL.md @@ -28,7 +28,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. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. +- 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 effort for the job, per the Subagents section. - 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. diff --git a/skills/how/SKILL.md b/skills/how/SKILL.md index e90a1ed..7774169 100644 --- a/skills/how/SKILL.md +++ b/skills/how/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true Explore the codebase to answer "how does X work?" questions. Produce architectural explanations at the level of a senior engineer onboarding onto a subsystem, enough to build a working mental model, not so much that it reads like annotated source code. -Every spawn is a spawn_subagent with omit `subagent_type` and a prompt that forbids file edits (there is no readonly flag). Explorers use the `how explorer` line in the `pstack-models.md` rule (default `grok-4.7-build-fast`), and every explainer uses the `how explainer` line (default `grok-4.7`). Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. +Every spawn is a `spawn_subagent` call with no `subagent_type` and a prompt that forbids file edits (there is no readonly flag). Explorers use the `how explorer` line in the `pstack-models.md` rule (default `grok-4.6` at `xhigh`), and every explainer uses the `how explainer` line (default `grok-4.6` at `xhigh`). Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Pick each subagent's reasoning effort for the job, per the Subagents section. ## 1. Assess complexity diff --git a/skills/interrogate/SKILL.md b/skills/interrogate/SKILL.md index 78c4e6e..f69acab 100644 --- a/skills/interrogate/SKILL.md +++ b/skills/interrogate/SKILL.md @@ -28,14 +28,14 @@ Launch all reviewers in a single message with spawn_subagent, one per entry on t | Subagent | Default model | |----------|---------------| -| Reviewer A | `grok-4.7` | -| Reviewer B | `grok-4.7-build-fast` | +| Reviewer A | `grok-4.6 xhigh` | +| Reviewer B | `grok-4.5 high` | Each reviewer gets omit `subagent_type`, a prompt that forbids file edits (there is no readonly flag), and `model` set to its configured entry, or its table default when there is no configured line. Omit `model` for an `auto` or `inherit-parent` entry, so that reviewer runs on the parent model. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a configured entry, use the closest slug from `grok models` and say so. Prefer a detected slug different from the parent's when one exists. Do not block the review on the slug issue. Never treat an alias entry as a rejected slug. -Read `references/reviewer-prompt.md` and fill in the same template for every reviewer with the stated intent, the diff or file contents, the rubric from `references/rubric.md`, and the code-quality lens from `references/code-quality-review.md`. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. +Read `references/reviewer-prompt.md` and fill in the same template for every reviewer with the stated intent, the diff or file contents, the rubric from `references/rubric.md`, and the code-quality lens from `references/code-quality-review.md`. Pick each subagent's reasoning effort for the job, per the Subagents section. ## Step 4, Synthesize diff --git a/skills/no-comments/SKILL.md b/skills/no-comments/SKILL.md index 79afb13..2133006 100644 --- a/skills/no-comments/SKILL.md +++ b/skills/no-comments/SKILL.md @@ -16,7 +16,7 @@ Use the caller's files or diff. Otherwise use the current diff against the base ## Steps -1. Spawn `spawn_subagent` with `subagent_type: "pstack:comment-sicko"`. Pass the scope. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. Do not restate its rules. +1. Spawn `spawn_subagent` with `subagent_type: "pstack:comment-sicko"`. Pass the scope. Pick each subagent's reasoning effort for the job, per the Subagents section. Do not restate its rules. 2. Inspect its report and diff. Reject application-code edits, scope escapes, exception-protected deletions, misstated `MUST KILL` reasons, and flags that treat kept intentional code as guilty. Reshape flags on our-code surprises stay actionable. Do not restore those comments. A keep survives only with proof it is about something we cannot change. Audit missed scoped lint and TypeScript suppressions. Correctness or safety suppressions stay actionable `MUST KILL`s. Restore deletions only with exact exceptions and scoped proof. Before accepting thin `IMPORTANT` or `do not remove` kills or keeps, run `/how` or `/why` on their symbol. If a kill is ambiguous, do not restore. If a keep is refuted or still ambiguous, delete it. Revert and rerun one rejected report with the failure named. Reject a second, report it open, and fail `/no-comments`. 3. Fix trivial accepted flags directly by deleting a dead path, dropping a parameter, or using the real API. If any fix needs a shape, run `/architect` once for the accepted set and surrounding code. Stop at the sketch. Architect shapes. Step 4 implements. 4. Implement the smallest root-cause fix in scope. Remove every named workaround. If the root cause is out of scope, land the smallest in-scope fix and report the rest open. The **principle-fix-root-causes** and **principle-redesign-from-first-principles** skills guide intent only. Neither authorizes widening the fence nor fixing instances outside it. Never bolt on symptom guards. diff --git a/skills/poteto-mode/SKILL.md b/skills/poteto-mode/SKILL.md index 0944278..20319d0 100644 --- a/skills/poteto-mode/SKILL.md +++ b/skills/poteto-mode/SKILL.md @@ -92,7 +92,9 @@ Read the leaf skill in full for any principle you apply. Each entry names when i **Use `subagent_type: "pstack: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 and is the only chat that may call `spawn_subagent`. A child cannot spawn. Never spawn a `poteto-agent` to run the playbook itself. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`, `swarm`) omit `subagent_type`, or set the type they name. Respect what the skill prescribes, don't override to `poteto-agent`. -**Defaults for every `spawn_subagent` call.** `background: true`. There is no readonly flag. When a child must not edit files, say so in the prompt. MCP stays available through `search_tool` and `use_tool`. Pass file pointers, not inlined context. Pass `model` only when the tool schema includes it. Otherwise omit `model` so the child inherits the parent. If it rejects a slug, use the closest slug from `grok models` and say so. Do not invent an effort suffix. Defaults are `grok-4.7-build-fast` for code and `grok-4.7` 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 (`grok-4.7`), 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 `~/.grok/rules/pstack-models.md` (written by `/setup-pstack`) 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 `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`. When `spawn_subagent` has no `model` argument, omit `model` for this session so every role inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. +**Defaults for every `spawn_subagent` call.** `background: true`. There is no readonly flag. When a child must not edit files, say so in the prompt. MCP stays available through `search_tool` and `use_tool`. Pass file pointers, not inlined context. Pass `model` only when the tool schema includes it. Otherwise omit `model` so the child inherits the parent. If it rejects a slug, use the closest slug from `grok models` and say so. Defaults are `grok-4.6` at `xhigh` for code and 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 (`grok-4.6` at `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 `~/.grok/rules/pstack-models.md` (written by `/setup-pstack`) 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 `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`. When `spawn_subagent` has no `model` argument, omit `model` for this session so every role inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. + +**Match the model to the job.** Before each spawn, start from the role's line or default and pick the reasoning level 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. Verification is the exception and stays on the `swarm workers` model (`grok-4.6 xhigh` by default). Change only the effort and keep the model the role names, so a diverse panel stays diverse. If the model does not offer that effort, use its nearest offered effort. A role on `auto` or `inherit-parent` stays on the parent model. Set the effort only when `spawn_subagent` lists an effort argument. If the `spawn_subagent` tool rejects the adjusted slug, do not try another adjusted slug. Use the role's line or default and say so. You own every subagent's work. Review the diff and write your own summary, don't pass through what it said. A second opinion is the same prompt against a different model. Agreement is high-signal. diff --git a/skills/poteto-mode/playbooks/autonomous-run.md b/skills/poteto-mode/playbooks/autonomous-run.md index 2556599..03a9cb6 100644 --- a/skills/poteto-mode/playbooks/autonomous-run.md +++ b/skills/poteto-mode/playbooks/autonomous-run.md @@ -3,7 +3,7 @@ **You own the exit condition. Define done, then drive to it without stopping.** 1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero). -2. Pick the wake mechanism using `/loop` (a Grok Build built-in, not a pstack skill). Each fire is a fresh agent that cannot see this chat, so the stored prompt must stand alone. 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. Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. +2. Pick the wake mechanism using `/loop` (a Grok Build built-in, not a pstack skill). Each fire is a fresh agent that cannot see this chat, so the stored prompt must stand alone. 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. Pick each subagent's reasoning effort for the job, per the Subagents section. 3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride. Sequence the work via the **sequence-verifiable-units** principle skill, verifying each unit before the next instead of batching checks at the end. 4. Mid-run discoveries are yours. Address broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself via poteto-mode. Put out-of-band fixes in their own PR. Do not park reversible work for the human or use `ask_user_question`. Surface only irreversible actions, genuine product or preference calls no experiment can settle, or a real dead end. Keep the predicate as the main drive, and return to it after each side fix. diff --git a/skills/poteto-mode/playbooks/bug-fix.md b/skills/poteto-mode/playbooks/bug-fix.md index 238439c..f89f4fb 100644 --- a/skills/poteto-mode/playbooks/bug-fix.md +++ b/skills/poteto-mode/playbooks/bug-fix.md @@ -1,12 +1,12 @@ ### Bug fix -**You own this task. Plan, review, verify.** Delegate investigation and the fix to subagents, stay in the lead. Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. +**You own this task. Plan, review, verify.** Delegate investigation and the fix to subagents, stay in the lead. Pick each subagent's reasoning effort for the job, per the Subagents section. Be scientific. Every shipped line traces to runtime evidence. Belt-and-suspenders that "might help" is a hypothesis, not a fix. It does not ship. When evidence refutes a hypothesis, revert what it motivated. The smallest change the evidence justifies ships, nothing more. 1. Reproduce it yourself on the matching surface via the control skill (Non-negotiables), even when a debug or instrumentation protocol says to ask the user to reproduce. Ask the user only with a stated, specific reason the control surface cannot reach the target, and only after driving it as far as it goes. If it won't reproduce directly, synthesize the trigger, tighten conditions, or instrument until it fires. 2. Binary-search the cause. Form the candidate hypotheses, then rule them out until one survives. Seed them with `how` over the affected subsystem and the **why** skill for regression history. Each pass, take the split that cuts the most remaining problem space, get runtime evidence, eliminate. When program state is unclear, add instrumentation or logging and read it as the code runs. Don't guess. Drive a long or stubborn hunt with `/loop`. Each fire cannot see this chat, so the stored prompt must stand alone. Confirm the surviving *mechanism* with runtime evidence before the step-3 architect/interrogate fan-out. -3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (default `grok-4.7-build-fast`) with a specific scope. +3. Plan the fix. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured bug-fix model (default `grok-4.6` at `xhigh`) with a specific scope. 4. Verify on the same surface. The original repro now passes. "Inconclusive" or wrong-surface is not a pass. Flag it. Unit tests show branch behavior, not bug absence. 5. Stage the commits so the failing repro lands before the fix in git history. See the **tdd** skill for the failing-test-first cadence when the bug has a cheap local test path. Skip it when the test would be expensive, integration-heavy, or unclear. This is the canonical **sequence-verifiable-units** principle skill, the failing test first and the fix on top. diff --git a/skills/poteto-mode/playbooks/eval.md b/skills/poteto-mode/playbooks/eval.md index 5312f53..3432369 100644 --- a/skills/poteto-mode/playbooks/eval.md +++ b/skills/poteto-mode/playbooks/eval.md @@ -17,7 +17,7 @@ 1. **Frame.** State what variant is under test and what behavior counts as success. Write the rubric (3-6 concrete criteria) for the judge only. Hold it back from candidates. 2. **Set up sanitized environments.** Per-candidate working dir with the variant in place. Plant any context an organic task would have: a project skeleton, the skills the candidate would naturally read. 3. **Author one organic prompt.** What a user would type. No leakage of what's being measured. -4. **Spawn N parallel candidates** on different models per the **arena** skill's Phase B. Each works in its own sanitized dir. Same prompt to each. Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. +4. **Spawn N parallel candidates** on different models per the **arena** skill's Phase B. Each works in its own sanitized dir. Same prompt to each. Pick each subagent's reasoning effort for the job, per the Subagents section. 5. **Spawn one blinded judge** on a different detected model slug per the **arena** skill's Phase C, when one exists. Judge sees outputs by sanitized label and the rubric, never a model name. 6. **Verify the chain from transcripts, not self-report.** Read each candidate's local transcript at `~/.grok/sessions///chat_history.jsonl`. Percent-encoding turns `/` into `%2F`. `GROK_HOME` overrides `~/.grok`. Do not glob across `~/.grok/sessions/*/`. That crosses workspace boundaries and reads private chats from unrelated projects. Look at which files each candidate actually opened. Grade chain-following from the files it really read plus the shape of the code, never from the candidate's own claims. 7. **Read every candidate output yourself** end to end. Compare to the judge's verdict. Disagreement means a model is biased or the rubric is ambiguous. Synthesize. diff --git a/skills/poteto-mode/playbooks/feature.md b/skills/poteto-mode/playbooks/feature.md index bb6c08b..fe79d43 100644 --- a/skills/poteto-mode/playbooks/feature.md +++ b/skills/poteto-mode/playbooks/feature.md @@ -9,7 +9,7 @@ - **Independent workstreams.** Disjoint files, services, or layers parallelize. Shared writes serialize. - **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-build-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). Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. 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. +4. Delegate code-writing to a subagent using your configured feature model (default `grok-4.6` at `xhigh`) 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 effort 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. 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. diff --git a/skills/poteto-mode/playbooks/hillclimb.md b/skills/poteto-mode/playbooks/hillclimb.md index f34e650..9a744e1 100644 --- a/skills/poteto-mode/playbooks/hillclimb.md +++ b/skills/poteto-mode/playbooks/hillclimb.md @@ -9,7 +9,7 @@ Core discipline: one change, one measurement, keep or revert. Never stack untest 3. Open the decision log via the **show-me-your-work** skill. A `decision.tsv`, one row per attempt: id, hypothesis, change, before, after, delta, tests, verdict (kept or reverted), note. Read it before each attempt. Keep it out of the tree (gitignored). 4. Ground each hypothesis in the architecture model from step 1, so it names a specific mechanism ("defer X off the boot path because it blocks first paint"), not "try memoizing something". For a perf metric, order hypotheses by the performance mantras in step 2 of the Perf issue playbook (`playbooks/perf-issue.md`). Borrow only their order, not that step's stop rule. 5. Loop, one hypothesis per iteration: - - Hand the change to a subagent using your configured hillclimb model (default `grok-4.7-build-fast`) with a tight scope. Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. Supervise and review the diff rather than typing it (the **guard-the-context-window** principle skill). When several independent hypotheses are live, fan them to parallel subagents, each in its own worktree (the **separate-before-serializing-shared-state** principle skill). + - Hand the change to a subagent using your configured hillclimb model (default `grok-4.6` at `xhigh`) with a tight scope. Pick each subagent's reasoning effort for the job, per the Subagents section. Supervise and review the diff rather than typing it (the **guard-the-context-window** principle skill). When several independent hypotheses are live, fan them to parallel subagents, each in its own worktree (the **separate-before-serializing-shared-state** principle skill). - Measure before and after with the frozen harness, and run the regression gate. - Accept only when the metric moves past noise and the gate stays green. Otherwise revert the change in full. A tweak that "might help" is not kept. - One commit per accepted fix, staging only the files you changed (`git add `, never `-A`). Log the row either way, kept or reverted. diff --git a/skills/poteto-mode/playbooks/multi-phase-plan.md b/skills/poteto-mode/playbooks/multi-phase-plan.md index c164b60..f5b988d 100644 --- a/skills/poteto-mode/playbooks/multi-phase-plan.md +++ b/skills/poteto-mode/playbooks/multi-phase-plan.md @@ -4,13 +4,13 @@ 1. When the change is one or two files with an obvious approach, skip the plan. Say so and stop. 2. Settle open questions by prototype before you write. Run `playbooks/prototype.md` for each. Keep the branch, the SHA, and the screenshots for Appendix A. Ask the operator only about a product or preference call that no run can settle. Give options (the **never-block-on-the-human** principle skill). -3. Explore in subagents with `subagent_type: "pstack:poteto-agent"` and an explicit model per the Subagents section (the **guard-the-context-window** principle skill). Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. Each returns file pointers, conventions, test commands, and entry points. No inlined dumps. +3. Explore in subagents with `subagent_type: "pstack:poteto-agent"` and an explicit model per the Subagents section (the **guard-the-context-window** principle skill). Pick each subagent's reasoning effort for the job, per the Subagents section. Each returns file pointers, conventions, test commands, and entry points. No inlined dumps. 4. Copy the skeleton below into the plan file and fill every placeholder. Unless the operator names a path, write the file under the agent store's `docs/`. Keep every heading and every sub-block in the order shown. One section per PR. One PR is one change with its own evidence (the **sequence-verifiable-units** principle skill). Name the execution playbook in **How to read this**. Pick between `playbooks/autopilot-full.md` and `playbooks/autopilot-stack.md` per the rule at the end of `playbooks/autopilot-stack.md`. A standing program takes `playbooks/orchestrate.md`. 5. Write under `/technical-writing` in full, then `/unslop`. The body is one Diátaxis mode, how-to. Appendices hold explanation and reference. Each heading states the task or the finding. No long dashes. No mid-sentence colons. 6. Run `node pstack/skills/poteto-mode/scripts/check-plan.mjs ` and fix every line it prints (the **encode-lessons-in-structure** principle skill). 7. Hand back. Post the plan path and the script's output, then stop. Execution starts on the operator's explicit go, under the execution playbook the plan names. -**Verification.** Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked (the **prove-it-works** principle skill). That sentence is the verification rule. Every verification block opens with it. The live block is mandatory. Ten lanes at the PR head drive the real surface through its control skill, per the **swarm** skill, on the `swarm workers` model (default `grok-4.7-build-fast`). Each lane is one box with a concrete scenario, the screenshot it saves, and its pass predicate. One lane is the **Regression lane against trunk.** It runs the same load-bearing scenario on trunk and head. If trunk does not have the feature, the lane records that fact and gates the behavior the diff adds plus the end state the user waits for instead of inventing a trunk result. The perf gate is dual-sided. Trunk and head must both produce the named metric. If trunk lacks the feature, also isolate the work the diff adds and set an absolute budget for that work plus the end-to-end state the user waits for. Do not claim a ratio between unlike scenarios. The perf block names the metric, the interleaved probe, the trunk baseline measured first, and the rule with the number that fails. A PR that changes an interaction is review-gated. The operator reviews it in chat with screenshots and a video before merge. A PR that changes no interaction writes `**Review gate.** None. is not review-gated.` and no boxes under it. +**Verification.** Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked (the **prove-it-works** principle skill). That sentence is the verification rule. Every verification block opens with it. The live block is mandatory. Ten lanes at the PR head drive the real surface through its control skill, per the **swarm** skill, on the `swarm workers` model (default `grok-4.6` at `xhigh`). Each lane is one box with a concrete scenario, the screenshot it saves, and its pass predicate. One lane is the **Regression lane against trunk.** It runs the same load-bearing scenario on trunk and head. If trunk does not have the feature, the lane records that fact and gates the behavior the diff adds plus the end state the user waits for instead of inventing a trunk result. The perf gate is dual-sided. Trunk and head must both produce the named metric. If trunk lacks the feature, also isolate the work the diff adds and set an absolute budget for that work plus the end-to-end state the user waits for. Do not claim a ratio between unlike scenarios. The perf block names the metric, the interleaved probe, the trunk baseline measured first, and the rule with the number that fails. A PR that changes an interaction is review-gated. The operator reviews it in chat with screenshots and a video before merge. A PR that changes no interaction writes `**Review gate.** None. is not review-gated.` and no boxes under it. **Control skill.** Pick it by surface. Browser, Electron, and web UIs use `control-ui` bundled in this plugin. CLIs and TUIs use `control-cli` bundled in this plugin. Native mobile uses whatever simulator-driving skill the repo has. A PR that touches two surfaces gets lanes on both. A surface with no control skill is a risk in Appendix C, and its live block still names how each lane drives it. diff --git a/skills/poteto-mode/playbooks/orchestrate.md b/skills/poteto-mode/playbooks/orchestrate.md index de7670a..00c6de8 100644 --- a/skills/poteto-mode/playbooks/orchestrate.md +++ b/skills/poteto-mode/playbooks/orchestrate.md @@ -12,7 +12,7 @@ Three rules carry the rest. #### Roles and placement -- **Coordinator (this chat).** Local. Frames, authors briefs, drains the inbox, owns the human report, makes judgment calls. It never authors or edits code. Conflicted merges, chain rebases, and code changes are always tasks. Mechanically landing a verified unit (fast-forward or clean cherry-pick of a worker's commit, then push) is bookkeeping the coordinator may do itself on repos where local git is cheap. Queueing finished work behind an idle stacker is how a deadline harvests nothing. The loop is agentic end to end. This chat is the only spawner. Agents are spawned, resumed, and drained only through `spawn_subagent`. A child must not spawn. Resume a completed child with `resume_from`. Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. State reads and writes go through `scripts/orch/orch.ts` at drain points, one command in and one line out. The CLI never spawns, waits, or wakes anything. +- **Coordinator (this chat).** Local. Frames, authors briefs, drains the inbox, owns the human report, makes judgment calls. It never authors or edits code. Conflicted merges, chain rebases, and code changes are always tasks. Mechanically landing a verified unit (fast-forward or clean cherry-pick of a worker's commit, then push) is bookkeeping the coordinator may do itself on repos where local git is cheap. Queueing finished work behind an idle stacker is how a deadline harvests nothing. The loop is agentic end to end. This chat is the only spawner. Agents are spawned, resumed, and drained only through `spawn_subagent`. A child must not spawn. Resume a completed child with `resume_from`. Pick each subagent's reasoning effort for the job, per the Subagents section. State reads and writes go through `scripts/orch/orch.ts` at drain points, one command in and one line out. The CLI never spawns, waits, or wakes anything. - **Sub-coordinator.** Always local, durable, one per track, and only when the program exceeds what one coordinator's drains can manage. A track the coordinator can drain itself needs no middle layer. Each nested layer re-pays a full orientation preamble, and a blocking sub-coordinator hides its children while the parent idles. Owns its track's units and boards and authors its workers' briefs. It must not call `spawn_subagent`. Grok Build allows spawning only from the top-level chat, so this chat spawns the workers and verifiers from the briefs the sub-coordinator returns. Rolls up aggregates at wave boundaries. Never forwards raw child reports. Cap in-flight children at what one drain can process, roughly ten, as a rolling window. Never as blocking batches, which cost the slowest child of every batch. - **Worker / verifier.** Always `isolation: "worktree"` unless the task needs the shared checkout (`isolation: "none"`): `control-ui` or `control-cli` runtime verification (bundled in this plugin), reading local transcripts, simulators and local IDE state, or auth that exists only here. A worker that cannot read the local store gets what it needs inlined in the brief or as repo paths. Prefer fewer, broader workers. One writer per worktree or branch (principle-separate-before-serializing-shared-state). Run a unit's verifier on a different detected model slug from its worker when one exists. diff --git a/skills/poteto-mode/playbooks/perf-issue.md b/skills/poteto-mode/playbooks/perf-issue.md index 191eb8a..ea5f18d 100644 --- a/skills/poteto-mode/playbooks/perf-issue.md +++ b/skills/poteto-mode/playbooks/perf-issue.md @@ -14,7 +14,7 @@ 7. Do it cheaper. When an earlier mantra meets the target, stop. -3. Plan the fix from the trace. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured perf-issue model (default `grok-4.7-build-fast`). Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. Review the diff. Capture a post-fix trace. +3. Plan the fix from the trace. If it crosses a function boundary, `architect` first. Delegate implementation to a subagent using your configured perf-issue model (default `grok-4.6` at `xhigh`). Pick each subagent's reasoning effort for the job, per the Subagents section. Review the diff. Capture a post-fix trace. Apply the **sequence-verifiable-units** principle skill, verifying each attempt before trying the next. 4. Parse and compare the artifacts (JSON to sqlite, diff). "Inconclusive" or wrong-surface is not a pass. Flag it. 5. Cite the measurement in the PR. diff --git a/skills/poteto-mode/playbooks/refactoring.md b/skills/poteto-mode/playbooks/refactoring.md index e1f8fc2..259e301 100644 --- a/skills/poteto-mode/playbooks/refactoring.md +++ b/skills/poteto-mode/playbooks/refactoring.md @@ -8,7 +8,7 @@ If the cleanup reveals a missing feature or a real bug, split it out and ship th 2. Name the structure the code is missing per **principle-model-the-domain**. Boring code stays when the shape is already clear and local. The reshape must delete branches or invalid states, not add indirection. 3. Name the target shape. State what the module layout, types, and call graph should be if built today (**principle-foundational-thinking**, **principle-redesign-from-first-principles**). If the target crosses a function boundary, run the **architect** skill for parallel design exploration of the shape before the move. 4. Subtract before you add. Delete dead code, collapse one-caller wrappers, drop redundant validators, and remove orphan references before introducing the new shape (**principle-subtract-before-you-add**). The smallest change that reaches the target shape ships (**principle-laziness-protocol**). A speculative cleanup that "might help" gets reverted. -5. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (**principle-migrate-callers-then-delete-legacy-apis**). No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files. Renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a subagent using your configured refactoring model (default `grok-4.7-build-fast`) with a specific scope (file paths, the names being moved, the behavior to hold). Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. +5. Move in small behavior-preserving steps, each keeping the pin green. For API reshapes, migrate every caller and delete the old API in the same wave (**principle-migrate-callers-then-delete-legacy-apis**). No compatibility shims, no parallel old-and-new paths. Spot-check every rename against the actual files. Renames silently miss usages in strings, prose, and back-references. Delegate the mechanical edits to a subagent using your configured refactoring model (default `grok-4.6` at `xhigh`) with a specific scope (file paths, the names being moved, the behavior to hold). Pick each subagent's reasoning effort for the job, per the Subagents section. 6. Prove behavior is unchanged on the real artifact, not "it compiles" (**principle-prove-it-works**). For larger reshapes, run an equivalence check: a script that diffs old-vs-new outputs, a recorded baseline replayed against the new code, or a smoke run on the matching surface via the relevant control skill. 7. Confirm the change is worth keeping. The success measure is reduced reader load (**principle-minimize-reader-load**). If the diff does not lower reader load somewhere, revert it. 8. Rebase into small ordered commits. A subtraction commit, then the reshape, then any follow-on cleanup. Shape them with the **sequence-verifiable-units** principle skill, so each behavior-preserving slice stays green before the next. Run **Opening a PR**. diff --git a/skills/poteto-mode/playbooks/runtime-forensics.md b/skills/poteto-mode/playbooks/runtime-forensics.md index 21c0443..1b9ef08 100644 --- a/skills/poteto-mode/playbooks/runtime-forensics.md +++ b/skills/poteto-mode/playbooks/runtime-forensics.md @@ -3,7 +3,7 @@ **You own the diagnosis. Instrument the live process, don't theorize from source.** The deliverable is a cited diagnosis, not a fix. 1. Capture the live signal on the matching surface via the control skill: a CPU profile for a spinning process, a heap snapshot for a leak, a CDP trace for a visual glitch. A real artifact, not a guess. -2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread. Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. +2. Reduce the artifact to the smoking gun: the function on the hot path, the retainer chain from the leaked object to a GC root, the loop firing without input. Parse large artifacts in a subagent (the **guard-the-context-window** principle skill), keep the reduced finding in the main thread. Pick each subagent's reasoning effort for the job, per the Subagents section. 3. Prove the mechanism before believing it. Inject instrumentation via CDP eval on the running process, or hotfix the live code without reloading, to confirm the hypothesis cheaply. 4. Map the finding back to source: file, symbol, the line that allocates or schedules. 5. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only forensics`. diff --git a/skills/poteto-mode/playbooks/session-pickup.md b/skills/poteto-mode/playbooks/session-pickup.md index 43a363b..2f403ce 100644 --- a/skills/poteto-mode/playbooks/session-pickup.md +++ b/skills/poteto-mode/playbooks/session-pickup.md @@ -2,7 +2,7 @@ **You own the resume point. Read the prior trail, don't redo it.** -1. Locate the prior trail. A local transcript at `~/.grok/sessions///chat_history.jsonl` (`GROK_HOME` overrides `~/.grok`. Do not glob across `~/.grok/sessions/*/`, that crosses workspace boundaries and reads private chats from unrelated projects), or a pushed branch. Read the metadata overview and 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). Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. +1. Locate the prior trail. A local transcript at `~/.grok/sessions///chat_history.jsonl` (`GROK_HOME` overrides `~/.grok`. Do not glob across `~/.grok/sessions/*/`, that crosses workspace boundaries and reads private chats from unrelated projects), or a pushed branch. Read the metadata overview and 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). Pick each subagent's reasoning effort for the job, per the Subagents section. 2. Reconstruct operational state. The branch and worktree, what already landed (`git log`, `git diff` against the base), the open todos, the decisions made. The prior trail is authoritative input. Resist the bias to re-derive it. 3. Diff done vs pending. Compare what shipped against what was planned, name the resume point, do not re-run the prior repro or redo completed work. A "let me verify from scratch" pass means you're treating the trail as untrustworthy when it's authoritative. 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. diff --git a/skills/poteto-mode/playbooks/trace-forensics.md b/skills/poteto-mode/playbooks/trace-forensics.md index 9bfd120..9b548ef 100644 --- a/skills/poteto-mode/playbooks/trace-forensics.md +++ b/skills/poteto-mode/playbooks/trace-forensics.md @@ -4,7 +4,7 @@ Distinct from **Runtime forensics**, which instruments the live process. Here the capture already exists. The artifact is a fixed dataset, read it, don't re-run it. Keep tooling generic: a DevTools or trace parser for cpuprofile and `.json.gz`, a text editor for a spindump, your heap tooling for a heapsnapshot. -1. Identify the format and load it with the right tool. Parse large artifacts in a subagent (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread. Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. +1. Identify the format and load it with the right tool. Parse large artifacts in a subagent (the **principle-guard-the-context-window** skill) and keep the reduced finding in the main thread. Pick each subagent's reasoning effort for the job, per the Subagents section. 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. Reach the queryable shape before you read. 3. Narrow to the cause. Query for the frames that hold the most time and walk the call tree 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. 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. diff --git a/skills/poteto-mode/playbooks/worktree-cleanup.md b/skills/poteto-mode/playbooks/worktree-cleanup.md index f5aac08..c6f5646 100644 --- a/skills/poteto-mode/playbooks/worktree-cleanup.md +++ b/skills/poteto-mode/playbooks/worktree-cleanup.md @@ -2,7 +2,7 @@ 1. Snapshot and audit. Record `df -h /`, then run `scripts/worktree-audit.sh [-b ] [repo-path]` (principle-build-the-lever). Without `-b` it checks `MERGED` against `origin/HEAD`, so pass `-b origin/` when PRs target another branch. It reads paths from `git worktree list`, never hand-typed, since a hand-typed `myrepo-worktrees/x` misses one that lives at a different absolute path (principle-encode-lessons-in-structure). It classifies each worktree by size, age, merge state, uncommitted work, PR state, and the newest chat that touched it, then suggests a bucket. The transcript scan is slow, so background it. 2. The bucket is advice, not permission. The pinned and active chats are the real artifact (principle-prove-it-works). Get that set from the user or sidebar and cross-check every candidate. The lever has marked `safe` a worktree the user had pinned, so the pinned set wins. -3. Verify usage before deleting. For every `verify-recent-chat` row, or anything you doubt, fan subagents out to read the transcripts and report whether the chat is pinned or ongoing and which worktrees it touches (principle-guard-the-context-window, transcripts are bulk). A pinned chat spawns arena and repro trees into sibling worktrees via background subagents, and those are in use even when their names never hit the sidebar. Use the role slug from the Subagents section of the poteto-mode skill. Do not invent an effort suffix. +3. Verify usage before deleting. For every `verify-recent-chat` row, or anything you doubt, fan subagents out to read the transcripts and report whether the chat is pinned or ongoing and which worktrees it touches (principle-guard-the-context-window, transcripts are bulk). A pinned chat spawns arena and repro trees into sibling worktrees via background subagents, and those are in use even when their names never hit the sidebar. Pick each subagent's reasoning effort for the job, per the Subagents section. 4. Pause on irreversible loss. `wip:N` is N tracked uncommitted edits. Show the diff and get a decision first, since removing a clean worktree is recoverable from its branch but uncommitted work is gone. `scratch:N` is untracked throwaway, safe to drop, but name the files. Per Autonomy, clean and merged and not-in-use proceeds. `wip` and in-use pause. 5. Prune the confirmed set. Per path, `git worktree remove --force `. If the dir survives on ignored build artifacts, `rm -rf` it, then `git worktree prune`. Branch refs survive, so no commits are lost. Confirm with `df -h /` and re-list. 6. Simulators and other reclaimers. Simulators are usually the next-biggest win. `xcrun simctl --set testing delete all` (XCTestDevices clones), `xcrun simctl delete unavailable`, and `xcrun simctl runtime list` then `runtime delete ` for old runtimes. More when needed: Xcode `DerivedData` and `iOS DeviceSupport`, and package caches (pnpm, uv, brew, yarn). Clear only caches the user has not said to keep. diff --git a/skills/recall/SKILL.md b/skills/recall/SKILL.md index 8ceeb1f..d92a50f 100644 --- a/skills/recall/SKILL.md +++ b/skills/recall/SKILL.md @@ -16,7 +16,7 @@ Transcripts live at `~/.grok/sessions// `xhigh` > `high` > `medium` > `low`. Effort is a separate field, written after the model id (`grok-4.6 xhigh`). If the model does not offer that effort, use its highest offered effort at or below the target, else mark the role as needing a choice. `inherit-parent` and `auto` do not change. So on grok 1.0.62, `unlimited` keeps `grok-4.6` at `xhigh`, `large` keeps the defaults, and `small` turns them into `grok-4.6 medium` and `grok-4.5 medium`. A panel list stays two entries when two different detected slugs exist. When the budget collapses a panel onto one slug, write that slug twice and tell the user the panel has no second model. If `spawn_subagent` has no `model` argument, still write the intended slugs. They take effect in the next session, after step 1 exposes `model`. **(c) Show the roles and confirm.** Show every role with its model, marking any real slug not in the detected set as needing a choice. Also list each line step 2 dropped. Ask whether to accept as-is or change specific roles, offering the detected models plus `inherit-parent` and `auto` (both mean this role runs on the parent chat model, so omit `model`) as the options. Prefer ask_user_question over free text. For panel roles (arena runners, architect runners, interrogate reviewers) the value is a list, and one subagent runs per entry, alias entries included, so the list length sets the count. `arena cross-judge pool` is also a list. Arena selects one value from it that differs from the parent's slug when another detected slug exists. `swarm workers` is the default model for every worker unless a race or comparison assigns another model per arm. @@ -50,30 +43,30 @@ Every real slug written must be in the detected set. `inherit-parent` and `auto` ### 5. Write the rule -Write `~/.grok/rules/pstack-models.md` as plain Markdown. No YAML frontmatter. Include a `# budget` line and one line per role, using the same labels poteto-mode uses. Overwrite the whole file so re-runs stay idempotent. Shape for `large` when `grok-4.7` and `grok-4.7-build-fast` are both detected: +Write `~/.grok/rules/pstack-models.md` as plain Markdown. No YAML frontmatter. Include a `# budget` line and one line per role, using the same labels poteto-mode uses. Overwrite the whole file so re-runs stay idempotent. Shape for `large` when `grok-4.6` and `grok-4.5` are detected: ``` # pstack model configuration. One line per role. Delete a line to fall back to the skill default. # `inherit-parent` or `auto` as a value: the role runs on the parent chat model (omit `model`). Alias entries in a panel list still count toward its fan-out. # Pass model only when spawn_subagent lists it. Step 1 exposes that argument for the next session. -# budget: large (judgment grok-4.7, code grok-4.7-build-fast) -feature, refactoring: grok-4.7-build-fast -bug-fix: grok-4.7-build-fast -perf-issue: grok-4.7-build-fast -hillclimb: grok-4.7-build-fast -judgment and prose: grok-4.7 -hardest tasks: grok-4.7 -how explorer: grok-4.7-build-fast -how explainer: grok-4.7 -why investigators: grok-4.7-build-fast -why synthesizer: grok-4.7 -reflect tooling: grok-4.7-build-fast -reflect judgment, divergent, synthesizer: grok-4.7 -arena runners: grok-4.7, grok-4.7-build-fast -arena cross-judge pool: grok-4.7, grok-4.7-build-fast -swarm workers: grok-4.7-build-fast -architect runners: grok-4.7, grok-4.7-build-fast -interrogate reviewers: grok-4.7, grok-4.7-build-fast +# budget: large (xhigh) +feature, refactoring: grok-4.6 xhigh +bug-fix: grok-4.6 xhigh +perf-issue: grok-4.6 xhigh +hillclimb: grok-4.6 xhigh +judgment and prose: grok-4.6 xhigh +hardest tasks: grok-4.6 xhigh +how explorer: grok-4.6 xhigh +how explainer: grok-4.6 xhigh +why investigators: grok-4.6 xhigh +why synthesizer: grok-4.6 xhigh +reflect tooling: grok-4.6 xhigh +reflect judgment, divergent, synthesizer: grok-4.6 xhigh +arena runners: grok-4.6 xhigh, grok-4.5 high +arena cross-judge pool: grok-4.6 xhigh, grok-4.5 high +swarm workers: grok-4.6 xhigh +architect runners: grok-4.6 xhigh, grok-4.5 high +interrogate reviewers: grok-4.6 xhigh, grok-4.5 high ``` Substitute the slugs step 3 actually chose. Keep the role labels exactly as written above. diff --git a/skills/show-me-your-work/SKILL.md b/skills/show-me-your-work/SKILL.md index 0aed629..3db1dd4 100644 --- a/skills/show-me-your-work/SKILL.md +++ b/skills/show-me-your-work/SKILL.md @@ -64,7 +64,7 @@ Correct the log, not the story. The audit never edits or removes a row, even an ## Cross-model review of the trail -Before handing back, spawn a subagent on a different detected model slug from the one that did the work, when one exists. Self-review is not a substitute. The subagent reads the audit trail and the run's transcript, then flags what the user should pay attention to. Not a redo of the work, a scan for what's suboptimal or risky. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. +Before handing back, spawn a subagent on a different detected model slug from the one that did the work, when one exists. Self-review is not a substitute. The subagent reads the audit trail and the run's transcript, then flags what the user should pay attention to. Not a redo of the work, a scan for what's suboptimal or risky. Pick each subagent's reasoning effort for the job, per the Subagents section. - Decisions logged with weak or absent evidence. - Verification steps skipped or claimed without proof in the transcript. diff --git a/skills/swarm/SKILL.md b/skills/swarm/SKILL.md index 250357e..d28223c 100644 --- a/skills/swarm/SKILL.md +++ b/skills/swarm/SKILL.md @@ -19,7 +19,7 @@ Open a todolist with one entry per phase before launching anything. 1. State the done predicate and the artifact or report the swarm must return. 2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning. -4. Pick the worker model from the `swarm workers` line in `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, use `grok-4.7-build-fast`. For `auto` or `inherit-parent`, omit `model` so the workers run on the parent model. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. For a model race, name each arm's model up front. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. +4. Pick the worker model from the `swarm workers` line in `~/.grok/rules/pstack-models.md`. If the rule or that line is missing, use `grok-4.6` at `xhigh`. For `auto` or `inherit-parent`, omit `model` so the workers run on the parent model. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. For a model race, name each arm's model up front. Pick each subagent's reasoning effort for the job, per the Subagents section. 5. Give each worker its own writable output when it writes. When workers verify or measure commits, each brief names the exact SHAs. A measurement brief also names the method (sample count, what one sample is, order). The worker records both in its result. ## Phase B: Fan out diff --git a/skills/why/SKILL.md b/skills/why/SKILL.md index 329564b..43180ed 100644 --- a/skills/why/SKILL.md +++ b/skills/why/SKILL.md @@ -8,7 +8,7 @@ disable-model-invocation: true Investigate the motivation and intent behind code. The companion `how` skill answers what the code does and how it works. `why` answers what forces led to its shape. -Each spawn below names a role line in the `pstack-models.md` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Use the role slug from the Subagents section of the **poteto-mode** skill. Do not invent an effort suffix. +Each spawn below names a role line in the `pstack-models.md` rule and a default. Set `model` to that line's value, or to the default if the rule or the line is missing. Leave `model` unset when the value is `auto` or `inherit-parent`. If `spawn_subagent` has no `model` argument, omit it for this session so the child inherits the parent, and apply step 1 of **setup-pstack** so the next session can pass `model`. If it rejects a slug, use the closest slug from `grok models` and say so. Pick each subagent's reasoning effort for the job, per the Subagents section. Every spawn omits `subagent_type`. There is no readonly flag. Investigators must not write files. Say that in the prompt. MCP stays available through `search_tool` and `use_tool`, which the investigators and the synthesizer's citation spot-checks need. @@ -46,7 +46,7 @@ Map each available MCP to one evidence category: Source control is always available through git and `gh`. For the other six, classify using the MCP name, server instructions, tool names, and resource descriptors. If an MCP could fit more than one category, choose the one matching its primary evidence. Record ambiguous cases in the coverage map. -Spawn one investigator per category that has a matching MCP, all in a single message so they run concurrently, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. `model`: the `why investigators` line, default `grok-4.7-build-fast`. +Spawn one investigator per category that has a matching MCP, all in a single message so they run concurrently, each owning exactly one tool or MCP. Don't ask one agent to cover multiple MCPs. `model`: the `why investigators` line, default `grok-4.6` at `xhigh`. Each investigator's prompt is `references/investigator-prompt.md` filled in, plus: - the category playbook `references/sources/.md` for the selected MCP, adapted from the examples in `references/source-playbook.md` @@ -76,7 +76,7 @@ If your scope assessment suggests a single-commit trivial target where the PR de ## Step 4. Synthesize -Spawn one synthesizer. `model`: the `why synthesizer` line, default `grok-4.7`. It gets: +Spawn one synthesizer. `model`: the `why synthesizer` line, default `grok-4.6` at `xhigh`. It gets: 1. The investigator findings, including any null results and any categories skipped with justification 2. The code anchor 3. The user's original question