diff options
Diffstat (limited to 'skills/exterminate-slop/references')
4 files changed, 166 insertions, 0 deletions
diff --git a/skills/exterminate-slop/references/languages/java.md b/skills/exterminate-slop/references/languages/java.md new file mode 100644 index 0000000..550dc1b --- /dev/null +++ b/skills/exterminate-slop/references/languages/java.md @@ -0,0 +1,37 @@ +# Java + +Use this note for Java source scopes. It sharpens the generic extermination pass; it is not a style guide. + +## Manifest + +Source files are `*.java` under the requested subtree. Exclude generated sources, vendored code, build output, fixtures, snapshots, and annotation-processor products unless the user explicitly includes them. Include tests when they expose duplicated construction, domain shape, or behavior-preservation evidence. + +## Navigation + +Use the project's Java language server, IDE metadata, Maven/Gradle graph, and textual search together. Anchor from live use sites: constructor calls, factory methods, getters/setters, switch sites, serialization boundaries, mapper layers, repository methods, validator calls, and DTO/domain conversions. Java's indirection is often architectural sediment; chase references until the real owner is visible. + +## Modernization Posture + +Do not preserve legacy Java style as a virtue. Use the latest Java version supported by the project unsparingly, and treat unjustified old language-level pins as slop to question. Prefer records, sealed hierarchies, switch expressions, pattern matching, compact constructors, local type inference, immutable collections, and modern standard-library APIs when they collapse boilerplate or make states explicit. If the build cannot move to the current language level, record that constraint instead of silently writing Java 8-shaped code. + +## Deslopping Moves + +Move semantics out of strings, maps, nulls, telescoping constructors, and mutable JavaBeans. Domain data with stable identity or invariants wants records, value objects, enums, sealed interfaces, or small final classes with validating constructors. Finite state spaces want enums or sealed hierarchies, not strings, integer codes, nullable fields, or parallel booleans. Repeated argument groups and DTO shuttles want named domain carriers. + +Collapse repeated parse, validate, normalize, map, format, authorize, query, and error-shaping logic into one owner. Prefer total constructors/factories, enum behavior, sealed dispatch, shared mappers, and narrow modules over duplicated service-layer folklore. Delete getter/setter husks, pointless adapters, ceremonial builders, redundant DTO twins, and compatibility layers unless an external boundary truly requires them. + +Bias toward code volume reduction when it increases semantic density. A record replacing a class wall, a sealed hierarchy replacing flag fields, or one domain mapper replacing five hand-written conversions is the correct direction. Do not mistake verbosity for enterprise seriousness. + +## Java-Specific Suspects + +Scrutinize `String` identifiers/statuses/types, `Map<String, Object>`, raw or weak generics, nullable fields, `Optional` fields, boolean constructor parameters, Lombok masking structure, mutable bean DTOs, anemic service methods, repeated mapper code, exception wrapping boilerplate, duplicated validation annotations plus manual checks, and switch/if chains over the same discriminator. + +Scrutinize boundaries separately. JSON, SQL, Kafka, REST, GraphQL, CLI, and legacy API surfaces may need primitive or DTO shapes externally, but convert to domain types at the boundary. Do not let transport classes become the internal model. + +## Verification + +After edits, run the narrowest meaningful Maven or Gradle compile/test command for the touched module, then widen if the abstraction crosses modules. Include formatter/checkstyle/spotbugs/error-prone/nullness checks when they are part of the repo contract, but never treat them as a substitute for the extermination ledger. + +## Avoid + +Do not write new Java in a legacy idiom unless the toolchain forces it. Do not preserve mutability, nullability, beans, builders, or DTO duplication by default. Do not add abstraction whose invariant is imaginary. Do not leave five verbose repetitions because the one modern representation feels unfamiliar. diff --git a/skills/exterminate-slop/references/languages/python.md b/skills/exterminate-slop/references/languages/python.md new file mode 100644 index 0000000..023f2d6 --- /dev/null +++ b/skills/exterminate-slop/references/languages/python.md @@ -0,0 +1,49 @@ +# Python + +Use this note for Python source scopes. It sharpens the generic extermination pass; it is not a style guide. + +## Manifest + +Source files are `*.py` under the requested subtree. Exclude generated files, vendored code, build output, virtualenvs, fixtures, snapshots, notebooks, and migration dumps unless the user explicitly includes them. Include tests when they expose duplicated construction, domain shape, or behavior-preservation evidence. + +## Navigation + +Use `rg`, the project's type checker, tests, and runtime entrypoints together. Python's semantic truth is often distributed across constructors, call sites, fixtures, protocols, and serialization edges; chase live construction and consumption paths before deciding an abstraction. Track import cycles and package boundaries before moving code. + +## Static Posture + +Pretend Python is statically compiled. Lean on precise annotations, `mypy`/`pyright` or `ty`, `typing` machinery, `Protocol`, `NewType`, `Literal`, `Final`, `TypeAlias`, generics, overloads, dataclasses, enums, and exhaustive local structure. Runtime validation is not a virtue by default; it is often defensive bloat. Add runtime checks only at real trust boundaries or where the program already depends on dynamic validation. + +## Deslopping Moves + +Move semantics out of anonymous primitives and into named static structure. Strings used as identifiers, slugs, modes, statuses, units, paths, URLs, and external keys should become `NewType`, `Literal` unions, enums, dataclasses, type aliases, or small value objects according to the strength of the invariant. Dict soup and tuple soup should become typed records: dataclasses, `NamedTuple`, `TypedDict` at transport edges, or explicit domain objects. + +Collapse repeated parse, normalize, default-fill, render, serialize, authorize, query, and error-shaping logic into one owner. Prefer type-directed constructors, pure conversion functions, protocols, table-driven dispatch, and explicit domain modules over repeated "simple" helper code. Centralize boundary coercion; inside the program, trust the typed representation instead of rechecking it everywhere. + +Bias toward code volume reduction when it increases semantic density. Delete defensive glue made obsolete by types, duplicate fixture builders, repeated `if key in dict` ladders, parallel lists, ceremonial wrappers, scattered casts, redundant `assert x is not None`, and sprawling optional bags. A compact typed representation is better than ten "safe" guards synchronized by anxiety. + +## Fail Fast + +Aggressively remove checks that static structure, construction path, or local dominance already proves unnecessary. Purge ceremony around irrecoverable errors. If missing data means the program is broken, crash at the point of contradiction instead of inventing a worthless dummy. Do not call `.get(key, default)` when the default has no honest semantics. Do not catch exceptions merely to rewrap, log-and-limp, return `None`, or preserve a doomed control path. Fail early, loudly, and close to the violated invariant. + +## Python-Specific Suspects + +Scrutinize `dict[str, Any]`, untyped dicts, tuple returns, string tags, magic constants, `None` sentinels, boolean flags, loose `**kwargs`, repeated `TypedDict` shapes, dataclasses with many optionals, scattered `cast`, ad-hoc path/string handling, repeated fixture factories, and `isinstance` chains over the same latent variant. + +Scrutinize boundaries separately. JSON, SQL rows, environment variables, argparse, HTTP payloads, pandas frames, and third-party SDK responses may arrive as primitives or dicts, but boundary coercion should happen once. Do not drag runtime paranoia into already-typed internal code. + +## Modernization Posture + +Default to zero backward compatibility with older Python versions. If the review is global in scope, and dependency constraints do not forbid it, upgrade the project to the latest viable Python version. If it can be upgraded, it should be. + +Use modern Python features when the project permits them: `dataclass(slots=True, frozen=True)`, structural pattern matching, `StrEnum`, `typing` improvements, `Protocol`, `Self`, `Literal`, precise generics, `|` unions, `TypeGuard`/`TypeIs`, and `Final`. Prefer stdlib and static-analysis-visible constructs. + +Astral tooling is mandatory doctrine: `uv`, `ruff`, and `ty` should be installed or introduced unless the repo has an explicit incompatible toolchain reason. Use Ruff's `UP` rules to modernize syntax and erase compatibility husks. Add dependencies only when they delete more machinery than they introduce. + +## Verification + +After edits, run the narrowest meaningful tests for the touched surface, then widen if the abstraction crosses packages. Run the project's formatter, linter, and type checker when present. Treat `ty`/mypy/pyright, Ruff, and tests as evidence, not as a substitute for the extermination ledger. + +## Avoid + +Do not launder defensive programming as rigor. Do not preserve dict soup because "Python is dynamic." Do not keep `None`/bool/string encodings when a named static representation would compress the truth. Do not create baroque class hierarchies without invariant pressure. Do not leave five small helpers when one typed domain object would annihilate them. diff --git a/skills/exterminate-slop/references/languages/rust.md b/skills/exterminate-slop/references/languages/rust.md new file mode 100644 index 0000000..89717ce --- /dev/null +++ b/skills/exterminate-slop/references/languages/rust.md @@ -0,0 +1,33 @@ +# Rust + +Use this note for Rust source scopes. It sharpens the generic extermination pass; it is not a style guide. + +## Manifest + +Source files are `*.rs` under the requested subtree. Exclude generated, vendored, target, fixture, snapshot, and build-output files unless the user explicitly includes them. Include tests when they encode domain shape, duplicated construction, or behavior-preservation evidence. + +## Navigation + +Use `rust_analyzer` aggressively. Anchor from live use sites before jumping through declarations: field access, constructor call, enum match, trait method call, conversion site, parser call, or repeated builder/update path. Use references and rename feasibility to understand whether an abstraction can be moved mechanically. Text search is for manifesting and cross-checking; semantic navigation is for decisions. + +## Deslopping Moves + +Prefer type-level compression over local explanation. If a primitive carries semantics, replace it with a domain type: newtype, enum, value object, typestate, phase-specific struct, trait, generic, const-generic shape, or smart constructor. Closed string worlds become enums. Validated identifiers and tokens become opaque wrappers. Tuple packs and repeated field bundles become named domain objects. Repeated `Option`/`bool` combinations become state types that make invalid states unrepresentable. + +Treat DRY as stronger than YAGNI. Repeated parse, validate, normalize, render, patch, convert, query, or error-shaping logic should collapse into one owner. Prefer `From`/`TryFrom`, dedicated constructors, extension traits, local algebra, iterator transforms, and small modules with a clear semantic center. Macros are legitimate when they enforce uniformity, remove boilerplate, or keep hot code compact. + +Bias toward code volume reduction when it increases semantic density. Delete dead compatibility shims, redundant wrappers, ceremonial intermediates, repeated guards made obsolete by types, and "simple" structs that only scatter one concept across context. Overabstraction is not a crime; weak abstraction is. A powerful abstraction is acceptable when it compresses a real invariant or repeated skeleton. + +## Rust-Specific Suspects + +Scrutinize `String`, `&str`, `PathBuf`, raw integers, bool flags, public tuple returns, builder structs full of `Option`, enums mirrored by strings, repeated `match` skeletons, repeated `clone`/conversion glue, parallel vectors/maps, and hand-rolled state machines encoded as primitive fields. + +Scrutinize generic transport boundaries separately. Serialization, database rows, CLI args, wire protocols, and FFI may need primitive shapes externally, but the primitive must be quarantined at the boundary and converted into domain types immediately. + +## Verification + +After edits, run `cargo fmt` and the narrowest meaningful Rust checks for the touched crates, then widen if the abstraction crosses crate boundaries. Prefer existing project commands. Use Clippy when it is part of the repo contract, but never treat Clippy as a substitute for the extermination ledger. + +## Avoid + +Do not write Rust like Python with types. Do not preserve public API compatibility unless requested. Do not add abstraction whose name is foggy or whose invariant is imaginary. Do not reject a correct abstraction merely because it looks advanced. Do not leave five concrete repetitions because one generic/macro/trait solution feels "less readable." diff --git a/skills/exterminate-slop/references/languages/typescript.md b/skills/exterminate-slop/references/languages/typescript.md new file mode 100644 index 0000000..85d18ce --- /dev/null +++ b/skills/exterminate-slop/references/languages/typescript.md @@ -0,0 +1,47 @@ +# TypeScript + +Use this note for TypeScript source scopes. It sharpens the generic extermination pass; it is not a style guide. + +## Manifest + +Source files are `*.ts`, `*.tsx`, `*.mts`, and `*.cts` under the requested subtree. Exclude generated clients, vendored code, build output, coverage, snapshots, fixtures, declaration output, and `node_modules` unless the user explicitly includes them. Include tests when they expose duplicated construction, domain shape, state variants, or behavior-preservation evidence. + +## Navigation + +Use `rg`, the TypeScript language server, `tsconfig` project references, package/workspace metadata, and the project's typecheck command together. Anchor from live use sites: component props, function calls, reducers, action dispatches, API adapters, parser/coercion sites, map/index access, switch statements, and DTO/domain conversions. Trace both runtime flow and type flow; TypeScript slop often hides in the gap between them. + +## Static Posture + +Treat TypeScript as a real static language. Lean on `strict`, `satisfies`, `as const`, discriminated unions, branded/opaque types, `readonly`, `never` exhaustiveness, template literal types, precise generics, `unknown` at trust boundaries, and exact object shapes. Do not use runtime checks to compensate for avoidable type vagueness. Parse or coerce once at a real boundary, then trust the typed internal representation. + +## Deslopping Moves + +Move semantics out of strings, loose objects, optional bags, boolean props, and `any`. Identifiers, slugs, paths, statuses, modes, units, event names, cache keys, and route names should become literal unions, branded types, typed records, discriminated variants, or domain modules. Repeated prop bundles, config bags, request shapes, reducer states, and tuple-ish arrays should become named types with closed variants where possible. + +Collapse repeated normalize, map, render, serialize, authorize, query, and error-shaping logic into one owner. Prefer total conversion functions, discriminated dispatch, typed lookup tables, exhaustive switches, and small domain modules over repeated "simple" object manipulation. Use `Record<K, V>` only when `K` is a real finite keyspace; do not use it as camouflage for map soup. + +Bias toward code volume reduction when it increases semantic density. Delete duplicate adapters, prop plumbing, action boilerplate, useless wrappers, scattered casts, repeated defaulting, optional chaining over required values, and compatibility husks. A compact union plus exhaustive dispatch is better than five nullable fields and defensive branches. + +## Fail Fast + +Aggressively remove checks that the type system, construction path, or local dominance already proves unnecessary. Do not write `foo?.bar ?? dummy` when `foo` must exist and the dummy has no honest semantics. Do not catch merely to rewrap, return `undefined`, or limp onward. If a value contradicts the typed model, fail early and close to the violated invariant. + +## TypeScript-Specific Suspects + +Scrutinize `any`, broad `unknown` that never narrows, `object`, `Record<string, ...>`, string tags, magic constants, nullable fields, boolean prop clusters, optional-heavy interfaces, index signatures, scattered `as` casts, non-null assertions, tuple returns, prop spreading, action string duplication, parallel arrays/maps, and `switch`/`if` chains over the same discriminator. + +Scrutinize boundaries separately. JSON, HTTP, GraphQL, localStorage, env vars, CLI input, database rows, and third-party SDK payloads may arrive untyped, but coercion should happen once. Do not let transport shape become business shape. + +## Modernization Posture + +Default to zero backward compatibility with old TypeScript, Node, bundler, or browser targets unless the repo has an explicit constraint. If the review is global in scope and dependency/runtime constraints do not forbid it, upgrade to the latest viable TypeScript and modernize the `tsconfig`. If it can be upgraded, it should be. + +Prefer modern TS syntax and strictness: `satisfies`, const type parameters when useful, `exactOptionalPropertyTypes`, `noUncheckedIndexedAccess`, `noImplicitOverride`, `verbatimModuleSyntax`, modern module resolution, and current ECMAScript targets. Use the project's formatter/linter; do not add tool sprawl unless it deletes more machinery than it introduces. + +## Verification + +After edits, run the narrowest meaningful typecheck and tests for the touched package, then widen if the abstraction crosses package boundaries. Run formatter/linter/build commands when they are part of the repo contract. Treat typecheck, lint, and tests as evidence, not as a substitute for the extermination ledger. + +## Avoid + +Do not preserve `any` as convenience. Do not replace domain modeling with defensive optional chaining. Do not leave stringly action/status/event systems because they are familiar. Do not keep public optional bags when a closed union would state the truth. Do not create class hierarchies without invariant pressure. Do not leave five object-shuffling helpers when one typed representation would annihilate them. |