@bfirestone45/opencode-slop-review 0.5.0

package/skills/ai-slop-review/references/go.md

@@ -0,0 +1,401 @@
+# Go AI Slop Signals
+
+Language-specific signals for Go codebases. These supplement the universal signals
+in SKILL.md -- apply both.
+
+## What idiomatic Go looks like
+
+### At version 1.26+
+- `log/slog` for structured logging (stdlib since 1.21)
+- Range-over-func iterators (since 1.23)
+- Generic `slices`/`maps` functions over hand-rolled loops
+- `cmp.Or` for default values
+- Structured concurrency patterns with `errgroup`
+- `maps.Clone`, `slices.Concat`, `slices.Contains` etc.
+- New `http.ServeMux` with method-based routing (1.22+)
+
+### Stdlib preferences
+- Logging: `log/slog` over `log` or third-party loggers in new code
+- Slices: `slices` package over manual loops for search/sort/compare
+- Maps: `maps` package for clone/keys/values operations
+- HTTP: `http.NewServeMux` patterns with method routing (1.22+)
+- Testing: `testing.TB` helpers, `t.Cleanup` over deferred cleanup
+
+### Error handling convention
+- Always wrap errors with `fmt.Errorf("context: %w", err)`
+- Use `errors.Is`/`errors.As` for comparison, never string matching
+- Return errors to caller, do not `log.Fatal` in library or handler code
+- Sentinel errors for expected conditions, wrapped errors for unexpected
+
+### Project adaptation
+Before flagging any idiom violation, check if the project's idiom baseline uses a different convention. The baseline overrides these defaults.
+
+---
+
+## Priority order for Go
+
+1. Error handling -- this is where AI Go code fails most visibly
+2. Context propagation -- threading context.Context correctly
+3. Concurrency -- goroutine lifecycle, channel ownership, sync primitives
+4. Interface and type design -- idiomatic Go vs. Java-in-Go
+5. Testing -- table-driven tests, test helpers, subtests
+
+---
+
+## Error handling (highest priority)
+
+This is the single biggest tell in AI-generated Go. Humans who write Go daily internalize
+error handling patterns; AI frequently gets them subtly wrong.
+
+**Fatal/print instead of return:**
+```go
+// SLOP -- log.Fatal in a library or handler function
+if err != nil {
+    log.Fatal(err)
+}
+
+// SLOP -- fmt.Println for errors
+if err != nil {
+    fmt.Println("error:", err)
+}
+
+// IDIOMATIC -- return the error to the caller
+if err != nil {
+    return fmt.Errorf("fetching user %d: %w", id, err)
+}
+```
+
+**Missing error wrapping:**
+```go
+// SLOP -- no context, breaks error unwrapping
+if err != nil {
+    return err
+}
+
+// SLOP -- wraps but without %w, breaks errors.Is/As
+if err != nil {
+    return fmt.Errorf("failed to connect: %v", err)
+}
+
+// IDIOMATIC
+if err != nil {
+    return fmt.Errorf("connecting to %s: %w", addr, err)
+}
+```
+
+**String comparison on errors:**
+```go
+// SLOP
+if err.Error() == "not found" {
+    // ...
+}
+
+// IDIOMATIC
+if errors.Is(err, ErrNotFound) {
+    // ...
+}
+```
+
+**Swallowed errors:**
+```go
+// SLOP -- error silently discarded
+result, _ := doSomething()
+```
+
+---
+
+## Context propagation
+
+**Missing context.Context in signatures:**
+```go
+// SLOP -- no context parameter
+func FetchUser(id int) (*User, error) {
+
+// IDIOMATIC -- context is first parameter
+func FetchUser(ctx context.Context, id int) (*User, error) {
+```
+
+**context.Background() mid-callstack:**
+```go
+// SLOP -- creates a new root context deep in the call chain
+func (s *Service) Process(data []byte) error {
+    ctx := context.Background()  // should come from caller
+    return s.store.Save(ctx, data)
+}
+```
+
+**No cancellation handling:**
+```go
+// SLOP -- ignores context cancellation
+func worker(ctx context.Context) {
+    for {
+        doWork()
+        time.Sleep(time.Second)
+    }
+}
+
+// IDIOMATIC
+func worker(ctx context.Context) {
+    for {
+        select {
+        case <-ctx.Done():
+            return
+        default:
+            doWork()
+        }
+        select {
+        case <-ctx.Done():
+            return
+        case <-time.After(time.Second):
+        }
+    }
+}
+```
+
+---
+
+## Concurrency
+
+**Goroutine leaks -- no cancellation path:**
+```go
+// SLOP -- goroutine runs forever, no way to stop it
+go func() {
+    for {
+        process(queue)
+    }
+}()
+
+// IDIOMATIC -- cancellable via context
+go func() {
+    for {
+        select {
+        case <-ctx.Done():
+            return
+        case item := <-queue:
+            process(item)
+        }
+    }
+}()
+```
+
+**Channel ownership confusion:**
+- Channel created by one goroutine, closed by another (race condition risk)
+- Channel created but never closed (goroutines blocked on range forever)
+- Unbuffered channel used where buffered is needed (deadlock risk)
+
+**sync.Mutex overuse:**
+```go
+// SLOP -- mutex protecting a counter that should use atomic
+var mu sync.Mutex
+var count int
+
+// BETTER
+var count atomic.Int64
+```
+
+**sync.Mutex where single-goroutine ownership works:**
+If a struct is only accessed from one goroutine, it does not need a mutex.
+AI often adds mutexes "just in case" -- a strong slop signal.
+
+---
+
+## Type and interface misuse
+
+**Interface defined in the wrong package:**
+```go
+// SLOP -- interface defined next to its implementation
+// (Go convention: interfaces belong in the consuming package)
+type UserStore interface {
+    GetUser(ctx context.Context, id int) (*User, error)
+}
+
+type userStore struct { ... }
+func (s *userStore) GetUser(...) { ... }
+```
+
+**Premature interface:**
+```go
+// SLOP -- interface with exactly one implementation and one consumer
+type Processor interface {
+    Process(data []byte) error
+}
+```
+
+**`interface{}` instead of `any`, or `any` instead of generics:**
+```go
+// SLOP -- interface{} is an alias for any since 1.18; using the old syntax is dated
+func Contains(slice []interface{}, item interface{}) bool {
+
+// STILL SLOP at 1.26+ -- hand-rolled contains; use slices.Contains
+func Contains[T comparable](slice []T, item T) bool {
+
+// IDIOMATIC at 1.26+ -- use the stdlib slices package
+import "slices"
+found := slices.Contains(slice, item)
+```
+
+**Value receiver on mutating method:**
+```go
+// SLOP -- s is a copy, mutation is lost
+func (s Service) SetTimeout(d time.Duration) {
+    s.timeout = d
+}
+
+// CORRECT
+func (s *Service) SetTimeout(d time.Duration) {
+    s.timeout = d
+}
+```
+
+---
+
+## Other Go idioms
+
+**defer inside a loop:**
+```go
+// SLOP -- defers accumulate until function return, not loop iteration
+for _, f := range files {
+    fd, _ := os.Open(f)
+    defer fd.Close()  // all closes happen at function exit
+}
+
+// CORRECT -- extract to helper or close explicitly
+for _, f := range files {
+    if err := processFile(f); err != nil {
+        return err
+    }
+}
+```
+
+**Hand-rolled slice/map operations (1.26+):**
+```go
+// SLOP -- manual contains check
+found := false
+for _, v := range items {
+    if v == target {
+        found = true
+        break
+    }
+}
+
+// IDIOMATIC at 1.26+ -- use slices package
+found := slices.Contains(items, target)
+
+// SLOP -- manual sort
+sort.Slice(items, func(i, j int) bool { return items[i] < items[j] })
+
+// IDIOMATIC at 1.26+
+slices.Sort(items)
+
+// SLOP -- manual map key collection
+keys := make([]string, 0, len(m))
+for k := range m {
+    keys = append(keys, k)
+}
+
+// IDIOMATIC at 1.26+
+keys := slices.Collect(maps.Keys(m))
+```
+
+**Old-style logging instead of slog (1.26+):**
+```go
+// SLOP in new code -- unstructured logging
+log.Printf("user %d logged in from %s", id, ip)
+
+// IDIOMATIC at 1.26+ -- structured logging with log/slog
+slog.Info("user logged in", "user_id", id, "ip", ip)
+```
+
+**Default value chains without cmp.Or (1.26+):**
+```go
+// SLOP -- verbose conditional default
+port := os.Getenv("PORT")
+if port == "" {
+    port = "8080"
+}
+
+// IDIOMATIC at 1.26+
+port := cmp.Or(os.Getenv("PORT"), "8080")
+```
+
+**HTTP server without timeouts:**
+```go
+// SLOP
+http.ListenAndServe(":8080", handler)
+
+// IDIOMATIC at 1.26+ -- use method-based routing on ServeMux
+mux := http.NewServeMux()
+mux.HandleFunc("GET /users/{id}", getUser)
+mux.HandleFunc("POST /users", createUser)
+
+srv := &http.Server{
+    Addr:         ":8080",
+    Handler:      mux,
+    ReadTimeout:  15 * time.Second,
+    WriteTimeout: 15 * time.Second,
+    IdleTimeout:  60 * time.Second,
+}
+srv.ListenAndServe()
+```
+
+**Global singletons via init():**
+```go
+// SLOP
+var db *sql.DB
+
+func init() {
+    var err error
+    db, err = sql.Open("postgres", os.Getenv("DATABASE_URL"))
+    if err != nil {
+        log.Fatal(err)
+    }
+}
+
+// BETTER -- dependency injection, initialized in main()
+```
+
+---
+
+## Security signals
+
+- SQL via `fmt.Sprintf` instead of parameterized queries (`db.Query(query, args...)`)
+- `http.ListenAndServe` with no TLS and no reverse proxy documented
+- `os/exec.Command` with user input concatenated into the command string
+- `http.Get` / `http.Post` with no timeout (uses `http.DefaultClient` which has no timeout)
+
+---
+
+## Go-specific test signals
+
+**Not using table-driven tests** -- the canonical Go testing pattern:
+```go
+// SLOP -- separate test functions for each case
+func TestParseValid(t *testing.T) { ... }
+func TestParseEmpty(t *testing.T) { ... }
+func TestParseInvalid(t *testing.T) { ... }
+
+// IDIOMATIC
+func TestParse(t *testing.T) {
+    tests := []struct {
+        name    string
+        input   string
+        want    Result
+        wantErr bool
+    }{
+        {"valid", "good", Result{...}, false},
+        {"empty", "", Result{}, true},
+        {"invalid", "bad", Result{}, true},
+    }
+    for _, tt := range tests {
+        t.Run(tt.name, func(t *testing.T) {
+            got, err := Parse(tt.input)
+            // ...
+        })
+    }
+}
+```
+
+- `t.Log` or `fmt.Println` instead of assertion -- test always passes
+- No `t.Helper()` on test helper functions (error locations point to helper, not caller)
+- No `t.Parallel()` on tests that are safe to parallelize
+- `testify` used in a codebase that uses stdlib `testing` everywhere else (or vice versa)

