diff --git a/.agents/CODEX-SKILL-COMPATIBILITY.md b/.agents/CODEX-SKILL-COMPATIBILITY.md index 29cafcc..5a0e27d 100644 --- a/.agents/CODEX-SKILL-COMPATIBILITY.md +++ b/.agents/CODEX-SKILL-COMPATIBILITY.md @@ -10,9 +10,9 @@ | Status | Skills | |---|---| -| Native | `brainstorming`, `caveman`, `enhance-prompt`, `forge-repo-ui-skill`, `handoff-audit`, `humanizer`, `plain-words`, `recall`, `writing-plans` | -| Adapted | `addskill`, `fable-mode`, `init-project`, `lab`, `optimize-context`, `sync-starter`, `writing-skills` | -| Capability-gated | `advocate`, `design-study`, `impartial-review`, `why` | +| Native | `babysit-ci`, `brainstorming`, `bro`, `caveman`, `enhance-prompt`, `forge-repo-ui-skill`, `handoff-audit`, `humanizer`, `plain-words`, `recall`, `unslop`, `verify-this`, `writing-plans` | +| Adapted | `addskill`, `automate-me`, `fable-mode`, `init-project`, `lab`, `optimize-context`, `sync-starter`, `writing-skills` | +| Capability-gated | `advocate`, `arena`, `design-study`, `impartial-review`, `why` | | Dangerous | `clarity-pass`, `create-guide`, `crosslink`, `ingest`, `merge` | | Claude-only | None in the starter source set. | diff --git a/.agents/skills/arena/SKILL.md b/.agents/skills/arena/SKILL.md new file mode 100644 index 0000000..234c666 --- /dev/null +++ b/.agents/skills/arena/SKILL.md @@ -0,0 +1,18 @@ +--- +name: "arena" +description: "Spawn N parallel candidate attempts at one task, pick the strongest as base, graft the losers' best parts in. Use when the user says $arena, \"arena this\", or when one attempt at a non-trivial artifact would lock in the wrong shape." +--- + + + +# Codex Adapter + +Read `../../../.claude/skills/arena/SKILL.md` completely and follow it as the canonical workflow for this skill. + +- Resolve every relative script, reference, asset, and template path from the canonical skill directory under `.claude/skills/arena/`. +- Read `../../../.agents/CODEX-SKILL-COMPATIBILITY.md` and apply the status and exceptions for this skill. +- Translate Claude Code tool names to the available Codex equivalent as described by the repository `AGENTS.md`. +- Before any Claude `Task`, `Agent`, or `Workflow` step, confirm that the current Codex session exposes the required multi-agent tools. Do not replace independent review with self-review. +- Skill invocation alone does not authorize commit, push, PR, merge, deploy, migration, dependency installation, or another outward action unless that action is the user's explicit request. +- Follow Codex system, developer, sandbox, approval, and tool instructions when they differ from the canonical workflow. +- Keep the canonical Claude skill unchanged unless the user explicitly asks to edit the workflow itself. diff --git a/.agents/skills/automate-me/SKILL.md b/.agents/skills/automate-me/SKILL.md new file mode 100644 index 0000000..f27ea15 --- /dev/null +++ b/.agents/skills/automate-me/SKILL.md @@ -0,0 +1,18 @@ +--- +name: "automate-me" +description: "Use for \"automate me\", \"$automate-me\", \"create/update my -mode skill\", or \"turn my preferences / working style into a skill\". Mines the current project's transcripts plus direct questions, then drafts a personal -mode skill." +--- + + + +# Codex Adapter + +Read `../../../.claude/skills/automate-me/SKILL.md` completely and follow it as the canonical workflow for this skill. + +- Resolve every relative script, reference, asset, and template path from the canonical skill directory under `.claude/skills/automate-me/`. +- Read `../../../.agents/CODEX-SKILL-COMPATIBILITY.md` and apply the status and exceptions for this skill. +- Translate Claude Code tool names to the available Codex equivalent as described by the repository `AGENTS.md`. +- Before any Claude `Task`, `Agent`, or `Workflow` step, confirm that the current Codex session exposes the required multi-agent tools. Do not replace independent review with self-review. +- Skill invocation alone does not authorize commit, push, PR, merge, deploy, migration, dependency installation, or another outward action unless that action is the user's explicit request. +- Follow Codex system, developer, sandbox, approval, and tool instructions when they differ from the canonical workflow. +- Keep the canonical Claude skill unchanged unless the user explicitly asks to edit the workflow itself. diff --git a/.agents/skills/babysit-ci/SKILL.md b/.agents/skills/babysit-ci/SKILL.md new file mode 100644 index 0000000..fd4504b --- /dev/null +++ b/.agents/skills/babysit-ci/SKILL.md @@ -0,0 +1,18 @@ +--- +name: "babysit-ci" +description: "Watch a PR's checks and iterate on failures until green. Use for $babysit-ci, \"watch CI\", \"fix CI\", \"get the checks green\", or when a PR is waiting on failing or pending checks." +--- + + + +# Codex Adapter + +Read `../../../.claude/skills/babysit-ci/SKILL.md` completely and follow it as the canonical workflow for this skill. + +- Resolve every relative script, reference, asset, and template path from the canonical skill directory under `.claude/skills/babysit-ci/`. +- Read `../../../.agents/CODEX-SKILL-COMPATIBILITY.md` and apply the status and exceptions for this skill. +- Translate Claude Code tool names to the available Codex equivalent as described by the repository `AGENTS.md`. +- Before any Claude `Task`, `Agent`, or `Workflow` step, confirm that the current Codex session exposes the required multi-agent tools. Do not replace independent review with self-review. +- Skill invocation alone does not authorize commit, push, PR, merge, deploy, migration, dependency installation, or another outward action unless that action is the user's explicit request. +- Follow Codex system, developer, sandbox, approval, and tool instructions when they differ from the canonical workflow. +- Keep the canonical Claude skill unchanged unless the user explicitly asks to edit the workflow itself. diff --git a/.agents/skills/bro/SKILL.md b/.agents/skills/bro/SKILL.md new file mode 100644 index 0000000..a1ced12 --- /dev/null +++ b/.agents/skills/bro/SKILL.md @@ -0,0 +1,18 @@ +--- +name: "bro" +description: "Restate the assistant's last message in plain human language, no jargon. Use when the user says $bro, \"in plain english\", \"dumb it down\", or \"what does that actually mean\"." +--- + + + +# Codex Adapter + +Read `../../../.claude/skills/bro/SKILL.md` completely and follow it as the canonical workflow for this skill. + +- Resolve every relative script, reference, asset, and template path from the canonical skill directory under `.claude/skills/bro/`. +- Read `../../../.agents/CODEX-SKILL-COMPATIBILITY.md` and apply the status and exceptions for this skill. +- Translate Claude Code tool names to the available Codex equivalent as described by the repository `AGENTS.md`. +- Before any Claude `Task`, `Agent`, or `Workflow` step, confirm that the current Codex session exposes the required multi-agent tools. Do not replace independent review with self-review. +- Skill invocation alone does not authorize commit, push, PR, merge, deploy, migration, dependency installation, or another outward action unless that action is the user's explicit request. +- Follow Codex system, developer, sandbox, approval, and tool instructions when they differ from the canonical workflow. +- Keep the canonical Claude skill unchanged unless the user explicitly asks to edit the workflow itself. diff --git a/.agents/skills/unslop/SKILL.md b/.agents/skills/unslop/SKILL.md new file mode 100644 index 0000000..2bf1ba5 --- /dev/null +++ b/.agents/skills/unslop/SKILL.md @@ -0,0 +1,18 @@ +--- +name: "unslop" +description: "Always-on AI-tell stripper: apply its pattern check to everything written for humans (chat prose, commits, PR bodies, docs, UI text). Also use when the user says $unslop, \"unslop this\", or points at text or a file to clean." +--- + + + +# Codex Adapter + +Read `../../../.claude/skills/unslop/SKILL.md` completely and follow it as the canonical workflow for this skill. + +- Resolve every relative script, reference, asset, and template path from the canonical skill directory under `.claude/skills/unslop/`. +- Read `../../../.agents/CODEX-SKILL-COMPATIBILITY.md` and apply the status and exceptions for this skill. +- Translate Claude Code tool names to the available Codex equivalent as described by the repository `AGENTS.md`. +- Before any Claude `Task`, `Agent`, or `Workflow` step, confirm that the current Codex session exposes the required multi-agent tools. Do not replace independent review with self-review. +- Skill invocation alone does not authorize commit, push, PR, merge, deploy, migration, dependency installation, or another outward action unless that action is the user's explicit request. +- Follow Codex system, developer, sandbox, approval, and tool instructions when they differ from the canonical workflow. +- Keep the canonical Claude skill unchanged unless the user explicitly asks to edit the workflow itself. diff --git a/.agents/skills/verify-this/SKILL.md b/.agents/skills/verify-this/SKILL.md new file mode 100644 index 0000000..6b89625 --- /dev/null +++ b/.agents/skills/verify-this/SKILL.md @@ -0,0 +1,18 @@ +--- +name: "verify-this" +description: "Verify a claim with fresh local evidence: restate it falsifiably, capture baseline and treatment, compare, return VERIFIED, NOT VERIFIED, or INCONCLUSIVE. Use for $verify-this, \"prove it works\", \"did this fix it\", \"show me the evidence\"." +--- + + + +# Codex Adapter + +Read `../../../.claude/skills/verify-this/SKILL.md` completely and follow it as the canonical workflow for this skill. + +- Resolve every relative script, reference, asset, and template path from the canonical skill directory under `.claude/skills/verify-this/`. +- Read `../../../.agents/CODEX-SKILL-COMPATIBILITY.md` and apply the status and exceptions for this skill. +- Translate Claude Code tool names to the available Codex equivalent as described by the repository `AGENTS.md`. +- Before any Claude `Task`, `Agent`, or `Workflow` step, confirm that the current Codex session exposes the required multi-agent tools. Do not replace independent review with self-review. +- Skill invocation alone does not authorize commit, push, PR, merge, deploy, migration, dependency installation, or another outward action unless that action is the user's explicit request. +- Follow Codex system, developer, sandbox, approval, and tool instructions when they differ from the canonical workflow. +- Keep the canonical Claude skill unchanged unless the user explicitly asks to edit the workflow itself. diff --git a/.claude/skills/arena/SKILL.md b/.claude/skills/arena/SKILL.md new file mode 100644 index 0000000..5615f7c --- /dev/null +++ b/.claude/skills/arena/SKILL.md @@ -0,0 +1,82 @@ +--- +name: arena +description: "Spawn N parallel candidate attempts at one task, pick the strongest as base, graft the losers' best parts in. Use when the user says /arena, \"arena this\", or when one attempt at a non-trivial artifact would lock in the wrong shape." +--- + +# Arena + +Fan out N parallel attempts at the same task. Read every candidate end to end. Pick the strongest as the base. Graft the best ideas from the others into it. Verify the synthesized result. + +Not the same as wow-loop (one implementer iterated under adversarial critique) or impartial-review (review of an existing diff). Arena is a bakeoff plus synthesis: use it when the *shape* of the solution is the open question. + +## Start + +Open a todo list with one entry per phase before launching anything. The arena runs autonomously and the list keeps phases from silently disappearing. + +1. Frame +2. Fan out +3. Cross-judge +4. Pick +5. Graft +6. Verify + +## Phase A: Frame + +The N candidates receive the same prompt, so the prompt is the contract. Get it right before spawning anything. + +1. State the artifact each candidate is producing. +2. Derive the rubric. State what success looks like for *this* task, then turn it into 3-6 concrete gradeable criteria. Concrete: "Adds a --dry-run flag that skips writes". Vague: "code is correct". The rubric is the picker's tool in Phase D; candidates only see the task. +3. Pick the runners. Default: 3 subagents on the session model (never Haiku), each prompted from a distinct angle (e.g. simplest-thing-that-works, robustness-first, user-experience-first) so diversity comes from framing, not chance. When the Codex CLI is available and the task warrants cross-vendor diversity, one candidate may run there (see codex-review for driving it). Spawn more candidates when the arena covers multiple design directions. +4. Assign output paths. Each candidate writes to its own location: a git worktree where possible (worktree isolation when spawning), otherwise `.tmp/arena-/candidate-/`. N candidates writing to the same path is shared mutable state and corrupts the comparison. + +## Phase B: Fan out + +Spawn all N subagents in one message so they run concurrently, each with the task, the path to any shared grounding, its own output path, and instructions to produce both the artifact and a short rationale. + +The rationale is mandatory. Without it, the parent cannot tell whether a candidate's structure is principled or accidental, which makes Phase E grafting unreliable. Each rationale names the alternatives the candidate considered and what it rejected. + +If a candidate fails to produce output, proceed with N-1 and note the dropout in the synthesis record. + +## Phase C: Cross-judge + +After all Phase B candidates complete, spawn one fresh read-only judge subagent. Prefer a different vendor from the candidates (Codex CLI) when available; otherwise a fresh same-model subagent still removes the parent's authorship bias. The judge sees the rubric and the candidates by path label only — never which angle or vendor produced which — scores each criterion, and recommends a base with rationale. It runs in parallel with the parent's own reading in Phase D, not with the candidates themselves: spawning while candidates are still writing means the judge sees partial outputs and reports them as dropouts. + +## Phase D: Pick a base + +Read every candidate end to end before picking. Skimming N candidates surfaces only the candidate whose surface looks most familiar. + +Score each candidate against the rubric criterion by criterion, not on holistic feel. Compare against the cross-judge. Agreement on the base confirms the pick. Disagreement means one of you is biased or the rubric was ambiguous; read both rationales before deciding. + +Pick the base on which candidate a future maintainer can extend most easily without breaking invariants. Prefer the cleaner boundary or smaller surface area when two feel tied. + +Record the pick and the reason in a short synthesis note alongside the base artifact, including the cross-judge's verdict. + +## Phase E: Graft + +Walk each losing candidate once more and identify what is worth porting into the base. The signal is usually one or two things per candidate, not most of it. + +Fold each graft in by hand, redesigning it to fit the base's shape. Don't paste mechanically. The result has to remain coherent under one mental model. + +Record what was grafted, from which candidate, and what was rejected and why. The rejection notes are the highest-signal part of the record: future readers learn from what you considered and dropped, not just what you kept. + +When N candidates converge on the same shape, that is a strong agreement signal. Note the convergence in the record and ship the consensus shape; no graft needed. When N candidates wildly diverge, Phase A was under-specified. Reframe and re-run rather than averaging the divergence. + +## Phase F: Verify + +The synthesized artifact has to hold up under the same scrutiny as any other output. The arena does not earn a verification pass: run the real check the artifact claims to satisfy. + +If verification surfaces a problem the arena did not catch, either Phase A was wrong (re-frame and re-run) or one candidate caught it and you missed the graft (go back to Phase E). Don't paper over. + +## Outputs + +One synthesized artifact. One short synthesis note alongside, naming the base, the grafts (with source candidate), the rejections, the dropouts if any, and the verification result. Scratch candidate outputs stay in `.tmp/` or their worktrees; only the synthesis ships. + +## Anti-patterns + +- Don't average divergent candidates into a hybrid nobody designed. Reframe and re-run. +- Don't let the judge see angle or vendor labels; sanitized path labels only. +- Don't skip reading a candidate because the judge scored it low; grafts hide in losers. +- Don't run an arena on trivial work; one attempt suffices when the shape is obvious. + +--- +Adapted from the `arena` skill in [cursor/plugins pstack](https://github.com/cursor/plugins/tree/main/pstack) (MIT, by poteto). diff --git a/.claude/skills/automate-me/SKILL.md b/.claude/skills/automate-me/SKILL.md new file mode 100644 index 0000000..9c1ffaf --- /dev/null +++ b/.claude/skills/automate-me/SKILL.md @@ -0,0 +1,101 @@ +--- +name: automate-me +description: "Use for \"automate me\", \"/automate-me\", \"create/update my -mode skill\", or \"turn my preferences / working style into a skill\". Mines the current project's transcripts plus direct questions, then drafts a personal -mode skill." +--- + +# Automate me + +A guided flow for turning the user's working conventions into a skill agents will follow. The output is one `-mode` skill tailored to them (e.g. `ryan-mode`). + +This skill orchestrates others: an inline mining pass (step 1), writing-skills plus addskill (authoring and repo install), and unslop (prose discipline). It sequences them; it doesn't replace them. + +## Flow + +### 0. Check for an existing skill + +Look for `.claude/skills/*-mode/SKILL.md` in the repo and `~/.claude/skills/*-mode/` globally, matching the user's handle. If one exists, confirm intent (unless they already said "update my skill" or similar): + +- Update the existing skill (default for repeat runs) +- Start fresh (rare; ask why before doing it) + +Update mode changes the rest of the flow: +- Step 1 mines only history since the skill was last edited (`git log -1 --format=%cI `). +- Step 2 asks what's changed or missing, not what to capture from zero. +- Step 4 edits the existing file in place. Preserve sections the user hasn't contradicted; revise ones with new evidence; add new sections only for genuinely new rules. + +### 1. Mine their history + +Locate the current project's transcripts before fanning out. Locally that is `~/.claude/projects//` (the directory whose name encodes the project's absolute path); the project's auto-memory `MEMORY.md` under the same root is also evidence. Use only the current project's scope. Don't glob across other projects' directories: that crosses workspace boundaries and reads private chats from unrelated work. In a sandbox with no transcript access, say so and skip to step 2; questions plus CLAUDE.md and memory carry the draft. + +Survey recent conversations for recurring patterns. Run parallel subagents across slices of history (e.g. last 2-4 weeks split into 3 slices so each has enough material). Each slice miner reads transcripts from the scoped path the parent provides, hunts the signals below, and returns a short structured list of patterns with evidence pointers. Default signals: + +- Response preferences (length, tone, format, "dumb it down" corrections) +- Delegation habits (subagents, models, specialized workflows, parallelism) +- Verification posture (what "done" means; unit tests vs live repro; reviewers) +- Code and prose discipline (style, principles cited, lint/format tools) +- Process conventions (worktrees, commits, PRs, review/merge tooling) +- Meta preferences (fixing skills mid-task, proposing new ones) + +Have each miner return **preference atoms**, not summaries: trigger, decision rule, quality bar, stop condition, evidence pointer, confidence. Rate confidence per atom: **strong** (explicit user preference, workflow-changing correction, repeated pattern, or direct request to encode behavior), **medium** (accepted workflow or repeated tool/validation preference), **weak** (agent-chosen behavior with no user feedback, or a likely task-specific correction), **contradicted** (evidence points in incompatible directions — ask the user before writing anything based on it). + +Cross-check across slices before elevating a signal. Patterns seen in 2+ slices are high-confidence; lone signals are weak and usually get dropped. Contradicted atoms never get codified silently. + +### 2. Ask the user directly + +Mining misses intent that hasn't come up yet. Ask structured multi-choice questions rather than asking the user to type from scratch: lower cognitive load, higher hit rate. + +Shape: one or two questions with 4-6 options each, multi-select for category questions. Start broad ("Which areas matter most?"), then follow up on selected areas with specific options. After the structured rounds, one free-form question catches anything the options missed. + +Don't dump 20 questions. Two structured rounds plus one open question is usually enough. + +### 3. Cluster findings + +Group the combined signals into sections. Common ones (use only what applies): + +- **Response style**: length, tone, format. +- **Autonomy**: how much to do without asking; tool use. +- **Understand first**: which skills to reach for when scoping or investigating. +- **Subagents**: default, parallelism, model-to-task, specialized workflows. +- **Prose / code discipline**: principles, lint tools, style guides. +- **Review and verify**: repro posture, verification skills, live-testing tools. +- **Process**: git worktrees, commits, PRs, review/merge tooling. +- **Skills**: skill-authoring habits, fix-the-skill-first, proposing new skills. + +The fable-mode skill shows the output shape and granularity. Don't copy its content; the user's rules are not fable-mode's. + +### 4. Draft the skill + +Author via writing-skills; install via addskill (repo commit, Codex adapter, compatibility matrix). + +- Path: `.claude/skills/-mode/SKILL.md` in the repo (required for cloud sessions), plus a global symlink if the user wants it machine-wide. +- Handle: the user's first name or chosen identifier. +- Frontmatter `description`: trigger on their name plus `/-mode` plus "work in their style" — not generic keywords like "write code" or "review PR". Mode skills are heavy and opinionated; they should fire on explicit invocation, not auto-trigger on loose description matching. + +### 5. Iterate on prose + +Apply unslop and writing-skills' guidelines to every line. Show the draft to the user and take feedback; expect multiple iterations. Cut ruthlessly: a mode skill is not a manual. + +### 6. Land it + +Work on a branch off freshly-fetched main. Commit and open a PR so the user can review it. Don't push to main directly. + +## Guardrails + +- **Don't overfit to one conversation.** A preference stated once and contradicted another time is noise. Require multiple instances before codifying. +- **Don't be clever.** Restating other skills' contents, inventing metaphors, or writing "poetic" prose for an agent reader is cost without benefit. Keep it operational. +- **Reference, don't inline.** Other skills the user relies on appear as path references, not pasted excerpts. +- **Keep sections minimal.** Only add a section if the user has a specific, non-default rule there. "Communicate clearly" is not a section. "Short paragraphs. Tables when comparing options." is. +- **Name conventions generic.** Use "the user" in imperatives, not the author's first name. Others may read or adopt the skill. +- **Don't force symmetry.** No process rules worth writing down means no Process section. Sparse is fine; bloated is not. + +## Evaluation + +A `-mode` skill is subjective output; a benchmark loop isn't useful here. Vibe-check with the user: does it read like them? Did it miss anything? Then ship. Run a description-optimization loop only if trigger accuracy proves a problem in practice. + +## When not to use + +- User wants a task-specific skill (not working conventions): writing-skills plus addskill alone, no mining. +- User wants one narrow workflow captured ("how I write commit messages"): a regular skill, not a mode skill. + +--- +Adapted from the `automate-me` skill in [cursor/plugins pstack](https://github.com/cursor/plugins/tree/main/pstack) (MIT, by poteto); preference atoms and confidence scale from cursor-team-kit's `workflow-from-chats` (MIT). diff --git a/.claude/skills/babysit-ci/SKILL.md b/.claude/skills/babysit-ci/SKILL.md new file mode 100644 index 0000000..e5ef936 --- /dev/null +++ b/.claude/skills/babysit-ci/SKILL.md @@ -0,0 +1,36 @@ +--- +name: babysit-ci +description: "Watch a PR's checks and iterate on failures until green. Use for /babysit-ci, \"watch CI\", \"fix CI\", \"get the checks green\", or when a PR is waiting on failing or pending checks." +--- + +# Babysit CI + +Drive a PR's checks to green: watch, diagnose, apply the smallest fix, push, repeat. + +`gh pr checks` is the source of truth. It includes all PR-attached checks; `gh run list` only covers GitHub Actions and misses external checks. + +## Workflow + +1. Resolve the active PR: `gh pr view --json number,url,headRefName`. +2. Inspect current checks before waiting: `gh pr checks --json name,bucket,state,workflow,link`. +3. Checks already failed → diagnose those first. For a GitHub Actions check, `gh run view --log-failed` and extract the first actionable error; otherwise follow the check's link to identify the failing command or service. +4. Checks pending → watch with `gh pr checks --watch --fail-fast`. For long waits, run the watch in a background task and continue other work; report when it resolves. +5. Apply the smallest safe fix for one failure cause. Push. +6. Re-run `gh pr checks --json name,bucket,state,workflow,link` after every push — the check set itself can change — and repeat until green. + +## Guardrails + +- Fix one actionable failure at a time; prefer minimal, low-risk changes before broader refactors. +- Never bypass hooks (`--no-verify`) to force progress. +- Failure clearly unrelated to the PR and already fixed on main → merge latest main instead of bloating the PR with unrelated fixes. +- Flaky failure → retry once and report the flake evidence; don't silently re-run until green. +- Verify a fix locally when a cheap local repro of the failing command exists, before spending a CI round trip. + +## Output + +- Current CI status. +- Failure summary and fixes applied, in iteration order. +- PR URL once checks are green; next action if blocked. + +--- +Merged from the `loop-on-ci` + `fix-ci` skills and `ci-watcher` agent in [cursor/plugins cursor-team-kit](https://github.com/cursor/plugins/tree/main/cursor-team-kit) (MIT). diff --git a/.claude/skills/bro/SKILL.md b/.claude/skills/bro/SKILL.md new file mode 100644 index 0000000..cc61770 --- /dev/null +++ b/.claude/skills/bro/SKILL.md @@ -0,0 +1,13 @@ +--- +name: bro +description: "Restate the assistant's last message in plain human language, no jargon. Use when the user says /bro, \"in plain english\", \"dumb it down\", or \"what does that actually mean\"." +--- + +# Bro + +Restate your last message. Stop using jargon and speak coherently. State it more simply and concisely, like one human talking to another. + +Keep every fact, number, and caveat; drop only the vocabulary. If a technical term has no plain substitute, keep the term and add a one-clause gloss. + +--- +Adapted from the `bro` skill in [cursor/plugins pstack](https://github.com/cursor/plugins/tree/main/pstack) (MIT, by poteto). diff --git a/.claude/skills/fable-mode/SKILL.md b/.claude/skills/fable-mode/SKILL.md index 145885f..ac51246 100644 --- a/.claude/skills/fable-mode/SKILL.md +++ b/.claude/skills/fable-mode/SKILL.md @@ -32,6 +32,11 @@ State what done looks like before touching anything. - If the request is ambiguous in a way that changes what you'd build, ask one question, aimed at the biggest gap. Otherwise pick the sensible default, say so in one line, and proceed. Ask questions to change outcomes, not to feel safe. +- Classify a fork before asking about it. If the answer is a fact you could observe by running + something (behavior, timing, output, whether a test separates), it is not the user's to answer: + build the cheapest probe and let the result decide. Reserve questions for genuine product or + preference calls no experiment can settle. A throwaway probe usually answers faster, and it hands + the user a result to react to instead of a decision to make. - Right-size the effort. Match the depth of this process to the stakes of the task. Deep reasoning belongs in planning and review, not in mechanical steps. @@ -79,6 +84,9 @@ Before committing to an answer, switch roles and try to kill it. hide the failures that matter. - Treat good news as suspect. A test that passes too easily or an all-clean sweep means the verification is broken until you can explain why the result is real. +- A change that "might help" is a hypothesis, not a fix; it does not ship. Every shipped line traces + to evidence. When evidence refutes a hypothesis, revert what it motivated. The smallest change the + evidence justifies ships, nothing more. - Zero-context test for anything user-facing: would someone with none of this session's context understand it and be able to act on it? @@ -90,6 +98,9 @@ The report is part of the work, not an afterthought. - Separate verified from assumed, out loud. "I confirmed X by running Y; I'm assuming Z because I couldn't check it." - Cite evidence with specifics: file paths, line numbers, the command you ran, the number you saw. +- Cite rules the same way. Naming a gate, skill, or principle in the report must trace to a specific + decision it changed; a citation with no decision behind it is decoration. Name the choice it drove + or drop the citation. - Report what you observed, not what you intended. If tests failed, say so with the output. If a step was skipped, say that. - Never soften a real problem to be agreeable. Disagreement with concrete reasoning beats compliance. @@ -111,6 +122,9 @@ The report is part of the work, not an afterthought. decisions the user genuinely owns, and bundle the questions. - Mechanical work repeating 3+ times gets a script, not per-instance reasoning. Reasoning is for judgment; scripts are for repetition. +- When a skill, playbook, or checklist supplies steps, copy them into the plan verbatim before + adding task-specific ones. A step you choose not to do stays in the plan with a one-line + `skip: `; dropping a step silently is not allowed. - Preserve by default. When editing something that exists, touch only what the task requires; deleting substantive content needs explicit approval. @@ -131,7 +145,7 @@ Any one of these: stop, go back to that gate. - This is a method skill, not a workflow. It changes how you execute the current task; it produces no files of its own. -- It stacks with task-specific skills (/proveit, /verify, /code-review). Those are the "how to check" +- It stacks with task-specific skills (/impartial-review, /code-review). Those are the "how to check" tools; this is the discipline of when to reach for them. - Don't apply it to trivial work. Forcing all five gates onto a two-minute edit is its own failure mode. diff --git a/.claude/skills/humanizer/SKILL.md b/.claude/skills/humanizer/SKILL.md index c2a9c76..b4266d6 100644 --- a/.claude/skills/humanizer/SKILL.md +++ b/.claude/skills/humanizer/SKILL.md @@ -63,12 +63,12 @@ Removing patterns is half the job. ## Pattern checklist -Scan for these. Numbers map to `patterns.md` for examples. +The canonical tell list is the `unslop` skill (`.claude/skills/unslop/SKILL.md`, or `~/.claude/skills/unslop/` globally) — the always-on floor this deep pass builds on. Scan its full list every pass; don't duplicate it here. The table below is the index into `patterns.md` for before/after examples, and carries the humanizer-only extras (tail negations, authority tropes, signposting, hyphenated compounds). | # | Category | Scan for | |---|----------|----------| | 1–6 | Content | Significance inflation; notability name-drops; promotional language; vague attribution; formulaic "despite challenges…" sections | -| 7–12 | Language | AI vocabulary; copula dodge (serves as → is); -ing filler; negation pivots in any disguise ("not just X, it's Y", "the point isn't X. It's Y", "less about X than Y"); tail negations; rule of three; synonym cycling; false ranges | +| 7–12 | Language | AI vocabulary; copula dodge (serves as → is); -ing filler; "not just X, it's Y"; tail negations; rule of three; synonym cycling; false ranges | | 13 | Grammar | Passive voice and subjectless fragments when active voice is clearer | | 14–19 | Style | Em dash overuse; colon as mid-sentence crutch; mechanical boldface; inline-header bullets that restate the line; Title Case headings; decorative emojis; curly quotes | | 20–22 | Chatbot | "I hope this helps", cutoff disclaimers, sycophantic openers | @@ -77,15 +77,6 @@ Scan for these. Numbers map to `patterns.md` for examples. | 27–29 | Framing | Authority tropes (at its core); signposting (let's dive in); fragmented headers | | 30–34 | Plain speech | Abstract jargon nouns (substrate, wedge, paradigm); vague product copy; dense sentences; weak adverbs; fancy synonyms (utilize → use) | -**Compact scan lines** (use every pass): - -- **Content** — pivotal moment, testament, evolving landscape, nestled, experts say, despite challenges… continues to thrive. -- **Language** — delve, crucial, showcase, foster, leverage, serves as, highlighting…/ensuring…, negation pivots in any disguise (not just X it's Y; the point isn't X. It's Y; isn't about A, it's about B; less about X than Y), rule of three, from X to Y. -- **Style** — do not use excessive em dashes (—); use periods, commas, semicolons, or hyphens instead. Also cut colon comparison crutches, **Speed:** Speed improved…, Great question! / I hope this helps! -- **Plain speech** — substrate/wedge/harness/paradigm; feelings instead of mechanism; split sentences that need a second read; utilize/leverage/facilitate. - -**Inline-header nuance:** bad = `**Speed:** Speed improved…` (label restates the line). OK = `**Schema in TypeScript.** Tables live in one file.` (label names; next sentence adds detail). - ## Output ### Default (most requests) diff --git a/.claude/skills/impartial-review/SKILL.md b/.claude/skills/impartial-review/SKILL.md index a174152..99a7605 100644 --- a/.claude/skills/impartial-review/SKILL.md +++ b/.claude/skills/impartial-review/SKILL.md @@ -27,6 +27,8 @@ State the scope you're reviewing in your first sentence so the user can redirect If you're not sure, dispatch. Subagents are cheap relative to a missed bug. +**Strict quality mode (opt-in):** when the user asks for a "strict", "harsh", "thermo-nuclear", or deep maintainability review, additionally load `strict-quality-rubric.md` from this folder and append it to the Bucket D ("things the author missed") subagent's prompt — missed structural simplifications are exactly its territory. It raises the approval bar to presumptive blockers (code-judo simplifications, 1k-line rule, spaghetti growth) on top of the normal buckets; correctness review is unchanged. + ## Step 3: Dispatch five parallel Sonnet 4.6 review subagents Send all five `Agent` tool calls **in a single message** so they run concurrently. Each uses: @@ -291,9 +293,9 @@ This rule is repeated inside each subagent prompt, but it also applies to your i When the five agents return — **this is the precision stage.** The subagents over-reported on purpose (coverage); your job is to verify and rank so the human gets a trustworthy list. You're running on the strongest available model, and this verification is exactly where it earns its cost. Reviewing the subagents' work is the point — do not rubber-stamp it. -1. **Deduplicate.** Two agents may flag the same issue from different angles — merge into one finding, keep the higher severity. Bucket E findings often overlap with A/B/C/D (e.g., a cover-identity leak is also a correctness issue) — merge but preserve E's rule citation so the human sees *why* it's a violation. +1. **Deduplicate — and read agreement as signal.** Two agents may flag the same issue from different angles — merge into one finding, keep the higher severity. Bucket E findings often overlap with A/B/C/D (e.g., a cover-identity leak is also a correctness issue) — merge but preserve E's rule citation so the human sees *why* it's a violation. The same issue surfaced independently by two or more subagents is high-confidence signal: note the agreement on the merged finding ("flagged independently by A and D") and weight it accordingly when you verify. A lone-agent finding is still worth verifying, just with lower prior. 2. **Verify every finding you intend to surface — across all severities, not just 🔴.** The finding stage deliberately over-reported, including LOW-confidence items; turning that into precision is your job. For each finding, run a real `grep`/`Read` to confirm before passing it to the human (for Bucket E, open the cited rule file and confirm the rule actually says what the agent claimed — paraphrased rules are the most common Bucket E failure mode). Treat the 🔴s adversarially: a fresh-context subagent in a hurry is exactly the kind of reviewer that produces plausible-but-wrong blockers, so try to *refute* each one before you accept it. - - **Own the confidence filter — but drop only on evidence.** A finding tagged LOW-confidence gets *confirmed* (verify, then promote and re-tag), *refuted* (drop it — optionally note it under "checked and verified fine"), or *kept as LOW* with a one-line note on the residual uncertainty. Drop a finding **only because you checked and it isn't real** — never because it "seems minor" or "seems unlikely." Filtering on vibes here re-introduces exactly the recall loss the coverage-first finding stage was built to prevent. + - **Own the confidence filter — but drop only on evidence.** A finding tagged LOW-confidence gets *confirmed* (verify, then promote and re-tag), *refuted* (drop it from the findings list and record it under "Dismissed" with the reason), or *kept as LOW* with a one-line note on the residual uncertainty. Drop a finding **only because you checked and it isn't real** — never because it "seems minor" or "seems unlikely." Filtering on vibes here re-introduces exactly the recall loss the coverage-first finding stage was built to prevent. 3. **Severity-order globally.** All 🔴 first across all buckets, then all 🟡, then 🟢 — not bucket-by-bucket and not in the order agents returned. 4. **Present in this format:** @@ -314,6 +316,12 @@ After the findings, include: - [Suspicious-looking item that's actually OK, with a one-line reason. Merge these from all five subagents so the human doesn't re-investigate.] +## Dismissed + +- [Every subagent finding you refuted during verification, with the one-line + reason it's wrong or missing context. Never silently drop a finding: showing + the dismissal lets the human override your judgment.] + ## Recommendation [Which fixes are blocking merge, which can be a follow-up, which can be skipped. diff --git a/.claude/skills/impartial-review/strict-quality-rubric.md b/.claude/skills/impartial-review/strict-quality-rubric.md new file mode 100644 index 0000000..d49e261 --- /dev/null +++ b/.claude/skills/impartial-review/strict-quality-rubric.md @@ -0,0 +1,51 @@ +# Strict quality rubric ("thermo-nuclear" mode) + +Load only when strict mode is requested. Condensed from cursor-team-kit's `thermo-nuclear-code-quality-review` (MIT). This is a maintainability audit on top of the normal buckets — it does not replace correctness review. + +## Core stance + +Be ambitious about structural simplification. Do not stop at "this could be a bit cleaner." Look for "code judo" moves: restructurings that preserve behavior while whole branches, helpers, modes, conditionals, or layers disappear entirely. Prefer the solution that makes the code feel inevitable in hindsight. If you see a path to delete complexity rather than rearrange it, push hard for that path. + +## Non-negotiables + +1. **1k-line rule.** Do not let a PR push a file from under 1k lines to over 1k lines without a very strong reason. Treat crossing the threshold as a strong smell; prefer extracting helpers, subcomponents, or modules first. Waive only with a compelling structural reason and a still-organized result. +2. **No spaghetti growth.** New ad-hoc conditionals, scattered special cases, or one-off branches in unrelated flows are a design problem, not a stylistic nit. Push the logic into a dedicated abstraction, helper, state machine, or module. +3. **Clean the design, don't just accept working code.** Same behavior with meaningfully cleaner structure beats "it works". Prefer simplifications that remove moving pieces over refactors that spread the same complexity around. +4. **Direct, boring, maintainable over hacky or magical.** Flag thin abstractions, identity wrappers, and pass-through helpers that add indirection without buying clarity; be skeptical of generic mechanisms hiding simple data-shape assumptions. +5. **Type and boundary cleanliness.** Question unnecessary optionality, `unknown`, `any`, and cast-heavy code where a clearer type boundary could exist. A branch relying on silent fallback to paper over an unclear invariant should make the boundary explicit instead. +6. **Canonical layer and helpers.** Call out feature logic leaking into shared paths, and bespoke helpers where a canonical utility exists. Push code to the package/module/layer that owns the concept. +7. **Orchestration and atomicity.** Flag needless sequential orchestration of independent work and partial-update logic that leaves state half-applied, when the cleaner structure is obvious. Don't over-index on micro-optimizations. + +## Flag aggressively + +A cleaner reframing that would delete whole categories of complexity · refactors that move code without reducing concepts a reader holds · a file crossing 1000 lines due to the PR · new conditionals bolted onto unrelated paths · one-off booleans/nullable modes complicating control flow · copy-pasted logic instead of extracted helpers · edge-case handling in the middle of an already busy function · "temporary" branching likely to become permanent debt. + +## Preferred remedies + +Delete a layer of indirection rather than polishing it · reframe the state model so conditionals disappear · turn special-case logic into a simpler default flow with fewer exceptions · replace condition chains with a typed model or explicit dispatcher · separate orchestration from business logic · split the large file into focused modules · reuse the canonical helper. + +Not satisfied with "maybe rename this" when the real issue is structural. Not satisfied with a merely cleaner version of the same messy idea when a much simpler idea is plausible. + +## Tone + +Direct, serious, demanding; not rude, but never soften major maintainability issues into mild suggestions. Say things like: + +- "this pushes the file past 1k lines. can we decompose this first?" +- "this adds another special-case branch into an already busy flow. can we move this behind its own abstraction?" +- "i think there's a code-judo move here that makes this much simpler. can we reframe this so these branches disappear?" +- "this refactor moves complexity around, but doesn't really delete it. is there a way to make the model itself simpler?" + +## Output priority + +1. Structural regressions → 2. missed dramatic-simplification opportunities → 3. spaghetti/branching growth → 4. boundary/type-contract problems → 5. file-size/decomposition → 6. modularity → 7. legibility. Few high-conviction comments beat a long cosmetic list. + +## Approval bar + +Do not approve merely because behavior seems correct. Presumptive blockers unless clearly justified by the author: + +- Preserves a lot of incidental complexity when a plausible code-judo move would delete it. +- Pushes a file from below 1000 lines to above. +- Adds ad-hoc branching that tangles an existing flow. +- Scatters feature checks across shared code to solve a local problem. +- Adds an unnecessary abstraction, wrapper, or cast-heavy contract. +- Duplicates an existing helper or puts logic in the wrong layer. diff --git a/.claude/skills/unslop/SKILL.md b/.claude/skills/unslop/SKILL.md new file mode 100644 index 0000000..8a07db5 --- /dev/null +++ b/.claude/skills/unslop/SKILL.md @@ -0,0 +1,101 @@ +--- +name: unslop +description: "Always-on AI-tell stripper: apply its pattern check to everything written for humans (chat prose, commits, PR bodies, docs, UI text). Also use when the user says /unslop, \"unslop this\", or points at text or a file to clean." +--- + +# Unslop + +Strip AI patterns from writing. Write clean first: never generate the tell and fix it after. The cleanup-afterward pass has been measured to fail, so the bad sentence must not be produced in the first place. + +## Always-on contract + +This skill is a session default (see CLAUDE.md). It applies at write time to every artifact a human will read: chat replies, commit messages, PR titles and bodies, docs, READMEs, UI text, summaries, issue comments. + +Exempt: code, symbol/function/API names, error strings, quoted text, file contents reproduced verbatim. + +Coexists with other modes: + +- **caveman** compresses; unslop strips tells. Both apply to chat prose. +- **humanizer** is the on-request deep pass: voice-matching, file rewrites, soul-adding for long-form drafts. Unslop is the always-on floor. For "humanize this in my voice", load humanizer. + +## On-demand mode (`/unslop `) + +1. Scan for the patterns below. +2. Rewrite. Preserve meaning and every fact; match intended tone. +3. Self-audit: "What makes this obviously AI generated?" Fix remaining tells. +4. For files: targeted section edits, show the diff, never silently overwrite. + +## Patterns to detect and never write + +### Content + +1. **Puffery.** "pivotal moment", "testament to", "evolving landscape", "setting the stage for", "indelible mark". State what happened. +2. **Superficial -ing phrases.** "highlighting...", "ensuring...", "showcasing...", "fostering...". Delete or expand with real substance. +3. **Promotional language.** "nestled", "vibrant", "breathtaking", "groundbreaking", "renowned", "stunning". Neutral description. +4. **Vague attributions.** "Experts believe", "Industry reports suggest". Name the source or delete. +5. **Formulaic challenges.** "Despite challenges... continues to thrive." Specific facts. + +### Language + +6. **AI vocabulary.** Additionally, crucial, delve, enduring, enhance, fostering, garner, interplay, intricate, landscape (abstract), pivotal, showcase, tapestry (abstract), testament, underscore, vibrant. Plain words. +7. **Fancy ways to say "is".** "serves as", "stands as", "boasts", "features". Say "is" or "has". +8. **"Not just X, but Y."** State the point directly. +9. **Rule of three.** Forcing ideas into groups of three. Use the natural number. +10. **Synonym cycling.** Protagonist, main character, central figure in one paragraph. Pick one, repeat it. +11. **False ranges.** "from X to Y" where X and Y aren't on a meaningful scale. List directly. + +### Style + +12. **Em dashes.** Never. Use `.` `,` `:` `;` `·`. No parentheses or en dashes as substitutes; end the sentence or use a comma. +13. **Colon as mid-sentence connector.** Colons before a list or example are fine. As a rhetorical hinge ("If you're coming from X: instead of...") rewrite so the point stands alone. +14. **Boldface overuse.** Don't bold every proper noun or acronym. +15. **Inline-header lists.** Bold label + colon restating the line ("**Performance:** Performance improved...") is a tell; convert to prose. A bold lead-in ending in a period followed by genuinely new detail is fine. +16. **Title case headings.** Sentence case. +17. **Decorative emojis** in headings and bullets. Remove. +18. **Curly quotes.** Straight quotes. + +### Communication artifacts + +19. **Chatbot phrases.** "I hope this helps!", "Let me know if...", "Of course!", "Certainly!", "Found the smoking gun!" Remove. +20. **Sycophancy.** "Great question! You're absolutely right!" Respond directly. +21. **Cutoff disclaimers.** "While specific details are limited..." Find the fact or remove. + +### Filler + +22. **Filler phrases.** "In order to" → "To". "Due to the fact that" → "Because". "It is important to note that" → delete. +23. **Hedging stacks.** "could potentially possibly be argued that it might" → "may". +24. **Generic conclusions.** "The future looks bright." Specific plans or facts, or nothing. + +### Jargon + +25. **Abstract metaphor nouns.** Substrate, wedge, vector, locus, nexus, primitive (noun), harness (metaphor), surface ("API surface"), bedrock, scaffolding (metaphor), paradigm, gold-plating, ratchet (metaphor), north star, flywheel, endgame. Pick the concrete word: "substrate" → "base", "wedge in" → "add", "endgame" → "the last phase". + +### Plain speech + +26. **Say what it does, not how it feels.** "SQL you can read", "types that follow your schema" name a feeling. Name the mechanism or a number instead: "`.toSQL()` returns the exact string sent to the database", "a column rename fails the build". If a sentence can't be restated as a concrete instruction, fact, or number, cut it. If it could appear unchanged in another project's docs, it says nothing about this one; cut it. +27. **One idea per sentence.** If the reader backtracks to parse, split or drop clauses. +28. **Active voice.** "queries are validated" → "the compiler validates queries". Passive only when the actor is unknown or genuinely irrelevant. +29. **Cut adverbs or use the number.** "runs quickly" → "is fast" or the measurement. "significantly improves" → the measured delta. +30. **Plain word over fancy synonym.** "utilize" → "use", "leverage" → "use", "facilitate" → "help", "numerous" → "many", "in the event that" → "if". + +## Code diffs (`/unslop the diff`) + +Code has its own slop. When pointed at a diff (default: against main), remove AI patterns introduced in the branch: + +- Extra comments that are unnecessary or inconsistent with local style. +- Defensive checks or try/catch blocks abnormal for trusted code paths. +- Casts to `any` used only to bypass type issues. +- Deeply nested code that early returns would simplify. +- Other patterns inconsistent with the file and surrounding codebase. + +Guardrails: keep behavior unchanged unless fixing a clear bug; minimal focused edits over broad rewrites; summary in 1-3 sentences. + +## Anti-patterns + +- Don't drop a fact, caveat, or qualifier to remove a tell. Accuracy beats cleanliness. +- Don't apply to code, identifiers, error strings, or quoted material. +- Don't run a visible "cleanup pass" over your own fresh prose; write it clean the first time. +- Don't replace humanizer for voice-matching or long-form rewrites; that's its job. + +--- +Adapted from the `unslop` skill in [cursor/plugins pstack](https://github.com/cursor/plugins/tree/main/pstack) (MIT, by poteto); code-diff section from cursor-team-kit's `deslop` (MIT). diff --git a/.claude/skills/verify-this/SKILL.md b/.claude/skills/verify-this/SKILL.md new file mode 100644 index 0000000..a4cd5e4 --- /dev/null +++ b/.claude/skills/verify-this/SKILL.md @@ -0,0 +1,74 @@ +--- +name: verify-this +description: "Verify a claim with fresh local evidence: restate it falsifiably, capture baseline and treatment, compare, return VERIFIED, NOT VERIFIED, or INCONCLUSIVE. Use for /verify-this, \"prove it works\", \"did this fix it\", \"show me the evidence\"." +--- + +# Verify this + +Verification is not a recap. It proves or disproves a specific claim with repeatable evidence. + +## When to use + +- The user asks "verify this", "prove it works", "did this fix it", or "show me the evidence". +- A bug fix needs a before/after repro. +- A UI, CLI, API, performance, or memory claim needs measurement. +- A test passes but the user-visible behavior still needs confirmation. + +Do not use this for vague claims like "the code is cleaner". Ask for a measurable claim first. + +## Workflow + +1. Restate the claim in falsifiable form: condition, metric, and threshold. +2. Pick the smallest local surface that can disprove it. +3. Capture a baseline from the old state: merge base, parent commit, failing branch, or current broken repro. +4. Capture treatment from the changed state with the same command, data, warmup, and environment. +5. Compare raw artifacts: numbers, screenshots, terminal transcripts, HTTP responses, profiles, heap snapshots, or test output. +6. Return exactly one verdict: `VERIFIED`, `NOT VERIFIED`, or `INCONCLUSIVE`. + +## Local surfaces + +- Code behavior: focused unit/integration tests or a minimal repro script. +- CLI/TUI behavior: a terminal transcript of the real command. +- UI behavior: browser screenshots, page-text extraction, accessibility snapshots (see the `run` skill and the sentinel check in `pitfalls.md` — confirm the page under test is serving the current code before trusting any capture). +- API behavior: local HTTP/RPC request and response diff. +- Performance: same-machine baseline/treatment timings or CPU profiles. +- Memory: heap snapshots before and after the suspected operation. + +## Artifact layout + +When safe to write artifacts: + +```text +.tmp/verify-this// +├── claim.md +├── baseline/ +├── treatment/ +├── diff/ +└── verdict.md +``` + +If artifacts may contain sensitive code, prompts, screenshots, HTTP bodies, or heap data, keep only the minimal inline evidence unless the user agrees to disk storage. + +## Verdict rules + +- `VERIFIED`: baseline and treatment differ in the predicted direction, by the claimed threshold, with no obvious confound. +- `NOT VERIFIED`: the behavior is unchanged, moves the wrong way, or misses the threshold. +- `INCONCLUSIVE`: no valid baseline, noisy signal, failed measurement, or an environment difference invalidates the comparison. + +## Output + +```text +VERIFIED | NOT VERIFIED | INCONCLUSIVE +Claim: + +Evidence: +: baseline=<...>, treatment=<...>, delta=<...>, threshold=<...> + +Reasoning: + +``` + +Do not soften a negative result. A clear `NOT VERIFIED` is useful. + +--- +Adapted from the `verify-this` skill in [cursor/plugins cursor-team-kit](https://github.com/cursor/plugins/tree/main/cursor-team-kit) (MIT). diff --git a/.claude/skills/writing-skills/SKILL.md b/.claude/skills/writing-skills/SKILL.md index 89925fd..7b7f47b 100644 --- a/.claude/skills/writing-skills/SKILL.md +++ b/.claude/skills/writing-skills/SKILL.md @@ -16,7 +16,7 @@ You write test cases (pressure scenarios with subagents), watch them fail (basel **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing. -**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation. +**BACKGROUND:** This skill adapts TDD's fundamental RED-GREEN-REFACTOR cycle to documentation. **Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill. @@ -281,13 +281,54 @@ wc -w skills/path/SKILL.md **When writing documentation that references other skills:** Use skill name only, with explicit requirement markers: -- ✅ Good: `**REQUIRED SUB-SKILL:** Use superpowers:test-driven-development` -- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand superpowers:systematic-debugging` -- ❌ Bad: `See skills/testing/test-driven-development` (unclear if required) -- ❌ Bad: `@skills/testing/test-driven-development/SKILL.md` (force-loads, burns context) +- ✅ Good: `**REQUIRED SUB-SKILL:** Use writing-plans` +- ✅ Good: `**REQUIRED BACKGROUND:** You MUST understand brainstorming` +- ❌ Bad: `See skills/planning/writing-plans` (unclear if required) +- ❌ Bad: `@skills/planning/writing-plans/SKILL.md` (force-loads, burns context) **Why no @ links:** `@` syntax force-loads files immediately, consuming 200k+ context before you need them. +## Invocation Economics + +Every skill charges one of two loads: + +- **Context load** — a model-invoked skill's description sits in the context window every turn. You pay tokens and attention permanently in exchange for agent discoverability. +- **Cognitive load** — a user-invoked skill (`disable-model-invocation: true`) costs nothing per turn, but the human must remember it exists and when to reach for it. The human is the index. + +Pick model-invocation only when the agent must fire the skill on its own, or another skill must reach it. If it only ever fires by hand, make it user-invoked and pay zero context load. + +When user-invoked skills multiply past what the human can remember, add a **router skill**: one user-invoked skill that names the others and when to reach for each. It can only hint, never fire them — user-invoked skills have no description, so nothing but the human can reach them. + +**Pointer wording is a variance lever.** A link's wording, not its target, decides when and how reliably the agent follows it. Must-have material behind a weakly-worded pointer is a variance bug: sharpen the wording first; inline the material only if that fails. + +## Steering Levers + +Levers that make a skill produce the same *process* every run. Predictability means same process, not same output — a brainstorming skill should predictably diverge. + +### Leading words + +A **leading word** is a compact concept already living in the model's pretraining that anchors a whole region of behavior in the fewest tokens: *tracer bullet*, *fog of war*, *relentless*, a *tight* loop. Repeated as a token (never as a sentence), it accumulates a distributed definition and recruits priors the model already holds — for free. + +- Hunt for restatements to collapse: "fast, deterministic, low-overhead" → a *tight* loop. Fewer tokens AND a sharper hook. +- Prefer pretrained words. A coined term recruits no priors — you pay in definition tokens what a pretrained word gives free. +- Use the same word in the description, the body, and your own prompts. Shared language fires the skill more reliably. +- A leading word too weak to beat the default behavior is a no-op ("be thorough" when the agent is already thorough-ish). Fix: stronger word (*relentless*), not more prose. + +### Completion criteria + +Every step ends on a completion criterion with two properties: + +- **Clarity** — can the agent tell done from not-done? A vague bound ("understanding reached") invites **premature completion**: attention slips to *being done* rather than the work, and visible later steps strengthen the pull. Sharpen the criterion first (cheap, local); hide later steps by splitting the sequence only when the criterion is irreducibly fuzzy AND you actually observe the rush. +- **Demand** — how much it requires sets the depth of work. "Every modified model accounted for" forces thoroughness where "produce a change list" does not. Demand also binds flat reference: "every rule applied" makes a checklist exhaustive. + +### The no-op test + +For every line: does it change behavior versus what the model does by default? A perfectly relevant line can still be a no-op — you pay load to say nothing. When a sentence fails the test, delete the whole sentence rather than trimming words from it. Disputes over whether a line is a no-op are disputes about the default — settle them by running the skill, not by debate. + +### Negation + +"Don't think of an elephant" names the elephant. A prohibition drags the banned behavior into context and half-reads as an instruction to do it. Default to the **positive**: state the target behavior ("write one-line comments") so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively — the loophole-closing lists in this skill are exactly that case — and even then, pair it with the positive target so attention lands on what to do. + ## Flowchart Usage ```dot @@ -391,7 +432,7 @@ Edit skill without testing? Same violation. - Don't "adapt" while running tests - Delete means delete -**REQUIRED BACKGROUND:** The superpowers:test-driven-development skill explains why this matters. Same principles apply to documentation. +**BACKGROUND:** The same TDD principles apply to documentation. ## Testing All Skill Types @@ -399,7 +440,7 @@ Different skill types need different test approaches: ### Discipline-Enforcing Skills (rules/requirements) -**Examples:** TDD, verification-before-completion, designing-before-coding +**Examples:** TDD, designing-before-coding **Test with:** - Academic questions: Do they understand the rules? @@ -442,6 +483,16 @@ Different skill types need different test approaches: **Success criteria:** Agent finds and correctly applies reference information +### Blinding Rules (all test types) + +An agent that knows it's being evaluated behaves differently, so test candidates must run blind: + +- No `eval`, `test`, `judge`, `experiment`, `rubric`, `score`, `compare`, `benchmark`, or `candidate` in any directory name, file name, or prompt the candidate sees. +- Sanitize directory and slug names: use project-shaped names a user might pick, not labels like `candidate-1` or `agent-a`. +- Hold the rubric back from candidates; it exists for the judge only. +- A judge may know it's judging, but sees outputs by sanitized label only — never by model or variant name. Comparing two variants: one judge scores both sets in a single pass on one scale, blind to which set each came from. +- Grade compliance from the files the candidate actually read plus the shape of its output, never from the candidate's own claims about what it did. + ## Common Rationalizations for Skipping Testing | Excuse | Reality | diff --git a/CLAUDE.md b/CLAUDE.md index 7301dc9..d337a70 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -92,3 +92,7 @@ After adding, removing, or editing a skill or `skillOverrides`, run `node .claude/scripts/sync-codex-skills.mjs --write` and include the generated `.agents/skills/` changes. Do not hand-edit generated adapters; `AGENTS.md` owns Codex-specific runtime safety and tool translation. + +## Always-on unslop + +Everything written for humans passes the `unslop` skill's pattern check at write time: chat prose, commit messages, PR bodies, docs, READMEs, UI text. Write clean first; never generate the tell and fix it after. Caveman compresses, unslop strips tells; both apply. Pattern list: `.claude/skills/unslop/SKILL.md`. Read it before the first substantial written artifact of a session.