@su-record/vibe 4.1.13 → 4.1.15

package/skills/antislop-code/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: antislop-code
+description: A code skill that strips generic-AI engineering patterns and writes, diagnoses, revises and converts code that other people will read or maintain — a library, a contribution, a handoff, a code review — in any programming language. Use it before writing code for a new module or feature, when judging or fixing an existing codebase, and whenever a change needs to fit the repository's own conventions instead of a generic default.
+metadata:
+  tags: [code, review, editing]
+  category: content
+---
+
+# Code Writing Skill (antislop-code)
+
+`antislop-code` is a **general-purpose code skill**. It does not impose one
+style or one language. It chooses names, structure and abstraction that fit
+the repository at hand — the same way `antislop-design` chooses layout and
+type that fit the brief rather than one house look.
+
+## When to Use
+
+- Writing a new module, function or feature that another person will read, run or maintain later.
+- Reviewing a pull request, a contribution, or a handoff before it ships.
+- Diagnosing an existing file or directory without changing it.
+- Revising only what needs to change while preserving behaviour and tests.
+- Converting a generated draft, a template, or a scaffold into the codebase's own conventions.
+
+Do not apply it to a throwaway script run once and discarded, a one-off
+data-cleaning pass with no second reader, or bindings generated by a tool
+from a schema or an IDL — those are not read or maintained the way a library
+or a contribution is. Apply it to code in any language: the catalogue below
+is about shape, not syntax.
+
+Treat "write" or "implement" as authoring, "review" or "look this over" as
+diagnosis, "fix" or "clean up" as revision, and "port this" or "make this
+fit our style" as conversion. Do not attach a findings table the caller did
+not ask for; lead with the finished code.
+
+## Quality Priority
+
+Judge in the following order. Do not damage an earlier condition to gain a
+later advantage.
+
+1. **Behaviour and tests**: the code does what it must, and the tests that prove it still pass.
+2. **Fit with the codebase**: the change reads as if the same person who wrote the surrounding code wrote this too — same naming, same error handling, same structure.
+3. **Clarity**: a maintainer who has never seen this file can follow it without asking the author.
+4. **Brevity**: nothing exists that the first three conditions do not require.
+
+## What Code Slop Is
+
+Code slop is a structural or naming choice that could be dropped into any
+codebase, in any language, unchanged, and would still "look like good
+code." It is the engineering equivalent of a sentence that fits any topic.
+The test is not whether a pattern appears — an interface, a try/except, a
+comment can all be correct — but whether the choice was earned by this
+code's actual shape or is the generic default a model reaches for when
+nobody decided otherwise.
+
+- **A comment that restates the line.** `// increment the counter` above `counter += 1`. The comment adds nothing the code did not already say.
+- **A docstring on a getter.** `"""Gets the name."""` above `def get_name(self): return self._name`. The name of the method already is the docstring.
+- **A guard for an impossible state.** A null check, a type check or an `assert` on a value the caller can never actually pass, defending against a state the type system or the call graph already rules out.
+- **A try/except or try/catch that swallows.** `except: pass` or `catch (e) {}` — the failure disappears instead of propagating or being handled.
+- **An interface or abstract class with one implementation.** A `Repository` interface with exactly one `SqlRepository` behind it, built for a substitution that will never happen.
+- **A factory for one class.** `createWidget()` that only ever returns a `Widget`, adding a layer of indirection with no second product to switch between.
+- **Names like `Manager`, `Helper`, `Utils`, `Handler`, `Service` with nothing behind them.** A class named for a role instead of what it actually holds or does, often a grab-bag of unrelated methods.
+- **A wrapper that only forwards.** A function whose entire body calls another function with the same arguments and returns its result, adding a name but no behaviour.
+- **A constant made configurable that never varies.** A value read from an environment variable, a config file or a settings object that has exactly one value in every environment that exists.
+- **Dead code kept "just in case," or commented out.** A branch nothing reaches, an unused parameter, a block of commented-out code sitting next to the code that replaced it.
+- **"Robust," "enhanced," "improved," "comprehensive" in a name, a comment or a commit message.** A quality claim standing in for a specific change; the word describes nothing a reader can check.
+- **A TODO or FIXME that ships.** A marker for work that was never done, left in the code that goes out anyway.
+- **Logging every step.** A `print` or `log.info` call after every line, drowning the one log line that would matter in noise.
+- **A generic error message.** `raise Exception("Something went wrong")` or `throw new Error("failed")` — no failing operation named, no next step suggested.
+- **Type or annotation noise that repeats the obvious.** `count: int  # an integer` or a return-type annotation restating what the function's own name already says.
+- **Re-exports and barrels nobody imports.** An `index.ts` or `__init__.py` re-exporting everything in a directory when nothing outside it imports through that path.
+- **A test that asserts the implementation instead of behaviour.** A mock call count, a check that a private method ran, in place of a check on the return value or the observable state.
+- **A commit message that praises itself.** "Successfully implemented the feature" or "now works perfectly" — a self-assessment where a commit message names what changed.
+
+### How to see these in source
+
+Most of these markers have a concrete textual signature: a bare
+`except:`/`catch (e) {}` with an empty body, a class name ending in
+`Manager`/`Helper`/`Utils`/`Handler`/`Service`, an `interface` or abstract
+base class with exactly one class implementing or extending it, a `# TODO`
+or `// TODO` comment, a comment line whose words are the same words as the
+code line beneath it, a `raise`/`throw` with a generic string literal, a
+config or environment lookup for a key whose value never changes across the
+codebase's own config files, and a commit message containing "successfully"
+or "robust." The full table of markers, a grep-able pattern for each, and
+the fix, is in
+[references/catalogue.md](references/catalogue.md).
+
+## The Decisions a Specific Change Makes First
+
+Before writing or changing code, settle the following. These outrank the
+catalogue whenever they conflict with it.
+
+1. **The repository's own conventions outrank the pack.** A sample of how this codebase already names things, handles errors and structures modules outranks any rule in this skill. Read two or three neighbouring files before writing one more.
+2. **The smallest change that passes the check.** Do not restructure a file to fix one line; do not introduce a pattern the rest of the codebase does not use.
+3. **Delete before add.** If a change can be made by removing code, remove it before reaching for a new abstraction, a new flag or a new file.
+4. **A name says what, a comment says why, or nothing.** A comment that would still be true if the code beneath it changed is not doing its job; a comment that repeats the code is not doing its job either.
+5. **An abstraction is earned by a second caller.** Do not generalise, interface, or configure something for a future need that has no present caller.
+6. **A guard is earned by a reachable state.** Check for a condition only when something in the code's actual inputs or call sites can produce it.
+7. **An error message names what failed and what to do.** "Config file not found at <path>; run `init` first" beats "Something went wrong."
+8. **A test tests behaviour.** It asserts on inputs and outputs or observable state, not on how many times an internal method was called.
+
+## The Four Tasks
+
+### Write
+
+1. Read two or three files near where the change lands: naming, error handling, module shape, test style.
+2. Write the smallest version that satisfies the requirement and the existing conventions, real inputs and real error paths, no placeholder data.
+3. Run the checklist in [Verification](#verification) before calling it done.
+
+### Diagnose
+
+Do not change the source. Produce a findings table and nothing else:
+
+- What to preserve (behaviour that works, tests that pass, conventions already followed correctly).
+- Findings: `file:line | marker | effect on the maintainer | one-line fix`.
+- What a human must decide.
+- Overall verdict.
+
+Do not flag a marker you cannot pin to a location and a maintenance effect;
+do not flag a single weak marker alone (see [Strength Tiers](#strength-tiers)).
+
+### Revise
+
+Hold a preservation contract. Do not add, remove or alter the following
+while fixing what was flagged:
+
+- **Behaviour**: what the code does for every input it already handles.
+- **Public API and signatures**: function names, parameters, return shapes and exported symbols that other code calls.
+- **Tests**: an existing passing test keeps passing; do not weaken an assertion to make a change fit.
+- **Error messages**: a message another system or a log parser depends on, unless the brief asks for a specific message change.
+- **Performance characteristics**: an complexity or resource bound the code was written to hold.
+- **Anything the brief marks as kept.**
+
+Be able to state the problem each change solves. Do not swap one name or one
+structure for another only to look different. Stop at `needs-human` when the
+brief or the codebase's own convention is too unclear to safely settle a
+change.
+
+### Convert
+
+Take a generated draft, a scaffold, or a template and rebuild its names,
+structure and error handling around the target codebase's own conventions,
+keeping the behaviour and the public surface the draft already has. This is
+not a rewrite for style alone: only change what would mark the file as
+having come from somewhere else.
+
+## Strength Tiers
+
+- **Strong markers act alone.** One instance is enough to flag: a swallowing catch, an interface or abstract class with exactly one implementation, dead or commented-out code, a shipped TODO, invented "robust"/"enhanced" naming.
+- **Weak markers act only when two or more overlap in the same function or file.** A short comment alone is not slop; a single defensive check alone is not slop; one `Helper`-named class alone is not slop. Two or three of these together, doing no other work, are.
+
+Do not run the catalogue as a checklist of banned constructs. A try/except,
+an interface and a comment are ordinary tools; the question is always
+whether this use, in this code, was decided or defaulted to.
+
+## Five Questions Before a Cut
+
+Before removing anything flagged, check all five:
+
+1. Does behaviour change if this is removed?
+2. Is it the author's deliberate choice, or something a template or a generator left behind?
+3. Does it explain something the code does not already say, or does it restate the code?
+4. Does it guard a state the code's actual inputs or callers can reach?
+5. Would the maintainer trust this file more with it gone?
+
+## Verification
+
+- Do the existing tests still pass, and does a new test cover the behaviour that changed?
+- Does the change read as if it were written by whoever wrote the surrounding file?
+- Would a maintainer who has never seen this file understand it without asking the author?
+- Is every abstraction, interface and factory backed by a second real caller?
+- Is every guard defending a state the code can actually reach?
+- Does every error message name what failed and what to do next?
+- Is anything present that behaviour, fit or clarity did not require?
+- Are any strong markers present — a swallowing catch, a one-implementation interface, dead code, a shipped TODO, invented "robust" naming? One is enough to flag.
+- Do two or more weak markers overlap in the same function or file — a short comment, a single guard, one generically named class, together?
+- For a revision: does the preservation contract hold — same behaviour, same public API, same passing tests, same error messages, same performance characteristics?
+
+## Editorial Review
+
+Do not close out a change meant for another maintainer — a library release,
+a contribution, a handoff — on the writer's own judgment alone. Bind a
+`review` check to the change in a scenario:
+
+```yaml
+- id: roster-review
+  then: the roster module passes the reviewer and the maintainer
+  check: { type: review, pack: code, path: src/roster.py, contract: docs/roster-brief.md }
+```
+
+- `path` is the file or directory under review; `contract` is the brief describing what the change is for, who maintains it, and any stated conventions.
+- The harness runs `reviewers/code/1-reviewer.md` first, and only on a pass runs `reviewers/code/2-maintainer.md`. A stage passes only when the entire response is exactly one line, `PASS`.
+- The scope skill proposes this check only when the code will be read or maintained by someone else — a library, a contribution, a handoff. For code nobody else reads or runs again, `vibe size` is the code gate instead.
+- If the same failure repeats twice, stop at `needs-human` rather than guessing at a fix the reviewer did not ask for.
+
+This mirrors the two-stage independent review in `antislop-design`'s
+[Editorial Review](../antislop-design/SKILL.md#editorial-review) — a
+different reader judges, the writer does not self-certify, and a reviewer
+returns only `PASS` or a `REJECT` list, never a rewrite.
+
+## Pitfalls
+
+- Do not strip the repository's own conventions to match this pack. When the two disagree, the sample outranks the rules.
+- Do not remove a comment that explains why a choice was made, even a short one; only remove a comment that restates what the code already says.
+- Do not delete a guard whose state is actually reachable, even if it looks defensive; check the call sites before cutting.
+- Do not rewrite a test to make it pass instead of fixing the code, and do not weaken an assertion to quiet a failure.

package/skills/antislop-code/references/catalogue.md

@@ -0,0 +1,28 @@
+# Code Slop Catalogue
+
+One row per marker. "Strength" follows the skill's tiers: a strong marker is
+enough on its own; a weak marker only counts when two or more overlap in the
+same function or file. Do not run this as a list of banned constructs — each
+alternative names what to decide instead, not a substitute default. Patterns
+are illustrative greps across common languages, not exhaustive regexes.
+
+| Marker | What it looks like | A pattern a reviewer can grep | Strength | Fix |
+|---|---|---|---|---|
+| Comment restates the line | A comment whose words are the same words as the code beneath it | A `#`/`//` comment line immediately followed by a line whose identifiers and verb match it, e.g. `# increment the counter` above `counter += 1` | Weak | Delete the comment; if it explains why, keep only the why. |
+| Docstring on a getter | A method docstring that says only what the method's name already says | `def get_\w+\(self\):\s*\n\s*"""Gets` or `"""Returns the \w+\."""` above a one-line return | Weak | Delete the docstring, or replace it with the one fact the name does not carry (units, a side effect, a caveat). |
+| Guard for an impossible state | A null/type check or `assert` on a value the call graph never actually produces | `if \w+ is None:\s*raise` or `assert \w+ is not None` with no caller that can pass `None` | Weak | Remove the guard, or replace it with a real invariant the type system does not already enforce. |
+| Try/except or try/catch that swallows | A failure disappears instead of propagating or being handled | `except:\s*pass`, `except Exception:\s*pass`, `catch\s*\(\w*\)\s*\{\s*\}` | Strong | Let the exception propagate, or handle it with a specific catch and a real recovery or log line naming the failure. |
+| Interface or abstract class with one implementation | A substitution point built for a swap that never happens | `interface \w+` with exactly one `implements` of it in the codebase, or `class \w+\(ABC\)` with exactly one concrete subclass | Strong | Delete the interface and call the one implementation directly; reintroduce it when a second implementation actually exists. |
+| Factory for one class | A creation function that only ever returns one type | `def create_\w+\(` or `class \w+Factory\b` returning a single concrete type with no branching | Weak | Replace the factory call with the constructor directly. |
+| Manager/Helper/Utils/Handler/Service names with nothing behind them | A class named for a role, holding an unrelated grab-bag of methods | `class \w+(Manager\|Helper\|Utils\|Handler\|Service)\b` | Weak | Name the class for what it actually holds or does; split unrelated methods into their own homes. |
+| Wrapper that only forwards | A function whose body only calls another function with the same arguments | `def \w+\(([^)]*)\):\s*\n\s*return \w+\(\1\)` or `return await inner\(` with identical arguments | Weak | Call the wrapped function directly at each call site; delete the wrapper. |
+| Constant made configurable that never varies | A config or environment lookup for a key with exactly one value everywhere it is set | `config\.get\("[A-Z_]+"` or `os\.environ\.get\("[A-Z_]+"` whose key has one value across every config file in the repo | Weak | Replace it with a plain named constant in code. |
+| Dead code, kept "just in case" or commented out | A branch nothing reaches, or old code left next to its replacement | A block of `#`/`//` commented-out statements, or a function/branch with no caller found by search | Strong | Delete it; version control already has the history. |
+| "Robust"/"enhanced"/"improved"/"comprehensive" naming | A quality claim in place of a specific description | `\b(robust\|enhanced\|improved\|comprehensive)\b` in an identifier, a comment, or a commit message | Strong | Name the specific behaviour or fix instead of the adjective. |
+| TODO/FIXME that ships | A marker for work that was never done, left in shipped code | `#\s*TODO`, `//\s*TODO`, `FIXME` with no linked issue | Strong | Do the work, file a tracked issue and reference it, or delete the marker. |
+| Logging every step | A log or print call after nearly every line, burying the line that matters | Multiple `print\(` or `log(ger)?\.(info\|debug)\(` calls per function body, one per statement | Weak | Keep only the log line that marks a real state change or failure. |
+| Generic error message | An error with no failing operation named and no next step | `raise Exception\("Something went wrong"\)`, `throw new Error\("failed"\)` | Strong | Name what failed and what to do: the operation, the input, and the fix. |
+| Type/annotation noise repeating the obvious | An annotation or trailing comment that restates the type or the name | `\w+: int\s*#\s*(an? )?int(eger)?\b` or a return type annotation matching the function's own name with no added information | Weak | Delete the noise; keep only an annotation that adds information a reader could not infer. |
+| Re-exports and barrels nobody imports | An index file re-exporting a directory that nothing imports through it | `export \* from` in `index.ts`, or `__all__ = \[.*\]` in `__init__.py`, with no import found elsewhere using that path | Weak | Delete the barrel; import from the concrete module directly. |
+| Test asserts the implementation, not behaviour | A test checks that an internal method ran, not what the code produced | `assert_called_with\(`, `toHaveBeenCalledTimes\(`, `\.mock\.calls\.length` with no assertion on a return value or observable state in the same test | Strong | Rewrite the assertion against the function's return value or the system's observable state. |
+| Commit message that praises itself | A self-assessment in place of a description of the change | `[Ss]uccessfully (implemented\|added\|fixed)`, `now works perfectly`, `fully functional` in a commit message | Strong | State what changed and why, not how well it turned out. |

package/skills/vibe-scope/SKILL.md

@@ -9,9 +9,11 @@ user-invocable: false
 ## Procedure
 
 1. Turn the discovery result into scenarios. A scenario is stored only if it carries exactly one check type:
-   - `run` command exit code · `file` exists/regex/contains/absent (a regex that must match nowhere)/schema/sum (a column total equals a reference) · `http` status/schema/maxMs · `eval` count of matching labelled cases (jsonl `{input, expected}` through a runner's stdin/stdout, `expect.pass` is a count) · `review` an antislop pack's reviewer stages in order (text: copy editor → chief editor; design: markup reviewer → art director), run by the harness, exact `PASS` only · `human` no verdict (goes to the inbox)
+   - `run` command exit code · `file` exists/regex/contains/absent (a regex that must match nowhere)/traceable (every number is in an evidence file)/a11y (mechanical accessibility defects)/schema/sum (a column total equals a reference) · `http` status/schema/maxMs · `eval` count of matching labelled cases (jsonl `{input, expected}` through a runner's stdin/stdout, `expect.pass` is a count) · `review` an antislop pack's reviewer stages in order (text: copy editor → chief editor; design: markup reviewer → art director; code: reviewer → maintainer), run by the harness, exact `PASS` only · `human` no verdict (goes to the inbox)
    - When a success condition is human-read text (blog, column, article, report, script, speech), propose `check: { type: review, path: <file>, contract: <file>, evidence: <file> }` and mark it `⚠ model-judged` in the approval message.
    - When it is something a person looks at (screen, page, component, dashboard, slide, card news, poster), propose `check: { type: review, pack: design, path: <file or directory>, contract: <brief>, screenshot: <png, if an earlier scenario renders one> }`, same mark.
+   - When the code will be read or maintained by someone else (a library, a contribution, a handoff), propose `check: { type: review, pack: code, path: <file or directory>, contract: <brief> }`, same mark; otherwise `vibe size` stays the code gate.
+   - Next to a text `review` that has an evidence file, propose `check: { type: file, path: <file>, traceable: <evidence file> }` (every number in the text is in the evidence); next to a design `review` on html, `check: { type: file, path: <html>, a11y: true }` (alt, heading order, unnamed controls, unlabelled inputs, contrast). These check facts; the reviewers keep the judgment.
    - Next to every `review`, propose its deterministic pre-gate on the same file: `check: { type: file, path: <file>, absent: "@placeholders" }` — the preset is the usual leftovers (lorem-ipsum text, a bracketed TODO, a to-be-decided mark, a company-name placeholder, unfilled double-brace fields, double-square-bracket notes); add the project's own words with `|`. For a directory, a `run` check with `grep -rlE` and `expect: 1`. Tell the writer that a note to the model goes between double square brackets, so the gate catches it if it survives into the artifact.
    - A condition you cannot check gets `human` explicitly. An irreversible action (push, deploy, send, delete, spend) gets `irreversible: <action>`.
    - A scenario that only makes sense after another one has passed gets `needs: [ids]`. The harness orders and parallelises checks from these edges; keep a connected graph under six scenarios.