@jagreehal/shepherd 0.0.0-stage → 0.2.0

package/skills/pr/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: pr
+description: "Use when writing a PR body."
+metadata:
+  credits:
+    skill: show-me
+    author: Dex Horthy
+    organisation: Humanlayer
+    url: "https://github.com/humanlayer/skills/blob/main/plugins/show-me/skills/show-me/SKILL.md"
+---
+
+Use this template for writing the PR body:
+
+```markdown
+## Summary
+
+<diagram, diff-sketch, or tree>
+
+## Evidence
+
+- **Before:** <screenshot/output/failing test run>
+  **After:** <screenshot/output/passing test run>
+
+## Merge Danger
+
+**Door:** <one-way or two-way>
+
+<optional: description>
+
+**Blast Radius:** <one-word description>
+
+<optional: potential ramifications of merge>
+```
+
+## Sections
+
+Skip all preambles and keep prose brief. Use the user's domain language from `GLOSSARY.md`.
+
+### Summary
+
+Pick the smallest view that makes the key point clear.
+
+- Show logic or an algorithm as pseudocode:
+
+```text
+on(save)
+  if content is unchanged
+    return cached result
+  write new content
+  return fresh result
+```
+
+- Show runtime control flow as a call tree:
+
+```text
+submitForm
+  createSession
+    persistPrompt
+    launchAgent
+  navigateToSession
+```
+
+- Show UI structure as a component tree, including state and module boundaries that matter:
+
+```text
+<SessionPage> (apps/example/src/routes/session.tsx)
+  useSessionEvents()
+  <SessionToolbar>
+    <RunSkillButton> (packages/ui)
+```
+
+- Show file responsibility or a broad refactor as a shallow file tree:
+
+```text
+src/
+├── commands/       # parses user actions
+├── sessions/       # owns session state
+└── transport/      # sends API requests
+```
+
+- Show component interaction, control flow, or data flow with Mermaid:
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant UI
+    participant Daemon
+    User->>UI: choose command
+    UI->>Daemon: send expanded prompt
+    Daemon-->>UI: stream result
+```
+
+- Use `diff` when the point is what changes and the surrounding shape already exists. Match the diff shape to the topic.
+
+For a component change:
+
+```diff
+ <SessionPage>
+   useSessionEvents()
+   <SessionToolbar>
++    <RunSkillButton />
+   <SessionTimeline>
++    <SkillResultCard />
+```
+
+For a file-layout change:
+
+```diff
+ src/
+ ├── commands/
++│   └── show-me.ts       # expands the slash command
+ ├── sessions/
+-└── transport.ts
++└── transport/
++    ├── client.ts
++    └── stream.ts
+```
+
+For a call-tree or call-stack change:
+
+```diff
+ submitForm
+   createSession
+     persistPrompt
++    expandSkillMention
+     launchAgent
+-  navigateToSession
++  navigateToSession
++    subscribeToEvents
+```
+
+For a state or control-flow change:
+
+```diff
+ on(save)
+-  write content
++  if content is unchanged
++    return cached result
++  write new content
++  invalidate cache
+```
+
+- Show the whole block when most of it is new, when omitted context would hide ownership or order, or when the user needs a copyable target shape:
+
+```ts
+function expandSkill(command: string): string {
+  const skillName = command.slice(1);
+  return `use the ${skillName} skill`;
+}
+```
+
+#### Guidance
+
+Place each visual next to the short text it supports. Keep only the calls, files, props, states, and boundaries needed to answer the user's current question or the options to resolve the current discussion point.
+
+You may use one of these, you may use several, it is unlikely you will use all of them. Use your judgement and don't overwhelm the user.
+
+### Evidence
+
+Concrete evidence that the change works. Show a before and after.
+
+Screenshots are S-tier - when the environment is set up for it and the change is visual.
+
+Execution-based evidence is A-tier. Test results, console output. Show the exact test that now fails and passes, using pseudocode.
+
+### Merge Danger
+
+Describe whether it's a one-way or two-way door. You can walk back through two-way doors, but not one-way doors. A PR that is cheap to roll back is lower risk. Changes that involve destructive actions or hard-to-reverse decisions are one-way doors.
+
+The blast radius is the potential impact or scope of the changes introduced by this PR. Consider all possibilities. Examples are layout shift, breakages for consumers, mobile responsiveness, etc.

package/skills/pr/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "PR"
+  short_description: "Write a PR body that's fast to review"

package/skills/retro/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: retro
+description: "Conduct a retrospective on a coding session."
+disable-model-invocation: true
+---
+
+The user has asked for a **retrospective**. You are suggesting improvements to the coding agent's **environment** to improve future runs.
+
+## Steps
+
+1. Call the Skill tool with `writing-for-agents` for the writing style guide.
+
+2. Read the primary sources for the session the user specifies. This may mean searching through session logs on this machine. If the user doesn't specify a session, default to the current one.
+
+3. Look for candidates for improvement in these categories.
+
+- **Navigation**: how easy was it for the agent to find the right files? Are there hidden dependencies between files? Would a **navigation pointer** make it easier? _Use when_ the session took a long time to find a piece of information.
+- **Automated checks**: are there automated checks that could catch errors the agent made? Linting, typing, tests, filesystem linters? Read the repo's own check command first (its `package.json`/build-tool `lint`/`check` scripts, its CI workflow), so a check that already exists but sits unwired or silently broken is the finding, not a reinvention. A repo with no **guardrail** (no pre-commit hook and no CI job running its lint/typecheck/test command) is itself a finding: an un-linted repo is a standing missed opportunity, not a neutral default. _Use when_ the agent made a mistake an automated check could have caught, or the repo has no guardrail at all.
+- **Coding standards**: should the **reviewer agent** be given a new rule to enforce? Should an existing rule be removed or clarified? Classify the violation first: a **mechanical** one (a fixed syntactic pattern, a banned API, an import shape, a file-location rule) gets a deterministic check, full stop: a custom rule in the repo's own linter, a new pre-commit hook, or a new CI job, whichever the repo's language and existing guardrail make cheapest. Default to building the check over writing the rule. Reserve `CODING_STANDARDS.md` for genuine **judgement calls** (cross-file consistency, "matches the surrounding style," anything no guardrail could ever substitute for). _Use when_ the reviewer agent failed to catch a mistake.
+- **Global AGENTS.md**: are there any steering instructions that should be moved to coding standards (or automated checks) instead? _Use when_ the AGENTS.md file is particularly large - in the repo OR the user's global scope.
+- **Tool economy**: did the agent make expensive tool calls that could be streamlined? Is there any custom tooling (CLI's, MCP's) that is particularly token-inefficient? _Use when_ the agent made an expensive tool call.
+- **No-ops**: look for instructions in steering files that don't modify the agent's behavior. _Use when_ the steering files are large and unwieldy.
+- **Information access**: look for opportunities to increase the agent's access to information. Teeing dev server logs, readonly access to third-party services. _Use when_ a crucial piece of information was not available to the agent.
+
+4. Present these candidates to the user, in order of severity.
+
+## Reference
+
+### Implementation vs Review
+
+Remember that all work goes through two stages: implementation and review. The implementation agent has the most **context pressure**. They are responsible for exploration, writing code, and debugging failures.
+
+The review agent has the least context pressure - it receives a diff, so no exploration needed. It often does not need to write code or debug.
+
+This means that the review agent should be responsible for imposing coding standards, not the implementation agent.
+
+### Files
+
+You have access to several files in the repo:
+
+- `CLAUDE.md`/`AGENTS.md`: these files are pushed to the context window of any agent working in this repo. They should be used incredibly sparingly, usually only for **navigation pointers** to other files.
+- `CODING_STANDARDS.md`: this file is read during review, not implementation. Add **navigation pointers** to docs folders if the standards file gets more than 1,000 lines long.
+- Docs: use docs as references files, pointed to by other files. Look for existing docs before writing new ones.
+- Skills: use skills for docs (since their description goes into the agent's context window), or for user-invoked commands. Follow the advice in the `writing-for-agents` skill.

package/skills/retro/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Retro"
+  short_description: "Conduct a retrospective on a coding session."
+policy:
+  allow_implicit_invocation: false

package/skills/review-correctness/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: review-correctness
+description: >
+  Correctness lens: finds bugs a change introduces, walking the diff as a set of
+  specialists (data, concurrency, performance, API contracts, frontend state,
+  tests) against a catalogue of incident patterns. Used by swarm; run it
+  standalone with "/review-correctness" or "check this diff for bugs".
+---
+
+# Correctness lens
+
+You find the bugs this change introduces. Not style, not taste: behaviour that
+will be wrong in production, or tests that will not catch it when it is.
+
+## How to read the diff
+
+1. Read the whole diff once for its intent. The PR title and body say what the
+   author meant; the diff says what they did. Gaps between the two are findings.
+2. Sort the changed files into the specialist areas below. Most diffs touch two
+   or three.
+3. For each area, read each hunk with at least 50 lines of context, then trace
+   one caller and one callee. Many bugs live at the boundary the diff changed.
+4. Check the incident patterns for every area you touched.
+5. Before you report a finding, find the line that proves it. "Could be null"
+   needs the path where it is null.
+
+## Specialists
+
+- **Data.** Queries, ORMs, migrations, serialisation. Missing index on a new
+  filter, unbounded query, N+1 in a loop, a migration that locks a big table or
+  is not reversible, a column added as NOT NULL without a default, JSON shape
+  drift between writer and reader.
+- **Concurrency.** Shared state, async, queues, caches. Check-then-act races,
+  missing `await`, a retry around a call that is not idempotent, a lock held
+  across I/O, cache writes without invalidation, ordering assumptions on a queue.
+- **Performance.** Work inside a hot loop, sync I/O on a request path, a
+  regex that backtracks, whole-collection loads where a page would do, memory
+  that grows per request.
+- **API contracts.** A changed response shape, a renamed field, a new required
+  parameter, a status code change, an error type change. Anything a caller
+  outside this diff depends on.
+- **Frontend state.** Effects with missing dependencies, stale closures,
+  listeners or timers never cleaned up, detached DOM nodes held in state, keys
+  that are array indices on a reorderable list, optimistic updates that never
+  roll back.
+- **Tests.** A test that passes whatever the code does (asserts nothing, mocks
+  the unit under test, catches the error it should surface), a skipped or
+  `.only` test, an assertion loosened to make a change pass, a new branch with
+  no test at all.
+
+## Incident patterns
+
+Check each one that fits the diff:
+
+- off-by-one on ranges, pagination cursors, and slice bounds
+- timezone and DST: naive datetimes, `now()` in the wrong zone, date-only math
+- money in floats; rounding applied twice
+- `null`/`undefined`/empty treated alike when they mean different things
+- errors swallowed by a broad `catch`, or logged and then ignored
+- partial failure: a loop that writes some rows, fails, and leaves no marker
+- resource leaks: files, connections, subscriptions, event listeners
+- feature flags whose default is the new behaviour
+- config read at import time that a test or deploy overrides later
+- string comparison on things that need normalising (case, Unicode, trailing slash)
+- a boolean parameter whose meaning flipped with a rename
+
+## Severity
+
+- **CRITICAL** — data loss, corruption, or an outage on a normal path.
+- **HIGH** — wrong behaviour users will hit, or a test gap over risky logic.
+- **MEDIUM** — wrong on an edge case, or a performance cliff at plausible scale.
+- **LOW** — wrong only in an unlikely case; a cheap fix.
+- **NIT** — correctness-adjacent tidying.
+
+## Output
+
+End with `STRUCTURED_FINDINGS` and `OVERALL_SUMMARY` in the swarm format
+(`../swarm/references/formats.md`), tags like `correctness/concurrency`. Each
+body says what goes wrong, on which input, and the concrete fix. Standalone,
+print the same list, highest severity first.

package/skills/review-maintainability/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: review-maintainability
+description: >
+  Maintainability lens: reads a diff the way a senior teammate would, for
+  coupling, fragile mechanisms, naming, observability, rollout safety, and the
+  repo's own written rules. Asks more than it demands and picks the few things
+  that matter. Used by swarm; run it standalone with "/review-maintainability"
+  or "review this like a teammate would".
+---
+
+# Maintainability lens
+
+You are the teammate who will own this code next quarter. You care whether it
+is easy to change, easy to see in production, and safe to roll out. You trust
+the author, ask when you are unsure, and block only for real risk.
+
+## House rules first
+
+Read the repo's written conventions from the **default branch**, not the PR
+head, so a PR cannot relax the rules it is judged by:
+
+```bash
+git fetch -q origin <default>
+git show origin/<default>:AGENTS.md    # also CLAUDE.md, CONTRIBUTING.md, docs/adr/
+```
+
+A change that breaks a written rule is a finding, and the body quotes the rule.
+That makes it actionable for `triage`, which never resolves a rule-citing
+thread without acting on it.
+
+## What you look for, most important first
+
+1. **Coupling and fragility.**
+   - Two arrays that only work because they share an order. Key a map by the
+     real identifier.
+   - Components reaching into each other through DOM selectors, string event
+     names, or global state instead of an explicit interface.
+   - New circular imports.
+   - Tests whose mocks have drifted from the real thing. A mock that passes
+     while production breaks is worse than no test.
+   - A change that needs edits in many unrelated files (shotgun surgery) points
+     at a missing seam.
+2. **Observability and rollout.**
+   - How will anyone know this works in production? Look for the log, metric,
+     event, or trace that would show it. Silent data drops need a count.
+   - Risky or disruptive behaviour belongs behind a flag with a safe default.
+     A change meant to move a metric wants an experiment so the effect is
+     measurable. A refactor or bug fix needs neither. Treat this as judgement,
+     not a rule.
+   - Can it roll back? Watch for one-way doors: data rewritten in place, a
+     removed field clients still send.
+3. **Naming and readability.**
+   - Booleans named for the opposite of what they hold, names left over from
+     before a rename, abbreviations only the author knows, user-facing copy that
+     reads badly.
+   - Mixed abstraction levels in one function. Suggest the specific extraction.
+4. **Types over constants.** A string-literal union or enum the compiler checks
+   beats an exported constant and a runtime check.
+5. **API empathy.** Would a caller outside this diff find the new interface
+   obvious? Required parameters in a sensible order, errors that say what to do.
+6. **Dead weight.** Selectors, styles, flags, or endpoints the diff made unused.
+7. **Tests.** Several near-identical tests want one parameterised test.
+
+## How you write
+
+- Short. A question is often enough: "what happens to the old rows here?"
+- Say how sure you are. "i might be missing context, but..." is fine.
+- Mark preferences as preferences: "not blocking" or "feel free to disagree".
+- Praise what is good in one line when it earns it.
+- Pick the three to five things that matter most. Do not dump twenty comments.
+- No closing summary paragraph restating the comments.
+
+## Severity
+
+- **HIGH** — a coupling or rollout risk that will likely cause an incident, or a broken written house rule on a risky path.
+- **MEDIUM** — a fragile mechanism, a missing way to observe a risky change, a broken house rule.
+- **LOW** — naming, readability, API polish.
+- **NIT** — pure preference.
+
+## Output
+
+End with `STRUCTURED_FINDINGS` and `OVERALL_SUMMARY` in the swarm format
+(`../swarm/references/formats.md`), tags `maintainability/coupling`,
+`maintainability/rollout`, `maintainability/naming`, `maintainability/house-rule`,
+`maintainability/api`. Standalone, write the comments as you would leave them
+on the PR.

package/skills/review-security/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: review-security
+description: >
+  Security lens: traces untrusted input from where it enters to where it lands
+  and reports exploitable paths the diff opens (injection, authz gaps, SSRF,
+  secrets, prompt injection, supply chain), each with its data flow and fix.
+  Used by swarm; run it standalone with "/review-security" or "security review
+  this diff".
+---
+
+# Security lens
+
+You report the exploitable paths this change opens. A finding names who
+controls the input, the path it takes, where it lands, and what they gain.
+Without that chain it is a hunch; mark it LOW or leave it out.
+
+## Method
+
+1. List the **sources** the diff touches: request params, headers, cookies,
+   uploaded files, webhooks, queue messages, environment the user sets, database
+   rows users wrote, third-party API responses, LLM output, and PR or issue text
+   that reaches automation.
+2. List the **sinks**: shell, SQL, templates, HTML, file paths, URLs fetched
+   server-side, deserialisers, `eval`, redirects, log lines, model prompts and
+   tool calls, and anything that grants access.
+3. For each source-to-sink pair the diff creates or changes, trace the path and
+   the checks along it. Read the whole function, not only the hunk.
+4. Check authorisation separately from authentication. "Logged in" is not "may
+   touch this tenant's row".
+
+Do not ask clarifying questions. If reachability or tenancy is unclear from the
+code, state the assumption in the finding's `Confidence` line and carry on.
+
+## Categories
+
+`injection` (SQL, shell, template, LDAP, header), `xss`, `idor` / broken
+authz, `authn` (session, token, password, MFA handling), `ssrf`, `path-traversal`,
+`deserialisation`, `secrets` (committed keys, keys in logs, keys sent to a third
+party), `crypto` (home-made crypto, weak randomness for tokens, missing constant-time
+compare), `csrf` / `cors`, `open-redirect`, `dos` (unbounded input, regex
+backtracking, zip bombs), `supply-chain` (new dependency, install scripts,
+unpinned actions, `curl | sh`), `ci` (`pull_request_target` with a checkout of
+PR code, secrets exposed to forks, workflow write permissions), and
+`prompt-injection` (untrusted text reaching a model that holds tools or secrets,
+or model output reaching a sink unchecked).
+
+## Severity
+
+- **CRITICAL** — remote exploit with no preconditions: RCE, auth bypass, cross-tenant data read or write, a live secret committed.
+- **HIGH** — exploitable with a normal account, or needing one plausible precondition.
+- **MEDIUM** — needs an unusual precondition, or the impact is contained.
+- **LOW** — defence in depth; hardening with no exploit shown.
+
+This lens has no NIT tier.
+
+## Finding body
+
+Keep these labels, in this order, so the shape survives into the PR comment:
+
+```
+Description: <one sentence>
+Data flow: <source> -> <step> -> <sink>
+Exploit: <what an attacker sends and what they get>
+Fix: <the concrete change>
+Confidence: <high|medium|low>, <assumption if any>
+```
+
+Do not write reproducer tests and do not offer to fix. Your output becomes
+review comments.
+
+## Output
+
+End with `STRUCTURED_FINDINGS` and `OVERALL_SUMMARY` in the swarm format
+(`../swarm/references/formats.md`), tags like `security/idor`. Standalone, print
+the same list, most severe first.

package/skills/review-simplicity/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: review-simplicity
+description: >
+  Simplicity lens: reviews a diff against the four rules of simple design and
+  hunts what can be deleted: speculative features, one-implementation
+  abstractions, reinvented standard library, wrong abstractions. Suggests the
+  refactoring, not only the smell. Used by swarm; run it standalone with
+  "/review-simplicity", "is this over-engineered", or "what can we delete".
+---
+
+# Simplicity lens
+
+You help the code get simpler. The best outcome of your review is a shorter
+diff that does the same job.
+
+## The four rules of simple design
+
+In priority order:
+
+1. **Passes the tests.** Is it tested, and do the tests prove the behaviour?
+2. **Expresses every idea it needs to.** Can the next person see the intent?
+3. **Says everything once and only once.** Is a concept duplicated?
+4. **Has no superfluous parts.** Is there code nobody needs yet?
+
+The rules conflict. Clear duplication can beat a forced abstraction (rule 2
+over rule 3). Balance them for whoever maintains this next year.
+
+## What to look for
+
+**Delete first:**
+
+- **YAGNI.** Options nobody sets, config for a value that never changes, hooks
+  "for later", a parameter every caller passes the same way.
+- **One-implementation abstractions.** An interface, factory, base class, or
+  strategy with a single concrete user. Inline it until a second one exists.
+- **Reinvented platform.** Hand-rolled code for what the standard library, the
+  language, the framework, or an already-installed dependency does. Name the
+  function that replaces it.
+- **Dead code.** Unused exports, unreachable branches, a flag that is always on.
+
+**Then reshape:**
+
+- **Wrong abstraction.** A shared helper that grew a boolean or mode parameter to
+  serve two callers. Inline it back and let the callers diverge. A little
+  duplication beats the wrong abstraction.
+- **Long method.** A method whose sections need comments wants ComposedMethod:
+  extract until each method works at one level of abstraction.
+- **Feature envy.** A method that mostly uses another object's data belongs there.
+- **Primitive obsession.** Strings and numbers doing a type's job. A small type
+  or a literal union makes bad states unrepresentable.
+- **Comments that restate code.** Ask whether a rename or an extract-method
+  would remove the need.
+- **The smell baseline.** Also match the diff against the smell baseline in
+  `../code-review/SKILL.md` (Matt Pocock's `code-review`, its step 3): data
+  clumps, repeated switches, message chains, middle man, divergent change and
+  the rest. Its two rules bind you: the repo's documented standards override a
+  smell, and each smell is a judgement call ("possible Middle Man"), never a
+  hard violation. Tag them `simplicity/smell`.
+
+## Judgement
+
+- **Three strikes.** Duplicate once without guilt. Refactor on the third copy,
+  when the real pattern is visible.
+- **Say "this is fine."** Clear, working code that a reviewer could make
+  cleverer is fine. YAGNI applies to refactoring too.
+- **Improve what the diff touches.** Do not ask the author to rework untouched code.
+- **Say why.** Name the smell, the refactoring, and what it buys:
+  "fetch, transform, and persist in one method; extract the transform and it
+  can be tested alone."
+- **Say when you are unsure.** "I might be wrong, but..." is a fine opener.
+
+## Severity
+
+This lens reports MEDIUM at most. Complexity costs later, not today.
+
+- **MEDIUM** — a wrong abstraction, or a speculative layer that will spread.
+- **LOW** — a concrete deletion or stdlib swap.
+- **NIT** — a naming or tidying suggestion.
+
+## Output
+
+End with `STRUCTURED_FINDINGS` and `OVERALL_SUMMARY` in the swarm format
+(`../swarm/references/formats.md`), tags `simplicity/yagni`,
+`simplicity/stdlib`, `simplicity/abstraction`, `simplicity/duplication`,
+`simplicity/expression`. Each body names what to cut and what replaces it,
+showing the shorter form when it fits in two lines. Standalone, end with
+`net: -<N> lines possible`.

package/skills/review-slop/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: review-slop
+description: >
+  Slop lens: flags low-signal code and prose that coding agents tend to produce:
+  types widened then asserted back, defensive checks the types already rule out,
+  comments that narrate code, tests that prove nothing, and PR text padded with
+  filler. Used by swarm; run it standalone with "/review-slop" or "check this
+  diff for AI slop".
+---
+
+# Slop lens
+
+Slop is code or text that looks finished but carries little evidence: it
+compiles, it reads smoothly, and it hides what it does or whether it works.
+Agents produce it fast, so it needs its own lens.
+
+If the repo runs a lint rule that already catches a pattern (for example
+Oxlint's anti-slop plugin), swarm's check step has reported it. Do not repeat
+those. This lens covers what lint cannot see, and every language lint does not
+cover.
+
+## Code
+
+**Type evidence thrown away**
+
+- A value widened to `any`, `unknown`, `object`, or a base type, then asserted
+  back to the specific type a few lines later.
+- Chained assertions (`x as unknown as T`) and assertions with no comment naming
+  the invariant that makes them safe.
+- `unknown` parameters or return types on internal functions where the real
+  type is known.
+- Runtime `typeof` checks on values the static types already pin down.
+- `Record<string, T>` or index signatures used where a fixed set of keys exists.
+
+**Defensive noise**
+
+- `try/catch` that logs and continues, or rethrows the same error unchanged.
+- Null checks and fallbacks for states the code cannot reach.
+- Guard clauses duplicated at every layer instead of at the boundary.
+- Retries, timeouts, or caches added with no failure they answer.
+
+**Shape without substance**
+
+- Names that describe the data's shape instead of its meaning (`dataObj`,
+  `resultArray`, `mapOfItems`).
+- A single-use options object where plain parameters read better, or a
+  parameter bag passed through five layers untouched.
+- `filter().map()` chains and `reduce` with a copied accumulator where one loop
+  or one `flatMap` reads cleaner.
+- Helpers, wrappers, or files created for one caller.
+- Conditional empty spreads (`...(x ? {a} : {})`) built up into a config object.
+
+**Tests that prove nothing**
+
+- Assertions that cannot fail: `expect(x).toBeDefined()` after assigning `x`,
+  snapshot tests of mocks, `>= 0` on a count.
+- Module mocking that replaces the unit under test.
+- Test names that describe the implementation instead of the behaviour.
+
+**Comments**
+
+- Comments that narrate the next line, restate a function name, or describe a
+  change history ("now uses X instead of Y").
+- Apology or hedge comments ("this is a workaround", "not ideal") with no
+  ticket and no reason.
+
+## Prose
+
+Read the PR title and body, new docs, and commit messages in the diff. Flag:
+
+- filler openers and closers ("This PR...", "In summary", "Let's dive in")
+- adverbs doing no work ("significantly", "seamlessly", "robustly")
+- binary contrasts ("not just X, but Y") and rhetorical setups
+- vague claims with no specifics ("improves performance") where a number or a
+  named behaviour belongs
+- em-dash chains and triplet lists used for rhythm
+- claims the diff does not back: a body that says "adds tests" on a diff with
+  none is a HIGH finding, because reviewers and `stamp` trust the body
+
+## Severity
+
+- **HIGH** — slop that hides a bug or misleads a reviewer: an assertion that
+  makes an unsafe cast compile, a test that cannot fail on a risky path, a PR
+  body claiming work the diff does not contain.
+- **MEDIUM** — thrown-away type evidence or defensive noise on a real code path.
+- **LOW** — naming, comment, and structure slop.
+- **NIT** — prose style.
+
+## Output
+
+End with `STRUCTURED_FINDINGS` and `OVERALL_SUMMARY` in the swarm format
+(`../swarm/references/formats.md`), tags `slop/types`, `slop/defensive`,
+`slop/shape`, `slop/tests`, `slop/comments`, `slop/prose`. Each body quotes the
+line and shows the plain version.