From c927ac1c6e041f96326e4a32e76ca13da8f6f5be Mon Sep 17 00:00:00 2001 From: main Date: Tue, 31 Mar 2026 14:21:52 -0400 Subject: Initial import --- skills/exterminate-slop/SKILL.md | 472 +++++++++++++++++++++++++++++ skills/exterminate-slop/agents/openai.yaml | 4 + skills/rust-bootstrap/SKILL.md | 53 ++++ skills/rust-bootstrap/agents/openai.yaml | 4 + 4 files changed, 533 insertions(+) create mode 100644 skills/exterminate-slop/SKILL.md create mode 100644 skills/exterminate-slop/agents/openai.yaml create mode 100644 skills/rust-bootstrap/SKILL.md create mode 100644 skills/rust-bootstrap/agents/openai.yaml (limited to 'skills') diff --git a/skills/exterminate-slop/SKILL.md b/skills/exterminate-slop/SKILL.md new file mode 100644 index 0000000..a6b572b --- /dev/null +++ b/skills/exterminate-slop/SKILL.md @@ -0,0 +1,472 @@ +--- +name: exterminate-slop +description: Perform an exhaustive Rust-only subtree audit and refactor pass for primitive obsession, under-abstraction, and DRY violations. Use when Codex needs to inspect every Rust file in a requested code subtree for strings, bools, tuples, parameter clumps, duplicated logic, repeated field bundles, or weak abstractions, and must follow a rigid ledgerized process instead of a loose best-effort review. +--- + +# Exterminate Slop + +Read the repo's [AGENTS.md](../../AGENTS.md) first. + +Rust only. Do not spend context on language-agnostic framing. + +## Contract + +- Require a concrete Rust subtree. If the user names only a repo, choose the smallest plausible subtree and state the assumption. +- Default to `audit_plus_refactor` unless the user clearly wants findings only. +- Inspect every `*.rs` file in scope. No sampling and no “representative files.” +- Create one persistent `/tmp` worklog before the first code read. Chat is summary only; the worklog is the durable source of truth. +- Partition the manifest into intentional logical cliques before deep reading. +- Read at most 8 files per wave. +- Write a `/tmp` checkpoint after every wave before reading more files. +- Record raw suspects during coverage, then promote only threshold-clearing suspects into the formal ledger after full coverage. +- Force a decision on every promoted ledger row. +- Do not edit until the promoted ledger exists, unless the user explicitly asked for a narrow hotfix instead of a full extermination pass. + +Files may be re-read. Re-reading is expected when a file belongs to multiple logical cliques or when a later duplication cluster changes the correct abstraction boundary. + +## Flow + +### 0. Create the worklog + +Create a path shaped like: + +```text +/tmp/exterminate-slop--.md +``` + +Seed it with the embedded worklog skeleton from `Embedded Forms`. + +The worklog must hold: + +- the manifest +- the clique plan +- every wave checkpoint +- the rejected clusters +- the promoted ledger +- the residual sweep + +If interrupted or resumed, reopen the same worklog before continuing. + +### 1. Lock scope and manifest + +Enumerate the full Rust-file manifest, for example with: + +```bash +rg --files -g '*.rs' +``` + +Write the manifest in the embedded form from `Embedded Forms` and persist it into the `/tmp` worklog immediately. + +### 2. Plan logical cliques + +Before deep reading, group manifest files into small logical cliques using the embedded clique-wave form from `Embedded Forms`. + +Good clique causes: + +- shared domain types +- repeated parse / validate / normalize flows +- repeated rendering / formatting flows +- repeated control-flow skeletons +- repeated construction / patch / conversion logic +- module-boundary interactions +- suspected duplication clusters + +Cliques may overlap. A file may appear in multiple cliques. Keep cliques to 2-8 files; split larger conceptual groups into multiple related waves. + +### 3. Run bounded coverage waves + +For each clique wave: + +- read at most 8 files +- use `rust_analyzer` aggressively for definitions, references, rename feasibility, and boundary understanding +- prefer `rust_analyzer` from live use sites in the current clique, not blind declaration-first jumps +- update the manifest coverage +- write a `/tmp` checkpoint containing: + - clique id and purpose + - files inspected in the wave + - raw suspects + - duplication hypotheses strengthened or weakened + - files worth re-reading in later cliques + +Do not read a 9th file until that checkpoint exists. A file counts as covered once it has been read in at least one wave. + +Concrete `rust_analyzer` pattern: + +- start at a live use site: field access, constructor call, function call, match arm, or repeated conversion site +- use hover or definition there to anchor the actual symbol in play +- then expand with references once the anchor is correct +- use rename feasibility only after the symbol has been anchored from a concrete use site + +If declaration-first references are noisy or incomplete, return to a concrete use site and trace outward again. + +### 4. Run smell passes + +Run distinct passes over the manifest and checkpointed suspects. If a pass needs more context, form another clique and respect the 8-file cap again. + +#### String suspicion + +Interrogate meaningful `String`, `&str`, string discriminators, and stringly keys. + +Ask whether the value is really an id, slug, path, URL, email, unit, currency, locale, timestamp, status, or other validated domain token; whether normalization or parsing repeats at call sites; whether the value set is finite; and whether multiple strings travel together as a latent record. + +#### Bool suspicion + +Interrogate meaningful `bool`. + +Ask whether it is really a mode, strategy, phase, policy, capability, or tri-state; whether call sites become unreadable because the meaning is positional; and whether correlated bools are encoding illegal states that want an enum or policy type. + +#### Tuple suspicion + +Interrogate tuple types, tuple returns, and repeated destructuring. + +Ask whether the order is accidental, whether the elements have stable names in human discussion, whether the tuple crosses module boundaries, and whether the same shape is repeatedly rebuilt or unpacked. + +#### Parameter-clump and field-bundle suspicion + +Interrogate functions, constructors, builders, and repeated local bundles. + +Ask whether the same 2-5 values travel together repeatedly, whether repeated bundles imply invariants, and whether an argument list wants a domain struct or value object. + +#### Duplication and under-abstraction + +Search for repeated parse / validate / normalize pipelines, repeated format / render / serialize logic, repeated match skeletons, repeated field-by-field copying, repeated conversions, repeated error shaping, and repeated query predicates. + +#### Primitive control encodings + +Interrogate string discriminators, integer type codes, sentinel values, parallel collections implying a missing domain object, and repeated `Option` / `bool` combinations that really encode richer states. + +### 5. Promote suspects + +During coverage, keep only raw suspects. After every manifest file has been inspected at least once, promote a suspect into the formal ledger only if at least one is true: + +- it appears in more than one file or module +- it crosses a crate or module boundary +- it shows invariant pressure rather than mere cosmetic repetition +- the fix is locally actionable now + +Anything not promoted must still be accounted for as a short rejected cluster using the embedded rejected-cluster form from `Embedded Forms`. Persist both promoted and rejected outcomes in the `/tmp` worklog. + +### 6. Populate and adjudicate the promoted ledger + +Populate the formal ledger with the embedded ledger form from `Embedded Forms`. Only promoted candidates belong there. + +For every row, run the embedded adjudication checklist and choose exactly one: + +- `refactor_now` +- `defer` +- `false_positive` +- `needs_broader_design` + +Keep the authoritative ledger in the `/tmp` worklog even if chat shows only a condensed view. + +### 7. Refactor in batches + +Group work by abstraction move rather than by file. + +Preferred moves: + +- primitive id or validated token → newtype / value object +- string or bool discriminator → enum +- tuple or clump → named struct +- repeated validation or parsing → constructor or smart parser +- repeated conversion or patch logic → dedicated helper, trait, or module +- repeated branch skeleton → extracted abstraction + +Apply the more specific move guidance in `Embedded Refactor Playbook`. + +Preserve public API compatibility only if the user asked for it. Otherwise prefer the clean shape. + +### 8. Verify and sweep + +After edits: + +- run relevant checks on the touched surface +- re-scan the same manifest +- update the worklog with eliminated rows, deferred rows, false positives, and residual hotspots + +Prefer the narrowest checks that still validate the changed surface, then widen if needed. + +## Embedded Forms + +### Worklog Skeleton + +Create one persistent worklog file per extermination run. + +```text +worklog_path: +scope_root: +inspection_mode: audit_only | audit_plus_refactor +wave_size_limit: 8 + +manifest: + +clique_plan: + +wave_checkpoints: + +rejected_clusters: + +promoted_ledger: + +residual_sweep: +``` + +Rules: + +- create this file before the first code read +- update it after every 8-file wave before reading more files +- treat it as the durable source of truth for the run +- if chat summaries are shorter, the worklog still must remain complete +- report the final worklog path in the user-facing response + +### File Manifest + +Build this before analysis starts. + +```text +scope_root: +inspection_mode: audit_only | audit_plus_refactor +wave_size_limit: 8 + +files: +- [ ] path/to/file_a.rs +- [ ] path/to/file_b.rs +- [ ] path/to/file_c.rs +``` + +Rules: + +- include every `*.rs` file in the requested subtree +- mark files as inspected only after reading them +- allow files to appear in multiple clique waves +- do not delete rows from the manifest during refactoring +- use the same manifest again for the residual sweep + +### Clique Wave Checkpoint + +Plan and checkpoint every bounded read wave with this format. + +```text +clique_id: +purpose: +why_these_files_belong_together: +wave_size: + +files: +- path/to/file_a.rs +- path/to/file_b.rs + +checkpoint: +- raw suspects: +- duplication hypotheses: +- likely rereads: +- abstraction pressure: +``` + +Rules: + +- `wave_size` must never exceed `8` +- write a checkpoint into the `/tmp` worklog after every wave before reading more files +- keep the checkpoint terse and raw; do not inflate every suspect into a formal ledger row yet +- a file may appear in multiple cliques when duplication or boundary reasoning demands it +- split oversized conceptual groups into multiple related cliques rather than inflating one wave +- name the clique by the suspected relationship, not by arbitrary adjacency + +### Rejected Cluster + +Use this for suspect clusters that were noticed during coverage but did not earn formal ledger rows. + +```text +cluster_id: +kind: +sites: +- path/to/file_a.rs :: short note +- path/to/file_b.rs :: short note + +rejection_reason: +still_watch_for: +``` + +Good rejection reasons: + +- boundary-shaped transport code +- serialization or protocol surface where primitive form is correct +- cosmetic repetition without invariant pressure +- local-only pattern with no cross-site duplication +- abstraction name still too foggy to justify extraction + +Rules: + +- keep this short +- account for every non-promoted suspect cluster somewhere +- do not use rejected clusters to hide real actionable refactors + +### Promoted Ledger + +Use one row per promoted candidate site. + +```text +| row_id | path | symbol_or_site | kind | evidence | suspected_abstraction | duplication_cluster | confidence | decision | decision_reason | +|--------|------|----------------|------|----------|-----------------------|---------------------|------------|----------|-----------------| +| S001 | crates/foo/src/bar.rs | User.id: String | string | parsed, validated, and compared in 3 places | UserId newtype | id-handling-1 | high | refactor_now | domain identifier with repeated normalization | +| B001 | crates/foo/src/baz.rs | frobnicate(..., dry_run: bool) | bool | positional flag controls strategy | ExecutionMode enum | mode-flags-1 | high | refactor_now | bool hides a mode split | +| T001 | crates/foo/src/qux.rs | (start, end, step) | tuple | repeated destructuring across module boundary | RangeSpec struct | tuple-shapes-2 | medium | defer | local only today, but cluster suggests future extraction | +``` + +Allowed `kind` values: + +- `string` +- `bool` +- `tuple` +- `parameter_clump` +- `field_bundle` +- `duplicate_logic` +- `primitive_control_encoding` + +Allowed `confidence` values: + +- `high` +- `medium` +- `low` + +Allowed `decision` values: + +- `refactor_now` +- `defer` +- `false_positive` +- `needs_broader_design` + +Requirements: + +- `evidence` must name the concrete smell, not a vague feeling +- `suspected_abstraction` must be specific +- `duplication_cluster` must group related rows when applicable +- `decision_reason` must explain why the row did or did not graduate into an edit +- do not create rows for suspects that failed promotion; summarize those as rejected clusters instead + +## Embedded Adjudication Checklist + +Run this checklist for every ledger row. + +### Semantic Pressure + +- Does this primitive carry domain semantics rather than mere transport? +- Does it have validation, normalization, parsing, or formatting rules? +- Does the code rely on an implied finite value set? +- Would naming the concept clarify the surrounding code immediately? + +### Invariant Pressure + +- Are some values invalid but still representable today? +- Are correlated values allowed to drift apart? +- Does ordering matter only because a tuple hid the field names? +- Are impossible states currently encoded with primitive combinations? + +### Boundary Pressure + +- Does the primitive cross module or crate boundaries? +- Does it appear in public APIs, trait methods, or repeated call chains? +- Is the same primitive interpretation duplicated at multiple boundaries? + +### Duplication Pressure + +- Is the same parse, validate, normalize, compare, or convert logic repeated? +- Does the same field bundle move together repeatedly? +- Is there a repeated branch skeleton with only small local differences? + +### Refactor Readiness + +- Can a local type or helper eliminate repetition immediately? +- Will the fix cascade cleanly through references if renamed mechanically? +- Is there a natural owner module for the new abstraction? +- Does the change need a broader domain redesign first? + +### Decision Mapping + +Choose exactly one: + +- `refactor_now`: the abstraction is clear and locally actionable now +- `defer`: the smell is real but the present diff would be premature +- `false_positive`: the primitive is genuinely incidental or boundary-shaped +- `needs_broader_design`: the smell is real but the right abstraction spans a larger domain cut + +## Embedded Refactor Playbook + +Prefer these moves when the ledger supports them. + +### String + +- identifiers → newtypes +- finite tags / statuses / modes → enums +- validated textual concepts → smart constructors plus opaque wrappers +- repeated path / URL / email / locale handling → dedicated domain type or parser boundary + +### Bool + +- mode switches → enums +- policy flags → policy types +- correlated bool sets → state enum or config struct with named fields +- public boolean parameters → named option type unless the meaning is truly trivial + +### Tuple + +- cross-module tuples → named structs +- repeated destructuring → named fields +- semantically rich returns → domain object instead of positional packs + +### Parameter Clumps And Bundles + +- repeated argument groups → parameter object +- repeated local field packs → extracted struct +- repeated construction/update logic → dedicated constructor or helper module + +### Duplicate Logic + +- repeated validation → single constructor / validator +- repeated conversions → `From` / `TryFrom` / dedicated conversion function +- repeated branch skeletons → extracted helper, trait, or dispatch enum +- repeated formatting → single renderer / formatter + +### Rejection Criteria + +Do not introduce an abstraction merely because a primitive exists. + +Reject or defer when: + +- the primitive is truly incidental and carries no stable semantics +- the abstraction name is still foggy +- the same concept appears only once and shows no invariant pressure +- the code is at a serialization boundary where the primitive form is the correct external shape + +## Final Response + +Always include: + +- the `/tmp` worklog path +- manifest coverage summary +- clique-wave summary +- rejected-cluster summary +- promoted-ledger summary + +If you edited code, also include: + +- abstraction batches executed +- verification summary +- residual sweep summary + +If you did not edit code, include: + +- highest-value next moves + +## Hard Failure Modes + +- do not inspect only “important” files +- do not skip the `/tmp` worklog or keep checkpoint state only in chat +- do not read more than 8 files without a persisted checkpoint +- do not silently compact a wave because you feel you “basically got it” +- do not treat one clique as if it exhausts all duplication relationships +- do not promote everything into the formal ledger just to feel exhaustive +- do not drop non-promoted suspects on the floor; summarize them as rejected clusters +- do not jump into edits before the promoted ledger exists +- do not propose generic cleanup without row-level evidence +- do not treat Clippy output as a substitute for this pass diff --git a/skills/exterminate-slop/agents/openai.yaml b/skills/exterminate-slop/agents/openai.yaml new file mode 100644 index 0000000..ea5efab --- /dev/null +++ b/skills/exterminate-slop/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Exterminate Slop" + short_description: "Exhaustive Rust slop eradication" + default_prompt: "Use $exterminate-slop to perform a decision-per-row Rust subtree pass for primitive obsession, under-abstraction, and DRY violations." diff --git a/skills/rust-bootstrap/SKILL.md b/skills/rust-bootstrap/SKILL.md new file mode 100644 index 0000000..499bf04 --- /dev/null +++ b/skills/rust-bootstrap/SKILL.md @@ -0,0 +1,53 @@ +--- +name: rust-bootstrap +description: Bootstrap or retrofit industrial-grade Rust linting by using the `rust_starter` repo as the source of truth. Use when Codex needs to set up strict Rust lint/check posture from scratch in a new repo, or ratchet an existing Rust repo toward manifest-owned lint policy without blindly overwriting valid local exceptions or stricter existing rules. +--- + +# Rust Bootstrap + +Read [AGENTS.md](/home/main/programming/projects/rust_starter/AGENTS.md) first. + +Then choose exactly one surface. + +## Fresh Bootstrap + +Use this when the target repo is blank or when you are setting up Rust linting from scratch. + +Read: + +- [docs/bootstrap-fresh.md](/home/main/programming/projects/rust_starter/docs/bootstrap-fresh.md) +- [template/fresh](/home/main/programming/projects/rust_starter/template/fresh) + +Apply the template deliberately: + +- replace placeholder members, names, and version/toolchain values +- keep repo-wide policy in root `Cargo.toml` +- keep `clippy.toml` tiny or delete it +- keep runners thin and orchestration-only + +## Retrofit + +Use this when the target repo already has Rust linting or check scripts and needs tightening. + +Read: + +- [docs/bootstrap-retrofit.md](/home/main/programming/projects/rust_starter/docs/bootstrap-retrofit.md) +- [template/fresh](/home/main/programming/projects/rust_starter/template/fresh) +- [docs/rust-linting-proposal.md](/home/main/programming/projects/rust_starter/docs/rust-linting-proposal.md) + +Retrofit is diff-aware ratchet work: + +- do not paste the fresh template wholesale +- preserve stricter local policy +- preserve justified local exceptions +- move duplicated script or CI flags into manifest-owned policy +- delete duplicate policy copies only after the manifest is authoritative + +## Guardrails + +- Re-open the repo docs when details matter; do not rely on memory. +- Use [docs/rust-linting-proposal.md](/home/main/programming/projects/rust_starter/docs/rust-linting-proposal.md) for rationale, not as a paste target. +- If a target repo already exceeds the template in some area, keep the stricter local posture. +- If a target repo intentionally diverges, adapt the pattern instead of forcing uniformity. + +This skill is intentionally thin. The repo docs are the real payload. diff --git a/skills/rust-bootstrap/agents/openai.yaml b/skills/rust-bootstrap/agents/openai.yaml new file mode 100644 index 0000000..2dbdc72 --- /dev/null +++ b/skills/rust-bootstrap/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Rust Bootstrap" + short_description: "Bootstrap or tighten Rust linting" + default_prompt: "Use rust_starter to bootstrap or retrofit industrial-grade Rust linting." -- cgit v1.2.3