From 6f101d232b912d12a39c00c94b426d8b0970768c Mon Sep 17 00:00:00 2001 From: Farzad Date: Wed, 21 Oct 2026 17:33:48 +0400 Subject: [PATCH] docs(pstack): add subagent and design-probe lessons to skills Move rules that lived only in a local Claude Code plugin cache into the pstack source. poteto-mode gains rules for briefing an agent on an unknown system, watching long jobs by progress, giving parallel worktrees their own resources, and treating a stop order that adds work as a fresh task. The adapter adds worktree cleanup and merge ownership. architect adds a learned-surface budget and a blind guessability probe. blast-radius, investigation, technical-writing, and three principle descriptions widen their triggers. harness/pstack/claude-code is regenerated. Co-Authored-By: Claude Fable 5.1 Claude-Session: https://claude.ai/code/session_01HGD8v9WkwgmcM4JPipW6fe --- .../claude-code/docs/harness/claude-code.md | 4 ++-- .../claude-code/skills/architect/SKILL.md | 4 ++++ .../claude-code/skills/blast-radius/SKILL.md | 2 +- .../claude-code/skills/poteto-mode/SKILL.md | 18 ++++++++++++------ .../poteto-mode/playbooks/investigation.md | 2 +- .../SKILL.md | 2 +- .../principle-explain-the-number/SKILL.md | 2 +- .../SKILL.md | 2 +- .../skills/technical-writing/SKILL.md | 3 ++- pstack/docs/harness/claude-code.md | 4 ++-- pstack/skills/architect/SKILL.md | 4 ++++ pstack/skills/blast-radius/SKILL.md | 2 +- pstack/skills/poteto-mode/SKILL.md | 18 ++++++++++++------ .../poteto-mode/playbooks/investigation.md | 2 +- .../SKILL.md | 2 +- .../principle-explain-the-number/SKILL.md | 2 +- .../SKILL.md | 2 +- pstack/skills/technical-writing/SKILL.md | 3 ++- 18 files changed, 50 insertions(+), 28 deletions(-) diff --git a/harness/pstack/claude-code/docs/harness/claude-code.md b/harness/pstack/claude-code/docs/harness/claude-code.md index bf154e646..ef609d145 100644 --- a/harness/pstack/claude-code/docs/harness/claude-code.md +++ b/harness/pstack/claude-code/docs/harness/claude-code.md @@ -20,10 +20,10 @@ pstack skills use Cursor names. In Claude Code, read this file once per session, | `poteto-agent`, `comment-sicko` | `pstack:poteto-agent`, `pstack:comment-sicko` | | `readonly: true` | `subagent_type: "Explore"`. It keeps `Bash`, so the brief also says "do not edit files", and you check `git status` afterward. | | `readonly: false` | `general-purpose`. It keeps the session's MCP servers. | -| `environment: "cloud"` | `isolation: "worktree"`. Name the branch or commit the worker checks out. | +| `environment: "cloud"` | `isolation: "worktree"`. Name the branch or commit the worker checks out. Gitignored files such as `.env` are not in the worktree, so the brief says to copy them in. The worker cannot `git -C` the main checkout, so the parent does the `merge --ff-only`. Cleanup is `git worktree unlock`, then `git worktree remove`, then `git branch -d`. | | `environment: "local"` | Omit. | | `cloud_base_branch: ` | Tell the worker to check out `` first. | -| `run_in_background: true` | Omit. Subagents run in the background by default and notify you when they finish. | +| `run_in_background: true` | Omit. Subagents run in the background by default and notify you only when they finish. Check a long job's elapsed time yourself through its task output file or `git log main..HEAD` in its worktree. | | `resume` | Spawn a new agent and paste the earlier result into its brief. | | `file_attachments` | List the paths in the brief. | diff --git a/harness/pstack/claude-code/skills/architect/SKILL.md b/harness/pstack/claude-code/skills/architect/SKILL.md index 0cd5921d4..9b5483cdc 100644 --- a/harness/pstack/claude-code/skills/architect/SKILL.md +++ b/harness/pstack/claude-code/skills/architect/SKILL.md @@ -36,6 +36,10 @@ Design it twice. Require at least two structurally distinct candidates before sy Screen every candidate against [`references/design-red-flags.md`](references/design-red-flags.md) before synthesis. Assume the next contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Prefer the design where a change that looks right from one file is right for the whole repo. +Before comparing, define the counted unit as everything a user must learn (every key, option, verb, and route), not the number of top-level blocks, and set a budget for it. A design can cut blocks while its learned surface stays the same size. + +Test guessability with a blind probe. Show a fresh agent, on a different model, about a third of the surface, have it guess the rest, and score the guesses against an answer key written before the probe. Use the score as the pass bar. After any rename taken from a probe, run a fresh probe, because the old score now measures fit. + Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers. Arena returns one synthesized design package. Its synthesis decision fills the rationale's "Synthesis decision" section. diff --git a/harness/pstack/claude-code/skills/blast-radius/SKILL.md b/harness/pstack/claude-code/skills/blast-radius/SKILL.md index b296cce0d..a42161776 100644 --- a/harness/pstack/claude-code/skills/blast-radius/SKILL.md +++ b/harness/pstack/claude-code/skills/blast-radius/SKILL.md @@ -1,6 +1,6 @@ --- name: blast-radius -description: "Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', or reviewing a small diff you don't trust." +description: "Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', reviewing a small diff you don't trust, or changing a global default (a model, an embedding, a threshold), where the proof is rerunning the behavior suite, not a capability check." disable-model-invocation: true --- diff --git a/harness/pstack/claude-code/skills/poteto-mode/SKILL.md b/harness/pstack/claude-code/skills/poteto-mode/SKILL.md index 1bb3884a5..f5a4da2df 100644 --- a/harness/pstack/claude-code/skills/poteto-mode/SKILL.md +++ b/harness/pstack/claude-code/skills/poteto-mode/SKILL.md @@ -61,7 +61,7 @@ Read the leaf skill in full for any principle you apply. Each entry names when i - **Type System Discipline.** Designing types or a signature in any typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries. - **Make Operations Idempotent.** Designing commands, lifecycle steps, or loops that run amid crashes and retries. Converge to the same end state. - **Migrate Callers Then Delete Legacy APIs.** Introducing a new internal API while old callers exist. Migrate and delete in one wave. -- **Separate Before Serializing Shared State.** Concurrent actors might write the same file, branch, key, or object. Eliminate the sharing first. +- **Separate Before Serializing Shared State.** Concurrent actors might write the same file, branch, key, object, database, port, or migration state. Eliminate the sharing first. **Verification** @@ -69,16 +69,16 @@ Read the leaf skill in full for any principle you apply. Each entry names when i - **Fix Root Causes.** Debugging. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate. - **Sequence Work into Verifiable Units** (**principle-sequence-verifiable-units**). Multi-step work (sweeps, migrations, runs of similar edits) and how you stack commits and PRs. Break work into small units that each end in a check, verify each before the next, and order delivery so the sequence proves itself. - **Test Behavior, Not Implementation.** Writing, changing, or keeping a test. Assert what the code's users can observe, so the test fails when that behavior breaks and keeps passing when only the internals change. -- **Explain the Number.** Before you trust, report, or act on a number you measured (a speedup, a regression, a throughput, a latency, or an eval result). Find what limits it, and rule out that it measured something other than the work you think. +- **Explain the Number.** Before you trust, report, or act on a number you measured (a speedup, a regression, a throughput, a latency, or an eval result), and any score on data you tuned against, which shows fit, not accuracy. Find what limits it, and rule out that it measured something other than the work you think. **Delegation** -- **Guard the Context Window.** Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread. +- **Guard the Context Window.** Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread. A short deliverable you are about to report from is read in full, never clipped with head or tail. - **Never Block on the Human.** Tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct. **Meta** -- **Encode Lessons in Structure.** You catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script instead of more text. +- **Encode Lessons in Structure.** You catch yourself writing the same instruction a second time, or promising yourself a new habit ("I'll remember to..."). Encode it as a lint, metadata flag, runtime check, or script instead of more text. ## Autonomy @@ -96,11 +96,17 @@ Read the leaf skill in full for any principle you apply. Each entry names when i **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. +**Briefs about a system you don't know.** Point the agent at the source and make its first deliverable its own cited account of that system. Never write your guess about it into the brief, because the agent echoes a planted framing back as a finding. + +**Watch long jobs by progress, not by clock.** Time estimates are unreliable, so never predict how long work will take, and don't cap a job by the clock. A brief for long work, especially a live or end-to-end run, gives a per-item timeout, so one stuck item can't hold the rest, and a stop-and-report rule for when progress stops. While it runs, check its progress yourself: new commits, items finished, and the same failure or retry repeating. A job with no new progress, or one looping on the same error, gets inspected and stopped or narrowed. A recent commit alone is not evidence it's on track. + +**Parallel agents get their own resources.** Agents in separate worktrees each get databases, ports, and migration state derived from their checkout, never one shared instance. + +**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. When the user changes a role's model or effort, write it into the `/setup-pstack` rule too, not only into memory, so every later spawn picks it up. 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. -**Fresh subagents by default.** Give new work to a fresh subagent with consolidated scope, meaning the original brief, every later directive, and the prior agent's report and branch. This holds for a fix round, a follow-up, a retry, and the next queue item. Resume, message, or queue a follow-up on an existing subagent only when the new work strictly needs state that lives in that agent and is costly to move: its local checkout, its uncommitted changes, or a process it still runs, such as a dev server, a simulator, or a babysit watcher. A stop or hold order to a running agent is not reuse. A role such as a PR owner outlives its agent. Once that agent returns, a fresh agent takes the role's next round. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary. +**Fresh subagents by default.** Give new work to a fresh subagent with consolidated scope, meaning the original brief, every later directive, and the prior agent's report and branch. This holds for a fix round, a follow-up, a retry, and the next queue item. Resume, message, or queue a follow-up on an existing subagent only when the new work strictly needs state that lives in that agent and is costly to move: its local checkout, its uncommitted changes, or a process it still runs, such as a dev server, a simulator, or a babysit watcher. A bare stop or hold order to a running agent is not reuse. A stop order that adds any work is a new task. Check what the agent has committed, stop it, and give the combined scope to a fresh agent. The same holds when the user changes the contract mid-run. A role such as a PR owner outlives its agent. Once that agent returns, a fresh agent takes the role's next round. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary. ## Writing the reply diff --git a/harness/pstack/claude-code/skills/poteto-mode/playbooks/investigation.md b/harness/pstack/claude-code/skills/poteto-mode/playbooks/investigation.md index cd119f04f..b5c2901b5 100644 --- a/harness/pstack/claude-code/skills/poteto-mode/playbooks/investigation.md +++ b/harness/pstack/claude-code/skills/poteto-mode/playbooks/investigation.md @@ -4,7 +4,7 @@ Investigation requests are read-only. They produce a cited explanation or a recommendation, not a code change. -1. Route through the **how** skill. For motivation questions, also route through the **why** skill. +1. Route through the **how** skill. For motivation questions, also route through the **why** skill. Ground in the primary source for the exact version in use (the pinned library source, or a vendor's `/llms.txt` docs index) before docs pages or memory, since docs often trail the pinned version. 2. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only investigation`. 3. Produce the `how`-shaped output (Overview / Key Concepts / How It Works / Where Things Live / Gotchas), or a recommendation with a tradeoffs table if the request is a decision between alternatives. 4. Apply the **unslop** skill to the reply. diff --git a/harness/pstack/claude-code/skills/principle-encode-lessons-in-structure/SKILL.md b/harness/pstack/claude-code/skills/principle-encode-lessons-in-structure/SKILL.md index 4a96f77fe..8be2b67f8 100644 --- a/harness/pstack/claude-code/skills/principle-encode-lessons-in-structure/SKILL.md +++ b/harness/pstack/claude-code/skills/principle-encode-lessons-in-structure/SKILL.md @@ -1,6 +1,6 @@ --- name: principle-encode-lessons-in-structure -description: "Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text." +description: "Apply when you catch yourself writing the same instruction a second time, notice a recurring correction, promise yourself a new habit (I'll remember to...), or dismiss a flake after one clean rerun. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text." disable-model-invocation: true --- diff --git a/harness/pstack/claude-code/skills/principle-explain-the-number/SKILL.md b/harness/pstack/claude-code/skills/principle-explain-the-number/SKILL.md index 1e180c14a..f31a6da1b 100644 --- a/harness/pstack/claude-code/skills/principle-explain-the-number/SKILL.md +++ b/harness/pstack/claude-code/skills/principle-explain-the-number/SKILL.md @@ -1,6 +1,6 @@ --- name: principle-explain-the-number -description: "Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think." +description: "Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result, including any score on data you tuned against, which shows fit, not accuracy. Find what limits it, and rule out that it measured something other than the work you think." disable-model-invocation: true --- diff --git a/harness/pstack/claude-code/skills/principle-guard-the-context-window/SKILL.md b/harness/pstack/claude-code/skills/principle-guard-the-context-window/SKILL.md index 0a1d3cfcf..bad73d027 100644 --- a/harness/pstack/claude-code/skills/principle-guard-the-context-window/SKILL.md +++ b/harness/pstack/claude-code/skills/principle-guard-the-context-window/SKILL.md @@ -1,6 +1,6 @@ --- name: principle-guard-the-context-window -description: "Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads." +description: "Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads. Also apply before summarizing a short report or doc: read it in full, never clipped with head or tail." disable-model-invocation: true --- diff --git a/harness/pstack/claude-code/skills/technical-writing/SKILL.md b/harness/pstack/claude-code/skills/technical-writing/SKILL.md index 903d7d6d2..ec5e4a7a9 100644 --- a/harness/pstack/claude-code/skills/technical-writing/SKILL.md +++ b/harness/pstack/claude-code/skills/technical-writing/SKILL.md @@ -42,7 +42,7 @@ Use the compass on a whole document or on one sentence. **Tutorial: learning by doing.** The learner's success is your job, not theirs. Open by saying what the learner will build, not what they will "learn". Every step produces a visible result, early and often. Tell them what they should see: the expected output, the prompt change, the log line. Cut explanation to one clause and a link. Stay concrete. Write as "we", in commands: "First, do x. Now, do y." -**How-to: steps to a goal.** Solve a problem a person has, not an operation the machine can perform. Assume competence and skip teaching. Action only: no digressions, no background, no completeness for its own sake. Link those instead. Allow forks and judgment: "If you want x, do y." Name the guide by the task: "How to calibrate the radar array", not "Radar array calibration". +**How-to: steps to a goal.** Solve a problem a person has, not an operation the machine can perform. Assume competence and skip teaching. Action only: no digressions, no background, no completeness for its own sake. Link those instead. Allow forks and judgment: "If you want x, do y." Name the guide by the task: "How to calibrate the radar array", not "Radar array calibration". Test a how-to or tutorial by having a fresh agent build something new from the doc alone, with source and examples off limits. Each point where it gets stuck is a hole in the doc. **Reference: facts for lookup.** Only describe. No instruction, no persuasion, no opinion. Be dry, complete, and sure. State facts, options, limits, and errors with no hedging. Mirror the structure of the thing described, so code and docs can be navigated together. Put material where readers expect it. Generate from code where possible. @@ -95,6 +95,7 @@ Don't mix modes: no reference tables inside a tutorial, no tutorial hand-holding - Apply the **unslop** skill to every doc this skill touches. That skill owns the slop-pattern catalog: AI vocabulary, filler, hedging, formatting tells. - PR descriptions and commit messages are writing too. Every layer except Diátaxis applies to them. A PR body is a briefing that a reviewer can read in under a minute. Do not paste swarm logs, SHA lists, or metric tables. Link them. - Product UI strings are not documentation. Use your product's copy guidelines for those. +- A proposal committed to the repo says "Proposal, not built" in its first lines and uses future tense, so later agents don't read it as the current contract. - Indent code snippets with tabs. Write real paths. Make every count or tree claim true at the commit that lands it, and include the command that regenerates it. ## Worked example diff --git a/pstack/docs/harness/claude-code.md b/pstack/docs/harness/claude-code.md index bf154e646..ef609d145 100644 --- a/pstack/docs/harness/claude-code.md +++ b/pstack/docs/harness/claude-code.md @@ -20,10 +20,10 @@ pstack skills use Cursor names. In Claude Code, read this file once per session, | `poteto-agent`, `comment-sicko` | `pstack:poteto-agent`, `pstack:comment-sicko` | | `readonly: true` | `subagent_type: "Explore"`. It keeps `Bash`, so the brief also says "do not edit files", and you check `git status` afterward. | | `readonly: false` | `general-purpose`. It keeps the session's MCP servers. | -| `environment: "cloud"` | `isolation: "worktree"`. Name the branch or commit the worker checks out. | +| `environment: "cloud"` | `isolation: "worktree"`. Name the branch or commit the worker checks out. Gitignored files such as `.env` are not in the worktree, so the brief says to copy them in. The worker cannot `git -C` the main checkout, so the parent does the `merge --ff-only`. Cleanup is `git worktree unlock`, then `git worktree remove`, then `git branch -d`. | | `environment: "local"` | Omit. | | `cloud_base_branch: ` | Tell the worker to check out `` first. | -| `run_in_background: true` | Omit. Subagents run in the background by default and notify you when they finish. | +| `run_in_background: true` | Omit. Subagents run in the background by default and notify you only when they finish. Check a long job's elapsed time yourself through its task output file or `git log main..HEAD` in its worktree. | | `resume` | Spawn a new agent and paste the earlier result into its brief. | | `file_attachments` | List the paths in the brief. | diff --git a/pstack/skills/architect/SKILL.md b/pstack/skills/architect/SKILL.md index 88e23ca10..8103e391f 100644 --- a/pstack/skills/architect/SKILL.md +++ b/pstack/skills/architect/SKILL.md @@ -34,6 +34,10 @@ Design it twice. Require at least two structurally distinct candidates before sy Screen every candidate against [`references/design-red-flags.md`](references/design-red-flags.md) before synthesis. Assume the next contributor is an agent that sees only the files it opened, copies the nearest example, and takes the shortest path that compiles. Prefer the design where a change that looks right from one file is right for the whole repo. +Before comparing, define the counted unit as everything a user must learn (every key, option, verb, and route), not the number of top-level blocks, and set a budget for it. A design can cut blocks while its learned surface stays the same size. + +Test guessability with a blind probe. Show a fresh agent, on a different model, about a third of the surface, have it guess the rest, and score the guesses against an answer key written before the probe. Use the score as the pass bar. After any rename taken from a probe, run a fresh probe, because the old score now measures fit. + Compare viable candidates on interface depth. Prefer the design that hides more complexity behind a smaller, simpler public surface. A rich interface can keep call chains short by concentrating capability instead of scattering it across layers. Arena returns one synthesized design package. Its synthesis decision fills the rationale's "Synthesis decision" section. diff --git a/pstack/skills/blast-radius/SKILL.md b/pstack/skills/blast-radius/SKILL.md index b296cce0d..a42161776 100644 --- a/pstack/skills/blast-radius/SKILL.md +++ b/pstack/skills/blast-radius/SKILL.md @@ -1,6 +1,6 @@ --- name: blast-radius -description: "Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', or reviewing a small diff you don't trust." +description: "Find what a change could break somewhere else before it ships, beyond the diff, and prove the one fact it's safe because of by running real code instead of writing it up. Use for 'blast radius of X', 'what could this break', reviewing a small diff you don't trust, or changing a global default (a model, an embedding, a threshold), where the proof is rerunning the behavior suite, not a capability check." disable-model-invocation: true --- diff --git a/pstack/skills/poteto-mode/SKILL.md b/pstack/skills/poteto-mode/SKILL.md index 21993f546..35ab2dc1d 100644 --- a/pstack/skills/poteto-mode/SKILL.md +++ b/pstack/skills/poteto-mode/SKILL.md @@ -59,7 +59,7 @@ Read the leaf skill in full for any principle you apply. Each entry names when i - **Type System Discipline.** Designing types or a signature in any typed language. Make illegal states unrepresentable, brand primitives, parse external data at boundaries. - **Make Operations Idempotent.** Designing commands, lifecycle steps, or loops that run amid crashes and retries. Converge to the same end state. - **Migrate Callers Then Delete Legacy APIs.** Introducing a new internal API while old callers exist. Migrate and delete in one wave. -- **Separate Before Serializing Shared State.** Concurrent actors might write the same file, branch, key, or object. Eliminate the sharing first. +- **Separate Before Serializing Shared State.** Concurrent actors might write the same file, branch, key, object, database, port, or migration state. Eliminate the sharing first. **Verification** @@ -67,16 +67,16 @@ Read the leaf skill in full for any principle you apply. Each entry names when i - **Fix Root Causes.** Debugging. Trace each symptom back to the first place the system went wrong and fix it there. A guard is a fix only when the state it handles is legitimate. - **Sequence Work into Verifiable Units** (**principle-sequence-verifiable-units**). Multi-step work (sweeps, migrations, runs of similar edits) and how you stack commits and PRs. Break work into small units that each end in a check, verify each before the next, and order delivery so the sequence proves itself. - **Test Behavior, Not Implementation.** Writing, changing, or keeping a test. Assert what the code's users can observe, so the test fails when that behavior breaks and keeps passing when only the internals change. -- **Explain the Number.** Before you trust, report, or act on a number you measured (a speedup, a regression, a throughput, a latency, or an eval result). Find what limits it, and rule out that it measured something other than the work you think. +- **Explain the Number.** Before you trust, report, or act on a number you measured (a speedup, a regression, a throughput, a latency, or an eval result), and any score on data you tuned against, which shows fit, not accuracy. Find what limits it, and rule out that it measured something other than the work you think. **Delegation** -- **Guard the Context Window.** Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread. +- **Guard the Context Window.** Context fills up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents, keep summaries in the main thread. A short deliverable you are about to report from is read in full, never clipped with head or tail. - **Never Block on the Human.** Tempted to ask "should I do X?" on reversible work. Proceed, present the result, let the human course-correct. **Meta** -- **Encode Lessons in Structure.** You catch yourself writing the same instruction a second time. Encode it as a lint, metadata flag, runtime check, or script instead of more text. +- **Encode Lessons in Structure.** You catch yourself writing the same instruction a second time, or promising yourself a new habit ("I'll remember to..."). Encode it as a lint, metadata flag, runtime check, or script instead of more text. ## Autonomy @@ -94,11 +94,17 @@ Read the leaf skill in full for any principle you apply. Each entry names when i **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. +**Briefs about a system you don't know.** Point the agent at the source and make its first deliverable its own cited account of that system. Never write your guess about it into the brief, because the agent echoes a planted framing back as a finding. + +**Watch long jobs by progress, not by clock.** Time estimates are unreliable, so never predict how long work will take, and don't cap a job by the clock. A brief for long work, especially a live or end-to-end run, gives a per-item timeout, so one stuck item can't hold the rest, and a stop-and-report rule for when progress stops. While it runs, check its progress yourself: new commits, items finished, and the same failure or retry repeating. A job with no new progress, or one looping on the same error, gets inspected and stopped or narrowed. A recent commit alone is not evidence it's on track. + +**Parallel agents get their own resources.** Agents in separate worktrees each get databases, ports, and migration state derived from their checkout, never one shared instance. + +**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. When the user changes a role's model or effort, write it into the `/setup-pstack` rule too, not only into memory, so every later spawn picks it up. 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. -**Fresh subagents by default.** Give new work to a fresh subagent with consolidated scope, meaning the original brief, every later directive, and the prior agent's report and branch. This holds for a fix round, a follow-up, a retry, and the next queue item. Resume, message, or queue a follow-up on an existing subagent only when the new work strictly needs state that lives in that agent and is costly to move: its local checkout, its uncommitted changes, or a process it still runs, such as a dev server, a simulator, or a babysit watcher. A stop or hold order to a running agent is not reuse. A role such as a PR owner outlives its agent. Once that agent returns, a fresh agent takes the role's next round. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary. +**Fresh subagents by default.** Give new work to a fresh subagent with consolidated scope, meaning the original brief, every later directive, and the prior agent's report and branch. This holds for a fix round, a follow-up, a retry, and the next queue item. Resume, message, or queue a follow-up on an existing subagent only when the new work strictly needs state that lives in that agent and is costly to move: its local checkout, its uncommitted changes, or a process it still runs, such as a dev server, a simulator, or a babysit watcher. A bare stop or hold order to a running agent is not reuse. A stop order that adds any work is a new task. Check what the agent has committed, stop it, and give the combined scope to a fresh agent. The same holds when the user changes the contract mid-run. A role such as a PR owner outlives its agent. Once that agent returns, a fresh agent takes the role's next round. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary. ## Writing the reply diff --git a/pstack/skills/poteto-mode/playbooks/investigation.md b/pstack/skills/poteto-mode/playbooks/investigation.md index cd119f04f..b5c2901b5 100644 --- a/pstack/skills/poteto-mode/playbooks/investigation.md +++ b/pstack/skills/poteto-mode/playbooks/investigation.md @@ -4,7 +4,7 @@ Investigation requests are read-only. They produce a cited explanation or a recommendation, not a code change. -1. Route through the **how** skill. For motivation questions, also route through the **why** skill. +1. Route through the **how** skill. For motivation questions, also route through the **why** skill. Ground in the primary source for the exact version in use (the pinned library source, or a vendor's `/llms.txt` docs index) before docs pages or memory, since docs often trail the pinned version. 2. Throughput checkpoint stays one line: `throughput checkpoint: n/a, read-only investigation`. 3. Produce the `how`-shaped output (Overview / Key Concepts / How It Works / Where Things Live / Gotchas), or a recommendation with a tradeoffs table if the request is a decision between alternatives. 4. Apply the **unslop** skill to the reply. diff --git a/pstack/skills/principle-encode-lessons-in-structure/SKILL.md b/pstack/skills/principle-encode-lessons-in-structure/SKILL.md index 4a96f77fe..8be2b67f8 100644 --- a/pstack/skills/principle-encode-lessons-in-structure/SKILL.md +++ b/pstack/skills/principle-encode-lessons-in-structure/SKILL.md @@ -1,6 +1,6 @@ --- name: principle-encode-lessons-in-structure -description: "Apply when you catch yourself writing the same instruction a second time, or notice a recurring correction. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text." +description: "Apply when you catch yourself writing the same instruction a second time, notice a recurring correction, promise yourself a new habit (I'll remember to...), or dismiss a flake after one clean rerun. Encode the rule as a lint, metadata flag, runtime check, or script instead of more text." disable-model-invocation: true --- diff --git a/pstack/skills/principle-explain-the-number/SKILL.md b/pstack/skills/principle-explain-the-number/SKILL.md index 1e180c14a..f31a6da1b 100644 --- a/pstack/skills/principle-explain-the-number/SKILL.md +++ b/pstack/skills/principle-explain-the-number/SKILL.md @@ -1,6 +1,6 @@ --- name: principle-explain-the-number -description: "Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result. Find what limits it, and rule out that it measured something other than the work you think." +description: "Apply before you trust, report, or act on a number you measured: a speedup, a regression, a throughput, a latency, or an eval result, including any score on data you tuned against, which shows fit, not accuracy. Find what limits it, and rule out that it measured something other than the work you think." disable-model-invocation: true --- diff --git a/pstack/skills/principle-guard-the-context-window/SKILL.md b/pstack/skills/principle-guard-the-context-window/SKILL.md index 0a1d3cfcf..bad73d027 100644 --- a/pstack/skills/principle-guard-the-context-window/SKILL.md +++ b/pstack/skills/principle-guard-the-context-window/SKILL.md @@ -1,6 +1,6 @@ --- name: principle-guard-the-context-window -description: "Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads." +description: "Apply when context is filling up: large outputs, long files, repeated reads, fan-out planning. Route bulk to subagents; keep summaries in the main thread, not raw payloads. Also apply before summarizing a short report or doc: read it in full, never clipped with head or tail." disable-model-invocation: true --- diff --git a/pstack/skills/technical-writing/SKILL.md b/pstack/skills/technical-writing/SKILL.md index 3e6d26109..62ee3c325 100644 --- a/pstack/skills/technical-writing/SKILL.md +++ b/pstack/skills/technical-writing/SKILL.md @@ -40,7 +40,7 @@ Use the compass on a whole document or on one sentence. **Tutorial: learning by doing.** The learner's success is your job, not theirs. Open by saying what the learner will build, not what they will "learn". Every step produces a visible result, early and often. Tell them what they should see: the expected output, the prompt change, the log line. Cut explanation to one clause and a link. Stay concrete. Write as "we", in commands: "First, do x. Now, do y." -**How-to: steps to a goal.** Solve a problem a person has, not an operation the machine can perform. Assume competence and skip teaching. Action only: no digressions, no background, no completeness for its own sake. Link those instead. Allow forks and judgment: "If you want x, do y." Name the guide by the task: "How to calibrate the radar array", not "Radar array calibration". +**How-to: steps to a goal.** Solve a problem a person has, not an operation the machine can perform. Assume competence and skip teaching. Action only: no digressions, no background, no completeness for its own sake. Link those instead. Allow forks and judgment: "If you want x, do y." Name the guide by the task: "How to calibrate the radar array", not "Radar array calibration". Test a how-to or tutorial by having a fresh agent build something new from the doc alone, with source and examples off limits. Each point where it gets stuck is a hole in the doc. **Reference: facts for lookup.** Only describe. No instruction, no persuasion, no opinion. Be dry, complete, and sure. State facts, options, limits, and errors with no hedging. Mirror the structure of the thing described, so code and docs can be navigated together. Put material where readers expect it. Generate from code where possible. @@ -93,6 +93,7 @@ Don't mix modes: no reference tables inside a tutorial, no tutorial hand-holding - Apply the **unslop** skill to every doc this skill touches. That skill owns the slop-pattern catalog: AI vocabulary, filler, hedging, formatting tells. - PR descriptions and commit messages are writing too. Every layer except Diátaxis applies to them. A PR body is a briefing that a reviewer can read in under a minute. Do not paste swarm logs, SHA lists, or metric tables. Link them. - Product UI strings are not documentation. Use your product's copy guidelines for those. +- A proposal committed to the repo says "Proposal, not built" in its first lines and uses future tense, so later agents don't read it as the current contract. - Indent code snippets with tabs. Write real paths. Make every count or tree claim true at the commit that lands it, and include the command that regenerates it. ## Worked example