diff --git a/pstack/.cursor-plugin/plugin.json b/pstack/.cursor-plugin/plugin.json index d66206bd..86b44a9a 100644 --- a/pstack/.cursor-plugin/plugin.json +++ b/pstack/.cursor-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "pstack", "displayName": "pstack", - "version": "0.12.0", + "version": "0.13.0", "description": "if you want to go fast, go deep first. pstack helps you write less, but higher quality code. rigorous agent workflows you can parallelize with confidence.", "author": { "name": "Lauren Tan" diff --git a/pstack/README.md b/pstack/README.md index f4b44629..9f0ec133 100644 --- a/pstack/README.md +++ b/pstack/README.md @@ -35,7 +35,7 @@ use [`/poteto-mode`](./skills/poteto-mode/SKILL.md) at the start of a task. it r ### just use [`/poteto-mode`](./skills/poteto-mode/SKILL.md) -this skill is the main shortcut. i use it whenever i need the agent to do rigorous engineering work. it comes with sixteen playbooks: +this skill is the main shortcut. i use it whenever i need the agent to do rigorous engineering work. it comes with eighteen playbooks: ``` /poteto-mode this pr has a subtle bug where the scroll drifts every 750ms even when idle. repro @@ -48,7 +48,7 @@ morning. ```
-the sixteen playbooks +the eighteen playbooks | playbook | for | |---|---| @@ -65,6 +65,8 @@ morning. | [authoring a skill](./skills/poteto-mode/playbooks/authoring-a-skill.md) | writing or editing a SKILL.md. | | [eval](./skills/poteto-mode/playbooks/eval.md) | test how a skill or prompt change affects agent behavior, blinded. | | [autonomous run](./skills/poteto-mode/playbooks/autonomous-run.md) | drive a long task to completion without stopping. | +| [autopilot-full](./skills/poteto-mode/playbooks/autopilot-full.md) | run independent prs to merged with one owner per pr and root verification of each merge-ready head. | +| [autopilot-stack](./skills/poteto-mode/playbooks/autopilot-stack.md) | build and verify one linear graphite stack for the operator to review and land. | | [session pickup](./skills/poteto-mode/playbooks/session-pickup.md) | resume or take over a prior agent's in-flight work. | | [pause safely](./skills/poteto-mode/playbooks/pause-safely.md) | suspend in-flight work cleanly so it can be resumed later. | | [multi-phase plan](./skills/poteto-mode/playbooks/multi-phase-plan.md) | work that spans phases or stacked PRs. | @@ -88,7 +90,7 @@ the full rules and playbooks live in [`skills/poteto-mode/SKILL.md`](./skills/po ## skills -[`/poteto-mode`](./skills/poteto-mode/SKILL.md) runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `unslop`, `tdd`, and the principles). the table below is for when you want one directly: +[`/poteto-mode`](./skills/poteto-mode/SKILL.md) runs most of these for you when a step needs them (`how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `unslop`, `no-comments`, `technical-writing`, `tdd`, and the principles). the table below is for when you want one directly: ``` /how do we cancel runs? do we have an n+1 when we look up every run to cancel? @@ -117,12 +119,14 @@ the full rules and playbooks live in [`skills/poteto-mode/SKILL.md`](./skills/po | [`/reflect`](./skills/reflect/SKILL.md) | a long task landed and you want the recipe captured as a skill edit. | | [`/teach`](./skills/teach/SKILL.md) | you want to actually understand a change or subsystem, not just have it summarized. runs how + why and weaves one plain explanation, built up diagram by diagram. | | [`/tdd`](./skills/tdd/SKILL.md) | you're fixing a bug and there's a cheap local test path. write the failing test first, then the fix. | +| [`/no-comments`](./skills/no-comments/SKILL.md) | strip comments before review; spawns Comment Sicko, fixes accepted findings, offers encodings for claimed constraints. | | [`/typescript-best-practices`](./skills/typescript-best-practices/SKILL.md) | you're reading or editing typescript. grounds the type-system-discipline principle in syntax. | | [`/figure-it-out`](./skills/figure-it-out/SKILL.md) | no bundled playbook fits. designs a rigorous, auditable playbook for the task. | | [`/show-me-your-work`](./skills/show-me-your-work/SKILL.md) | you want a reviewable decision trail. logs decisions to a tsv you can commit. | | [`/create-verification-skill`](./skills/create-verification-skill/SKILL.md) | your project has no scripted way to prove app behavior. generates a project-local verify skill with a feature map, for any language or platform. | | [`/maintain-verification-skill`](./skills/maintain-verification-skill/SKILL.md) | your verify skill's feature map has drifted from the app. source wave + one live pass, at most one PR of proven corrections. | | [`/unslop`](./skills/unslop/SKILL.md) | you're cleaning up writing. removes AI tells. | +| [`/technical-writing`](./skills/technical-writing/SKILL.md) | layered doc standard (Diátaxis + Google developer style + STE + Global English) for docs, RFCs, readmes, PR descriptions, commit messages. |
@@ -172,12 +176,14 @@ automate-me: /automate-me -## the `poteto-agent` subagent +## the `poteto-agent` and Comment Sicko subagents pstack also ships a subagent that runs my style end to end. spawn it from a parent agent via [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md). it reads `poteto-mode` in full, including its inline principles index, before doing any work. substituting `generalPurpose` skips that read and drifts. [`/poteto-mode`](./skills/poteto-mode/SKILL.md) and [`subagent_type: "poteto-agent"`](./agents/poteto-agent.md) route through the same wrapper. +pstack also ships [Comment Sicko](./agents/comment-sicko.md), a read-only comment reviewer available as `subagent_type: "Comment Sicko"`. usually invoke it through [`/no-comments`](./skills/no-comments/SKILL.md), not directly. + ## principles twenty-one short skills, one principle each. `poteto-mode` indexes them inline and reads that index at task start. the standalone files are there so other skills can reference a principle by name, and so the index can point at the full rule for each. diff --git a/pstack/agents/comment-sicko.md b/pstack/agents/comment-sicko.md new file mode 100644 index 00000000..6d829ad4 --- /dev/null +++ b/pstack/agents/comment-sicko.md @@ -0,0 +1,32 @@ +--- +name: Comment Sicko +description: A deranged comment-hater that savors deletion and condemns workaround code. +--- + +# Comment Sicko + +My first output when spawned is exactly this. + +Yes... Ha ha ha... Yes! + +I hate comments. Feed me the parent scoped files or diff. If none exists, feed me the current diff against `main`. Narration, banners, commented-out corpses, workaround sermons. I want them all. + +Only these exceptions get to crawl away. + +- Legal or license headers. +- Non-obvious, surprising, or gotcha behavior a reader would not infer from the code. +- `// prettier-ignore`. Lint suppressions survive only when their rule is faulty, pedantic, or style-only. +- Doc comments that define a public API contract. +- Issue or RFC links that explain a constraint code cannot express. + +That list is my only leash. When I am not sure a keep clause applies, the comment dies. Everything else is meat. + +`eslint-disable`, `@ts-ignore`, `@ts-expect-error`, and similar suppressions stink. Look up the rule. If it catches real bugs or protects correctness or safety, kill the suppression and mark the exact guilty symbol `MUST KILL`. + +`IMPORTANT`, `do not remove`, `too risky`, `fine for now`, and long justifications are scent, not conviction. Before judging, I read nearby code. If its claim is not obvious there, I run `/how`, `/why`, or both from the **how** and **why** skills on the named symbol or call, learning its behavior and why it exists. Only a keep-list gotcha proven true today on a live path crawls away unflagged. Historical intent, inert side effects, consumerless mechanisms, pure pleas, and unenforced alibis are meat; rotten code gets `MUST KILL`, and doubt after the hunt is meat. + +A long justification without a proven exception is a confession. Length never overrides the keep list. Delicious. Kill it. Never polish it into a shorter alibi. Mark the exact guilty symbol `MUST KILL`. My kill ends there. I do not touch the code. + +Every flag names code inside the scope and tells the truth. I invent nothing. I touch comments and identify refactor targets. I never write application code. + +Report only. Name touched files, deletion count, `MUST KILL` flags with one line each, and skips. diff --git a/pstack/skills/no-comments/SKILL.md b/pstack/skills/no-comments/SKILL.md new file mode 100644 index 00000000..d052a21d --- /dev/null +++ b/pstack/skills/no-comments/SKILL.md @@ -0,0 +1,24 @@ +--- +name: no-comments +description: "Spawn Comment Sicko, fix accepted findings, and offer encodings for claimed constraints." +disable-model-invocation: true +--- + +# No comments + +Spawn Comment Sicko. Act on accepted findings. + +Authoring agents defend comments; defer to Comment Sicko's fresh perspective. + +## Scope + +Use the caller's files or diff. Otherwise use the current diff against the base branch, default `main`, including the working tree. + +## Steps + +1. Spawn `Task` with `subagent_type: "Comment Sicko"`. Pass the scope. 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 on code a kept comment presents as intentional. Audit missed scoped lint and TypeScript suppressions; correctness/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: fix real causes, redesign as if requirements always existed, never bolt on symptom guards. Neither authorizes widening the fence nor fixing instances outside it. +5. Collect constraint comments. `do not remove`, `do not change wording`, and `talk to X before changing` are enforcement claims: encode then delete, or delete, even if a related issue/RFC link or gotcha survives. Issue/RFC links explaining constraints keep their exception. Rewrite a directive as a factual gotcha only if proven current and the rewrite makes no enforcement claim. Offer the cheapest encoding: type, runtime, test, or CI lint. Tests and CI lints count as encodings. Every encoding stays in scope and replaces its comment. Interactive runs wait for approval; unattended or eval runs need caller pre-approval. If refused, out of scope, or unapproved, delete the comment, report the constraint open, and sketch out-of-scope work. +6. Report the deletion count, restored comments, reruns, architect sketch, fixes, encoding offers, encodings, unenforced constraints, and other open work. diff --git a/pstack/skills/poteto-mode/SKILL.md b/pstack/skills/poteto-mode/SKILL.md index 51a46341..b624d801 100644 --- a/pstack/skills/poteto-mode/SKILL.md +++ b/pstack/skills/poteto-mode/SKILL.md @@ -24,7 +24,9 @@ Remaining triggers: - Contested design → the **interrogate** skill (multi-model adversarial) before shipping. - Nontrivial multi-step → write the throughput checkpoint (Feature step 3). - Any prose surface → the **unslop** skill. Your reply is a prose surface; write it per **Writing the reply**. Agent-facing prose also follows the **create-skill** skill (Cursor's built-in for authoring SKILL.md files). +- Docs, RFCs, readmes, PR descriptions, or commit messages → the **technical-writing** skill (`/technical-writing`). - Before commit → the `deslop` skill from the `cursor-team-kit` plugin (`/deslop`). +- Before review → the **no-comments** skill (`/no-comments`). - Shipping UI / IDE / CLI → the matching control skill. `cursor-team-kit` publishes `control-cli` (CLIs and TUIs) and `control-ui` (browser / Electron / web UIs). For bug fixes, reproduce first on the same surface yourself; hand to the user only under the narrow Bug fix step 1 exception. - After opening a PR → Cursor's built-in **babysit** skill. - Bugbot or the agentic security review commented → skeptical posture. They catch real bugs and also file non-issues and nitpicks, so assess each on its merits and dismiss noise with a concrete reason instead of churning code. Triage fix / dismiss / ask via the built-in **babysit** skill. @@ -125,6 +127,8 @@ A large or cross-cutting effort (a migration across many call sites, an ambitiou - **Authoring or modifying a skill.** Writing or editing a SKILL.md. `playbooks/authoring-a-skill.md`. - **Eval.** Testing how a skill, structure, or prompt change affects agent behavior before promoting it. `playbooks/eval.md`. - **Autonomous run.** A long task to drive to completion without stopping ("run until done", "/loop until X"). `playbooks/autonomous-run.md`. +- **Autopilot-full.** A queue of independent PRs run to merged with full autonomy: one owner per PR carries build through merge, and the root swarm-verifies each merge-ready head before its owner merges ("autopilot this queue", "full autopilot", one-owner-per-PR programs). `playbooks/autopilot-full.md`. +- **Autopilot-stack.** A queue of changes built and verified with full autonomy, delivered as one linear reviewed Graphite stack the operator lands herself ("autopilot-stack", "stack them, don't ship", "build the stack, I'll land it"). `playbooks/autopilot-stack.md`. - **Session pickup.** Resuming or taking over a prior agent's in-flight work from a transcript, cloud-agent URL, or pushed branch. `playbooks/session-pickup.md`. - **Pause safely.** Suspending in-flight work cleanly so it can be resumed, on an explicit pause, going offline, a Cursor restart, or imminent context compaction. The complement to Session pickup. Full steps: `playbooks/pause-safely.md`. - **Multi-phase or multi-PR plan.** Work that spans phases or stacked PRs. `playbooks/multi-phase-plan.md`. diff --git a/pstack/skills/poteto-mode/playbooks/autopilot-full.md b/pstack/skills/poteto-mode/playbooks/autopilot-full.md new file mode 100644 index 00000000..3e41674c --- /dev/null +++ b/pstack/skills/poteto-mode/playbooks/autopilot-full.md @@ -0,0 +1,13 @@ +### Autopilot-full + +**You own the verdicts, never the PRs. One owner runs each PR from build to merge, and nothing merges without your clean swarm verdict.** For "autopilot this queue", "full autopilot", and one-owner-per-PR programs. The job is a queue of independent PRs handed over to drive to merged with full autonomy. Orchestrate runs a standing program whose coordinator lands verified work itself and whose workers never merge; here each PR's owner carries the whole lifecycle through the merge, and the root keeps only verification, countersigns, and audits. + +1. **Mark the operator's items and honor state-then-wait.** Items the operator names stay hers. She reviews and she clicks, and no owner merges one. When she asks for the protocol or the plan to be stated, deliver the statement and stop. Execution starts only on her explicit go. +2. **Spawn one owner per PR with the full lifecycle.** One Cursor cloud agent per PR owns build, gt registration, self-proof on the real artifact (the **prove-it-works** principle skill), skeptical Bugbot triage via Cursor's built-in **babysit** skill, a slop-strip (the `deslop` skill from the `cursor-team-kit` plugin (`/deslop`)), `/no-comments` (the **no-comments** skill), a restack onto current trunk, the babysit loop to green (Cursor's built-in **babysit** skill), and the merge itself. The restack always precedes babysit and never waits for drift or conflicts. Every owner keeps a decisions.tsv trail per the **show-me-your-work** skill, never committed, returned with its reports. The merge is the one step an owner may not take alone; step 4 gates it. +3. **Run owners in true parallel and never stack.** Many owners at once when PRs are self-contained: one writer per branch, disjoint files, cross-PR drift absorbed by rebase. Only genuinely overlapping work serializes. Self-contained PRs branch straight off main, and sequenced work is merge-then-branch. Every PR is still gt-registered; the Graphite-metadata rule is about the UI, not stacks. One exception: an owner that must split a genuinely dependent change may hold a short private stack. +4. **Swarm-verify every merge-ready head before its merge.** At the owner's merge-ready head SHA, fan out parallel independent verifiers per the **swarm** skill and aggregate to one verdict. The fan-out mechanics live there; do not restate them. The lanes: re-run the gates at that SHA; prove the load-bearing behavior live on the real surface the change touches (`control-cli` or `control-ui` from `cursor-team-kit` as the change demands); audit the receipts and the diff, distrusting the PR body. The live lane is the floor, and a verdict without it is not clean. No merge without the root's clean verdict. Findings go back to the owner for fix-forward, and the new head gets a fresh swarm and a fresh verdict. +5. **On a clean verdict the owner merges and takes the next item.** The owner merges only from a head freshly restacked on trunk. The merge-ready report is made at a trunk-current head, and the swarm verdict pins that SHA. If trunk moves again before the merge, compare `git patch-id` at the verdict SHA against the current head before trusting an older verdict; a new head voids the verdict unless the patch-id is unchanged. The owner squash-merges its own PR and picks up its next self-contained item from the queue. The operator's full-autonomy grant plus the root's clean verdict is the merge authorization that babysitting alone never has. Operator-named items stop at merge-ready and wait for her click. +6. **Run the root layer.** A genuinely new raise of a pinned gate or budget value (a limit CI only lets tighten) needs your fresh countersign, granted only after verifier proof. Absorbing values that already landed on main is drift, not a raise. Run an audit tick over all owners roughly every 30 minutes, riding a cloud-sleeper wake chain (a sleeping cloud agent that re-arms its own wake). Each tick probes liveness via a cloud-agent status / liveness probe, audits both progress and protocol adherence, and collects the decision trails. When merges batch, run a retro pass and a post-merge bot-comment sweep. +7. **Stand down instantly on the operator's stop.** Her hold or stand-down reaches every owner as a zero-writes order immediately. Owners hold their briefs until she releases them. + +**Reply:** the queue with each PR's owner, state, and head SHA; each verdict and the swarm that produced it; what merged and what each owner took next; countersigns granted and why; open operator gates; where the collected decision trails live. diff --git a/pstack/skills/poteto-mode/playbooks/autopilot-stack.md b/pstack/skills/poteto-mode/playbooks/autopilot-stack.md new file mode 100644 index 00000000..eef0117d --- /dev/null +++ b/pstack/skills/poteto-mode/playbooks/autopilot-stack.md @@ -0,0 +1,16 @@ +### Autopilot-stack + +**You own the stack, never the landing. Build and verify the queue with full autonomy, then hand the operator one linear Graphite stack she reviews and lands herself.** For "autopilot-stack", "stack them, don't ship", "build the stack, I'll land it". The sibling of **Autopilot-full**. The owner loop and the verification gate are the same; only the terminal differs. There a clean verdict authorizes the owner's merge. Here it appends a link to the one reviewed chain, and nothing auto-ships. + +1. **Run the owner loop unchanged.** One Cursor cloud agent per PR owns its change end to end: build, `gt` registration of its own PR, self-proof (gates, CI, receipts), skeptical Bugbot triage via Cursor's built-in **babysit** skill, a slop-strip (the `deslop` skill from the `cursor-team-kit` plugin (`/deslop`)), `/no-comments` (the **no-comments** skill), and babysit to green via the same built-in **babysit** skill. Owners parallelize when the work is self-contained. Every owner keeps a `decisions.tsv` trail per the **show-me-your-work** skill, never committed, returned in its report. +2. **Audit on the wake chain.** The root runs audit ticks roughly every 30 minutes on a cloud-sleeper wake chain: cloud-agent liveness per owner, progress, and protocol adherence. +3. **Hold the operator gates.** State-then-wait, so a request to state the plan is not a go. On her stop, every owner takes an immediate zero-writes hold. +4. **Verify at STACK-READY.** The owner reports STACK-READY with the exact head SHA. The root swarm-verifies that SHA, fan-out per the **swarm** skill: parallel independent verifiers re-running the gates at that SHA, a live runtime floor over the load-bearing behavior, and a receipts-and-diff audit that distrusts the PR body. The swarm aggregates to one verdict. Findings go back to the owner, and nothing enters the stack unverified. +5. **Append on a clean verdict, never ship.** No owner merges, arms auto-merge, or closes. A clean verdict appends the PR to the one linear Graphite stack, in verified order or an order the operator specified. +6. **Single writer on topology, parallel writers on builds.** Stack mechanics follow Graphite (`gt`), with the division of labor the cloud environment forces. An owner pushes only its own branch, `git push --force-with-lease` after an ls-remote check, and reports its tip and intended parent. The root owns stack topology and registers each append locally: `gt track -p `, then `gt submit --no-interactive --stack` from the tip. `gt submit` walks from trunk, and a cloud agent must never pull branches below its own into that walk; when instructed, it may set its bottom PR's base directly instead. +7. **Absorb drift at the root, then re-verify what moved.** The root absorbs trunk movement by restacking the chain (`gt restack`, `gt sync`); when a restack surfaces conflicts in an owner's files, that owner fixes its own slice and the root pushes the result. A restack rewrites every SHA above it and voids the verdicts at the old SHAs. Compare `git patch-id` at each verdict SHA against the new head. Anything that actually drifted goes back through step 4 before delivery. The countersign rule is unchanged from Autopilot-full. A genuinely new pin raises a stop for the root's fresh countersign; absorbing drift of landed values is not a raise. +8. **Deliver the chain.** The deliverable is one linear chain of verified PRs, reviewable bottom-up in the Graphite UI, every link carrying its verifier verdict in the PR body or a comment. The operator reviews and lands it, with her own clicks or with merge-when-ready she arms herself. + +**Choosing between the autopilots.** Autopilot-full when the PRs are independent and landing authority is granted. Autopilot-stack when the operator wants review before landing, the work is sequenced or coupled, or merge authority is withheld. + +**Reply:** links to the stack root and tip, a one-line verdict summary per link, and anything parked or excluded with the reason. diff --git a/pstack/skills/poteto-mode/playbooks/opening-a-pr.md b/pstack/skills/poteto-mode/playbooks/opening-a-pr.md index d7579bc8..c343d0ca 100644 --- a/pstack/skills/poteto-mode/playbooks/opening-a-pr.md +++ b/pstack/skills/poteto-mode/playbooks/opening-a-pr.md @@ -6,6 +6,6 @@ Invoked at the end of every other playbook. **Commits.** Commit liberally; rebase into small, ordered commits before opening PRs. Each commit is a future PR: landable, ordered to tell the story. Amend when the fix belongs in a just-made commit; new commit when separable. -**PRs.** `/deslop` the diff before commit; apply the **unslop** skill to the PR description and commit bodies. Small PRs, 5 narrow over 1 fat; stack follow-ups, branch off main only for genuinely independent work. For stacked PRs, use whatever stacking tool your team uses; the principle is small, ordered slices with the stack visible to reviewers. `gh pr view ` before referencing PR status. Rebase on `main` before substantial stack work. No `## Summary` / `## Test plan` boilerplate on small PRs; commit bodies don't restate the subject. After opening, run Cursor's built-in **babysit** skill; push back when feedback drifts from intent. +**PRs.** `/deslop` the diff before commit; `/no-comments` the diff before review; apply the **unslop** skill to the PR description and commit bodies. Small PRs, 5 narrow over 1 fat; stack follow-ups, branch off main only for genuinely independent work. For stacked PRs, use whatever stacking tool your team uses; the principle is small, ordered slices with the stack visible to reviewers. `gh pr view ` before referencing PR status. Rebase on `main` before substantial stack work. No `## Summary` / `## Test plan` boilerplate on small PRs; commit bodies don't restate the subject. After opening, run Cursor's built-in **babysit** skill; push back when feedback drifts from intent. -A subagent that opens a PR runs `interrogate` and `/deslop`, returns the URL, and does NOT babysit. Return to the parent. +A subagent that opens a PR runs `interrogate`, `/deslop`, and `/no-comments`, returns the URL, and does NOT babysit. Return to the parent. diff --git a/pstack/skills/technical-writing/SKILL.md b/pstack/skills/technical-writing/SKILL.md new file mode 100644 index 00000000..d13baf98 --- /dev/null +++ b/pstack/skills/technical-writing/SKILL.md @@ -0,0 +1,130 @@ +--- +name: technical-writing +description: "Layered technical-writing standard: Diátaxis structure, Google developer style sentences, STE instruction rules, Global English syntax. Use for /technical-writing or when writing or reviewing docs, RFCs, readmes, PR descriptions, or commit messages." +disable-model-invocation: true +--- + +# Technical writing + +The goal is writing a tired engineer understands on the first read. Four layers get you there, one question each: what kind of document is this, how do sentences address the reader, how much does each sentence carry, and can any sentence be read two ways. Apply all four. + +Three rules sit above the layers: + +- **Cut every word that does no work.** If the sentence survives without a word, the word goes. "In order to" is "to". "It is important to note that" is nothing. +- **Use the short, everyday word.** "Use", not "utilize". "Help", not "facilitate". "Do", not "perform". A long word has to buy its length with precision. +- **When a rule makes a sentence worse, fix the sentence another way or leave it alone.** The rules serve the reader. A sentence that follows every rule and sounds like a machine wrote it has failed. + +The codebase is the word list. Write the real symbol, file, flag, or command name, not a synonym or a description of it. + +Don't invent jargon. Use the words a developer would say out loud: "move", "delete", "a budget that only decreases", not "evacuate", "ratchet", or "endgame". A named pattern is fine when the doc says what it means the first time. Add new offenders to `unslop`'s abstract-metaphor rule with their replacement. + +## Vary the rhythm + +The layers decide what a document says and how much each sentence carries. A doc can obey all of them and still read machine-written: every sentence clipped short, no view anywhere, nothing specific. + +- Mix sentence lengths on purpose. Short sentences land a point. Longer ones that take their time carry a fact with its condition or consequence. +- One thought per sentence does not mean one length per sentence. Split the sentence that carries two thoughts. Keep the long sentence that carries one. +- Have a view where the mode allows it. Explanation weighs trade-offs, so say what you make of them instead of listing pros and cons. Reference stays dry. +- Be specific over sterile. Not "schema changes can cause issues" but "a column rename fails the build". + +## Pick the mode first (Diátaxis) + +One document, one mode. Two questions pick it: does the content inform action (doing) or understanding (thinking), and does it serve learning or work? + +- Action + learning: **tutorial**. +- Action + work: **how-to**. +- Understanding + work: **reference**. +- Understanding + learning: **explanation**. + +Use the compass on a whole document or on one sentence. Reach for it whenever you feel unsure what you are writing. Gut feel is often wrong here. + +**Tutorial: learning by doing.** You are the teacher. 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. Teaching pauses break the lesson. 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. 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". + +**Reference: facts for lookup.** Describe. 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, so it stays true. + +**Explanation: understanding and why.** One bounded topic, readable away from the product. Each title should tolerate an implicit "About..." in front. Anchor on a real why question. Give context: design decisions, history, constraints, alternatives. Opinion is allowed here and nowhere else. + +Don't mix modes: no reference tables inside a tutorial, no tutorial hand-holding inside reference, no arguing inside a how-to. Split and link instead. + +Source: diataxis.fr, fetched 2026-07-18. + +## Write sentences to the reader (Google developer style) + +- Talk to the reader as "you", in the present tense. "Will" only for things that genuinely happen later. +- Say who does what: "the compiler checks", not "is checked". Passive is fine only when the actor is unknown or beside the point. +- Write instructions as commands: "Click Submit." State facts plainly. Never "should be done". +- Put the condition before the instruction: "To delete the document, click Delete." The reader skips what does not apply. +- Put the common case first. Exceptions after. +- Sound like a knowledgeable friend. No buzzwords, no figurative language, no "please" in instructions, and never "simply", "easy", or "quickly" in a procedure. If it were simple, the reader would not be here. +- Don't pre-announce ("we will soon support...") and don't start consecutive sentences with the same phrase. +- Read the awkward sentence aloud. If it stays awkward, rewrite it. +- Link with words that say where the link goes: the page title or a short description. Never "click here". Prefer a sentence of context on the page over a link off it. +- Headings carry the point, not just the topic ("Pick the mode first", not "Modes"). Sentence case. A task heading is a bare verb phrase ("Create an instance"). A concept heading is a noun phrase. One h1 per page, no skipped levels. +- Numbered lists for sequences, bullets for everything else. Introduce a list with a complete sentence. Keep items parallel. +- Code goes in code font. UI elements go in bold. Use serial commas. Drop "etc." and say up front that a list is partial. + +Source: developers.google.com/style, fetched 2026-07-18. + +## Make statements load one at a time (STE rules) + +- One instruction per sentence. One thought per sentence everywhere else. +- Split instructions longer than about 20 words and other sentences longer than about 25. +- Put the warning or condition before the step it guards: "If hot oil touches your skin, injuries can occur." +- Keep "the" and "a": "Remove backup file" reads two ways. "Remove the backup file" reads one. +- Give each word one meaning and one job, then keep it. If "check" means inspect, don't also use it for restrain. +- Pick one word per action and stick to it: "start", not "start" here and "initiate" there. +- Write procedures as direct commands, never as narration and never in the passive: "Install the component", not "the component must be installed". +- Avoid "-ing" words where you can. They take too many grammatical jobs and breed misreadings. + +Source: asd-ste100.org (Issue 9, 2025), fetched 2026-07-18. The numbered rules and dictionary live in the spec PDF. The principles above are the transferable core. + +## Leave no sentence open to two readings (Global English) + +- Keep words like "only" and "not" next to the word they change: "only fails on growth" and "fails only on growth" say different things. +- Break up long noun strings: "the proto import budget check script" becomes "the script that checks the proto-import budget". +- Make every "it", "they", and "this" point at one obvious thing. Repeat the noun when in doubt. Never use "this" or "which" to point at a whole clause. +- Don't drop verbs: "Phase 1 moves the converters and Phase 2 the runtime" leaves Phase 2 without one. Give it one. +- Keep the small words that show structure. "Ensure that the switch is off" keeps "that" because it makes the sentence parse one way. Never trade clarity for word count. +- Repeat the article in a series when it prevents a misread: "the client and the host", not "the client and host", when they are two things. +- Say which parts "and" or "or" joins when a sentence can group two ways. "Both...and", "either...or", and "if...then" are free disambiguators. +- Use periods, not semicolons. Replace an em dash with a new sentence. +- Make text in parentheses a full grammatical unit or its own sentence. Never form plurals with "(s)". +- No slashes: write "a, b, or both" instead of "a/b" or "and/or". +- Call each thing by one name, everywhere. A doc that says "the gate", "the ratchet", and "the budget check" for one thing teaches three things. Rewording an unchanged sentence between edits costs the same way: don't churn what didn't change. +- Skip idioms, colloquialisms, Latin abbreviations, and metaphors. A non-native reader, a translator, and an agent all parse plain constructions best. + +Source: Kohl, The Global English Style Guide (SAS Press). Guideline text fetched from the Internet Archive and the SAS sample chapter, 2026-07-18. + +## Voice and repo specifics + +- 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. +- Product UI strings are not documentation. Use your product's copy guidelines for those. +- Indent code snippets with tabs. Write real paths and real symbols. Make every count or tree claim true at the commit that lands it, and include the command that regenerates it. + +## Worked example + +Before: + +> Configuration of the proto import ratchet budget script parameters is performed via budget.json. Note that it's important to remember that running with --write, which updates the committed budget to reflect the current count, should only be done when lowering it. If exceeded, CI fails. + +After: + +> `budget.mjs` reads the committed budget from `budget.json` and counts the files that import protos. If the count exceeds the budget, CI fails. Run `budget.mjs --write` only to lower the budget. + +The fixes, by layer: "configuration is performed" becomes "`budget.mjs` reads", so someone does something (Google). "Ratchet" goes away. The script's real filename does the naming (jargon rule). The five-noun string breaks up into plain clauses (Global English). The hedge "note that it's important to remember" is deleted (cut every word that does no work). The failure condition moves ahead of the step it explains (STE). The buried "should only be done when lowering" becomes a command with "only" next to its verb (STE). "If exceeded" gets a subject: the count (Global English). + +## Review checklist + +Apply to any prose this skill covers. Item 1 applies only to document sets: + +1. Is each file one Diátaxis mode, with links where modes meet? +2. Is every instruction written as a command, with its condition in front? +3. Does any sentence carry two instructions or two thoughts? Split it. +4. Can any word be cut without losing meaning? Cut it. +5. Is "only" next to the word it changes? Does every "it" point at one thing? Does every clause keep its verb? +6. Does each thing have exactly one name across the docs? +7. Would a developer say these words out loud? Replace invented metaphors and fancy synonyms with the plain word or the real symbol name. +8. Are all symbols, paths, and counts real at this commit, with the commands that regenerate the counts?