package/skills/ai-slop-review/references/python.md

@@ -0,0 +1,263 @@
+# Python AI Slop Signals
+
+Language-specific signals for Python codebases. These supplement the universal signals
+in SKILL.md -- apply both.
+
+## What idiomatic Python looks like
+
+### At version 3.13+
+
+- Union types: `X | None` not `Optional[X]`, `X | Y` not `Union[X, Y]`
+- Built-in generics: `list[str]` not `typing.List[str]`, `dict[str, int]` not `typing.Dict[str, int]`
+- `@deprecated` decorator from `warnings`
+- `StrEnum` for string enumerations (stdlib since 3.11)
+- `tomllib` for TOML parsing (stdlib since 3.11)
+- `ExceptionGroup` and `except*` for concurrent error handling
+- Walrus operator `:=` where it reduces duplication
+- Per-interpreter GIL / free-threaded mode awareness
+
+### Stdlib preferences
+
+- Filesystem: `pathlib.Path` over `os.path` in new code
+- Caching: `functools.cache` (3.9+) or `lru_cache` over hand-rolled memoization
+- Data containers: `dataclasses` or `NamedTuple` over plain dicts for structured data
+- Iteration: `itertools` (product, chain, groupby) over nested manual loops
+- Context managers: `contextlib.contextmanager` over manual `__enter__`/`__exit__`
+- Temporary files: `tempfile` with context managers, never hardcoded paths
+
+### Error handling convention
+
+- Specific exceptions over bare `except Exception`
+- `raise X from e` to preserve tracebacks
+- EAFP for duck typing, LBYL for everything else
+- `.get()` over try/except KeyError for dict access
+
+### Project adaptation
+
+Before flagging any idiom violation, check if the project's idiom baseline (from Step 0)
+uses a different convention. The baseline overrides these defaults.
+
+---
+
+## Priority order for Python
+
+1. Error handling -- bare excepts, swallowed errors, exceptions for control flow
+2. Idiomatic Python -- are they writing Python or Java-in-Python?
+3. Type system usage -- modern typing vs. no types vs. over-typed
+4. Async correctness -- if async is used, is it used properly?
+5. Security -- eval, exec, shell injection, pickle
+
+---
+
+## Error handling
+
+**Bare exception swallowing** -- the single most common AI Python tell:
+```python
+# SLOP: silent failure
+try:
+    result = do_thing()
+except Exception:
+    pass
+
+# SLOP: catching too broadly then re-raising generically
+try:
+    data = parse(raw)
+except Exception as e:
+    raise ValueError(f"Parse failed: {e}")  # loses traceback, catches too much
+
+# BETTER: specific exceptions, context preserved
+try:
+    data = parse(raw)
+except json.JSONDecodeError as e:
+    raise ParseError(f"Invalid JSON at position {e.pos}") from e
+```
+
+**Exceptions for control flow** -- using try/except where a conditional or `.get()` works:
+```python
+# SLOP
+try:
+    value = data["key"]
+except KeyError:
+    value = default
+
+# IDIOMATIC
+value = data.get("key", default)
+```
+
+**Over-defensive error handling** -- wrapping operations that cannot fail:
+```python
+# SLOP: len() on a list cannot raise
+try:
+    count = len(items)
+except Exception:
+    count = 0
+```
+
+---
+
+## Classic footguns AI still produces
+
+**Mutable default arguments:**
+```python
+# SLOP -- the list is shared across all calls
+def append_to(item, target=[]):
+    target.append(item)
+    return target
+
+# CORRECT
+def append_to(item, target=None):
+    if target is None:
+        target = []
+    target.append(item)
+    return target
+```
+
+**Global state as a crutch:**
+```python
+# SLOP
+_cache = {}
+def get_user(user_id):
+    global _cache
+    if user_id not in _cache:
+        _cache[user_id] = fetch(user_id)
+    return _cache[user_id]
+
+# BETTER: encapsulate state, or use functools.lru_cache
+```
+
+**Resources without context managers:**
+```python
+# SLOP
+f = open("data.csv")
+data = f.read()
+f.close()
+
+# IDIOMATIC
+with open("data.csv") as f:
+    data = f.read()
+```
+
+---
+
+## Type and style signals
+
+**Missing or outdated type hints** -- with 3.13+ as the minimum floor, these are all
+non-idiomatic and should be flagged:
+- No type hints at all on function signatures
+- `Optional[X]` instead of `X | None` -- the `Optional` alias is legacy
+- `typing.List`, `typing.Dict`, `typing.Tuple`, `typing.Set` instead of `list`, `dict`, `tuple`, `set` -- built-in generics have been available since 3.9
+- `typing.Union[X, Y]` instead of `X | Y` -- the pipe syntax has been available since 3.10
+- Importing from `typing` for constructs that now live in the stdlib (e.g., `typing.NamedTuple` when `typing` import is the only reason)
+
+**isinstance chains instead of structural typing:**
+```python
+# SLOP
+def process(item):
+    if isinstance(item, str):
+        return handle_str(item)
+    elif isinstance(item, int):
+        return handle_int(item)
+    elif isinstance(item, list):
+        return handle_list(item)
+
+# BETTER: Protocol, singledispatch, or rethink the interface
+```
+
+**Avoiding the stdlib:**
+- `os.path.join` instead of `pathlib.Path` in new code
+- Manual iteration instead of `itertools` (product, chain, groupby)
+- Hand-rolled memoization instead of `functools.lru_cache` or `cache`
+- Manual context managers instead of `contextlib.contextmanager`
+- Custom data containers instead of `dataclasses` or `NamedTuple`
+- `collections.OrderedDict` in Python 3.7+ (regular dicts are ordered)
+
+**`*args, **kwargs` on internal functions:**
+```python
+# SLOP -- lazy interface design, impossible to type-check
+def create_user(*args, **kwargs):
+    return User(*args, **kwargs)
+
+# BETTER: explicit parameters with types
+def create_user(name: str, email: str, role: Role = Role.USER) -> User:
+    return User(name=name, email=email, role=role)
+```
+
+---
+
+## Async signals
+
+**Blocking calls in async code** -- the most insidious AI async mistake:
+```python
+# SLOP -- requests blocks the event loop
+async def fetch_data(url):
+    response = requests.get(url)  # BLOCKS
+    return response.json()
+
+# SLOP -- time.sleep blocks the event loop
+async def poll():
+    while True:
+        await check()
+        time.sleep(5)  # BLOCKS -- should be await asyncio.sleep(5)
+```
+
+**Deprecated async patterns:**
+```python
+# SLOP (deprecated since 3.10)
+loop = asyncio.get_event_loop()
+loop.run_until_complete(main())
+
+# IDIOMATIC
+asyncio.run(main())
+```
+
+**Missing await** -- code runs but the coroutine never executes:
+```python
+# SLOP -- result is a coroutine object, not the actual result
+async def process():
+    result = fetch_data()  # missing await
+    return result
+```
+
+---
+
+## Security signals
+
+These are serious -- flag as Critical regardless of other context:
+
+- `eval()` or `exec()` on any external or user-influenced input
+- Shell commands with `shell=True` and string formatting for the command
+- `pickle.loads()` / `pickle.load()` on untrusted data
+- Secrets in default argument values, module-level constants, or committed `.env` files
+- `yaml.load()` without `Loader=SafeLoader` (allows arbitrary code execution)
+- SQL built via f-strings or `.format()` instead of parameterized queries
+- `hashlib.md5()` or `hashlib.sha1()` for security purposes (use sha256+)
+- `random` module for security-sensitive values (use `secrets` module)
+
+---
+
+## Python-specific test signals
+
+- `unittest.TestCase` subclasses in a project that uses `pytest` everywhere else
+- `mock.patch` on everything -- tests that mock the entire world test nothing
+- No `parametrize` / `params` where the function has obvious input variations
+- `assert result is not None` as the only assertion (proves nothing about correctness)
+- Test files that import and call the function but do not assert meaningful behavior
+- `conftest.py` with fixtures that do too much setup (hiding test complexity)
+- No `tmp_path` or `tmp_path_factory` -- tests writing to fixed filesystem paths
+
+---
+
+## Framework-specific notes
+
+Be aware that some frameworks have conventions that look unusual:
+
+- **Dagster:** `@asset` decorators, `@op`, resource injection via type annotations,
+  `MaterializeResult` returns. These are framework conventions, not slop.
+- **Django:** Class-based views, `Meta` inner classes, `models.Manager` subclasses.
+- **FastAPI:** `Depends()` injection, Pydantic models for validation, `async def` route
+  handlers that may legitimately use sync ORM calls via `run_in_executor`.
+- **SQLAlchemy:** `Column()`, `relationship()`, declarative base patterns.
+- **Pydantic:** `model_validator`, `field_validator`, `ConfigDict` -- these are idiomatic.
+
+Do not flag framework-conventional patterns. Do flag when framework patterns are mixed
+incorrectly (e.g., raw SQL in a project that uses SQLAlchemy ORM everywhere else).