@diottodev/runic 1.0.0 → 1.1.0

package/engineering-team/skills/code-reviewer/languages/c.md

@@ -0,0 +1,103 @@
+---
+language: c
+extensions: [".c", ".h"]
+---
+
+# C — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only C-specific rules and idioms.
+
+---
+
+## PR Analyzer — C Risk Signals
+
+- `printf` / debug `fprintf(stderr, ...)` statements left in production code
+- `// TODO` / `// FIXME` comments near memory management code — high risk
+- Disabled compiler warnings (`#pragma GCC diagnostic ignore`, `-w` flags in Makefile)
+- Hardcoded credentials or keys in source
+- Use of banned functions: `gets`, `strcpy`, `strcat`, `sprintf`, `scanf` without width limits
+
+---
+
+## Code Quality — C Checks
+
+- Functions longer than 50 lines — C functions tend to grow organically and become hard to reason about
+- Missing `NULL` check after `malloc` / `calloc` / `realloc`
+- Return value of functions ignored without explicit `(void)` cast
+- Global mutable state used across translation units without clear ownership
+- Magic numbers without `#define` or `const` — especially sizes and offsets
+- Mixed `malloc`/`free` ownership — unclear which caller is responsible for freeing
+
+---
+
+## Security
+
+- Flag `gets()` — no bounds checking, always a buffer overflow; replace with `fgets()`
+- Flag `strcpy()` / `strcat()` — use `strncpy()` / `strncat()` with explicit size, or `strlcpy()` / `strlcat()`
+- Flag `sprintf()` — use `snprintf()` with explicit buffer size
+- Flag `scanf("%s", buf)` without a width specifier — unbounded read
+- Flag `strlen()` result used as a signed integer — potential truncation on 64-bit
+- Flag user-controlled data used as a format string (`printf(user_input)`) — format string attack
+- Flag integer arithmetic used as array index without bounds check
+- Flag signed integer overflow — undefined behavior in C
+
+---
+
+## Async / Concurrency
+
+- Flag shared global or `static` variables accessed from multiple threads without a mutex or `_Atomic`
+- Flag `pthread_mutex_t` / `sem_t` not initialized before use
+- Flag signal handlers that call non-async-signal-safe functions (`malloc`, `printf`, etc.)
+- Flag `volatile` used as a substitute for proper synchronization — it is not sufficient
+- Flag lock acquisition order inconsistency across call sites — deadlock risk
+
+---
+
+## Resource Management
+
+- Flag every `malloc` / `calloc` / `realloc` path — verify a matching `free` exists on all exit paths
+- Flag `fopen` without a matching `fclose` on all paths including error paths
+- Flag `dup` / `socket` / `open` file descriptors not closed on all paths
+- Flag stack-allocated VLAs (variable-length arrays) of unbounded size — stack overflow risk
+- Flag `realloc` return value assigned directly to the source pointer — leaks on failure
+
+---
+
+## Exception Handling
+
+- Flag ignored return values from `malloc`, `fopen`, `read`, `write`, `close` — all can fail
+- Flag `errno` checked after a function that doesn't set it, or not checked immediately after one that does
+- Flag `perror` / `strerror` as the sole error handling in library code — propagate errors to callers
+- Flag functions that return `-1` on error without documenting which `errno` values are possible
+- Flag `assert()` used for runtime error handling — disabled by `NDEBUG` in production builds
+
+---
+
+## Performance
+
+- Flag `strlen()` called repeatedly on the same string in a loop — cache the result
+- Flag unnecessary copies of large structs passed by value — pass by pointer
+- Flag `memcpy` / `memset` on overlapping regions — use `memmove` for overlapping
+- Flag repeated heap allocations in a tight loop — consider a pool or stack allocation
+- Flag `volatile` on variables not accessed by hardware or signal handlers — prevents optimization
+
+---
+
+## Idioms and Best Practices
+
+### Memory Safety
+- Every pointer must have a clear owner responsible for freeing it — document ownership in comments
+- Set pointers to `NULL` immediately after `free` to catch use-after-free early
+- Prefer `calloc` over `malloc` + `memset` for zero-initialized allocations
+- Use `const` on pointer parameters that the function does not modify
+
+### Defensive Coding
+- Always check `NULL` returns from allocation functions
+- Use `size_t` for sizes and counts — never `int`
+- Prefer `snprintf` and `fgets` over any unbounded string function
+- Compile with `-Wall -Wextra -Werror` and treat warnings as errors
+
+### Portability
+- Do not assume pointer size equals `int` size — use `intptr_t` / `uintptr_t`
+- Do not rely on undefined behavior for performance — use compiler intrinsics instead
+- Use `stdint.h` types (`uint32_t`, `int64_t`) for fixed-width requirements

package/engineering-team/skills/code-reviewer/languages/cpp.md

@@ -0,0 +1,103 @@
+---
+language: cpp
+extensions: [".cpp", ".cc", ".cxx", ".hpp", ".hh", ".hxx"]
+---
+
+# C++ — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only C++-specific rules and idioms.
+
+---
+
+## PR Analyzer — C++ Risk Signals
+
+- Raw `new` / `delete` outside of smart pointer wrappers
+- `reinterpret_cast` — almost always a red flag; require justification
+- Disabled compiler warnings (`#pragma warning(disable:...)`, `-w`)
+- `// TODO` / `// FIXME` near ownership or lifetime code
+- Hardcoded credentials or keys in source
+- Use of deprecated C-style functions: `strcpy`, `sprintf`, `gets`
+
+---
+
+## Code Quality — C++ Checks
+
+- Raw owning pointers (`T*`) used where `unique_ptr` / `shared_ptr` would express ownership
+- `shared_ptr` overused where `unique_ptr` suffices — implies shared ownership unnecessarily
+- `std::endl` used in hot paths — flushes the buffer every call; prefer `'\n'`
+- Implicit conversions between signed and unsigned integers
+- Virtual destructor missing on base classes with virtual methods
+- `catch (...)` swallowing all exceptions without logging or re-throwing
+
+---
+
+## Security
+
+- Flag `reinterpret_cast` on user-controlled data — potential type confusion
+- Flag raw array indexing without bounds check — use `.at()` or assert bounds
+- Flag `std::string` data passed to C APIs without null-termination guarantee — use `.c_str()`
+- Flag hardcoded buffer sizes — derive from `sizeof` or use `std::array<T, N>`
+- Flag `sscanf` / `sprintf` — use `std::istringstream` or `std::format` (C++20)
+- Flag user-controlled data used as a format string
+
+---
+
+## Async / Concurrency
+
+- Flag `std::shared_ptr` accessed from multiple threads — the pointer itself is not thread-safe for write; use `std::atomic<std::shared_ptr<T>>` (C++20) or external locking
+- Flag `std::vector` / `std::map` mutated from multiple threads without a mutex
+- Flag `std::mutex` locked twice in the same thread without `std::recursive_mutex` — deadlock
+- Flag detached threads (`std::thread::detach`) with no lifetime coordination
+- Flag `volatile` used instead of `std::atomic` for inter-thread communication
+
+---
+
+## Resource Management
+
+- Flag raw `new` returning an owning pointer — wrap immediately in `std::make_unique` or `std::make_shared`
+- Flag `delete` called manually outside of a destructor or smart pointer — ownership confusion
+- Flag RAII violations — resources acquired in constructor but not released via destructor
+- Flag `std::ifstream` / `std::ofstream` not checked for open failure before use
+- Flag exceptions thrown from destructors — causes `std::terminate` if thrown during stack unwinding
+
+---
+
+## Exception Handling
+
+- Flag `catch (...)` that swallows exceptions without logging or re-throwing
+- Flag exceptions thrown from destructors — wrap in `try/catch` inside the destructor
+- Flag `noexcept` on functions that can actually throw — causes `std::terminate`
+- Flag exception specifications (`throw(...)`) — deprecated since C++11, removed in C++17
+- Flag using exceptions for control flow in performance-critical paths
+
+---
+
+## Performance
+
+- Flag pass-by-value for non-trivial types where pass-by-const-reference suffices
+- Flag `std::vector::push_back` in a loop without `reserve` when size is known — repeated reallocations
+- Flag `std::map` used where `std::unordered_map` would give O(1) lookup
+- Flag `std::endl` in loops — prefer `'\n'` to avoid repeated buffer flushes
+- Flag unnecessary copies from missing `std::move` on local temporaries being returned or passed
+
+---
+
+## Idioms and Best Practices
+
+### Ownership and Lifetime
+- Prefer `std::unique_ptr` for sole ownership, `std::shared_ptr` only for shared ownership
+- Prefer `std::make_unique` / `std::make_shared` over `new` — exception-safe
+- Use `std::weak_ptr` to break `shared_ptr` cycles
+- Never use raw owning pointers in new code — they are for non-owning observation only
+
+### Modern C++ (17/20)
+- Prefer `std::optional<T>` over sentinel values or nullable pointers for optional returns
+- Prefer `std::variant` over tagged unions
+- Prefer `std::string_view` over `const std::string&` for read-only string parameters
+- Prefer range-based `for` loops over index loops where the index isn't needed
+- Prefer `if constexpr` over `#ifdef` for compile-time branching
+
+### Type Safety
+- Prefer `static_cast` over C-style casts — explicit and auditable
+- Avoid `reinterpret_cast` except in low-level I/O or FFI code with a comment
+- Use `enum class` over plain `enum` to avoid implicit integer conversions

package/engineering-team/skills/code-reviewer/languages/csharp.md

@@ -0,0 +1,97 @@
+---
+language: csharp
+extensions: [".cs", ".csx", ".razor", ".cshtml"]
+---
+
+# C# / .NET — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only C#-specific rules and idioms.
+
+---
+
+## PR Analyzer — C# Risk Signals
+
+- `#pragma warning disable` and `[SuppressMessage]` — verify they are justified
+- `unsafe { }` blocks — require explicit sign-off
+- Null-forgiving operator (`!`) used broadly without justification
+- `dynamic` used outside of interop scenarios
+- Hardcoded connection strings in source files
+
+---
+
+## Code Quality — C# Checks
+
+- `async void` methods (except event handlers)
+- `Task` returned but not awaited
+- `IDisposable` objects not in `using` / `using var`
+- Bare `catch { }` or `catch (Exception e) { }` swallowing silently
+- Nullable reference types feature disabled at project level
+
+---
+
+## Security
+
+- Flag raw string interpolation in SQL queries — require parameterized queries (`SqlCommand`) or EF Core
+- Flag missing `[ValidateAntiForgeryToken]` on state-changing controller actions
+- Flag user-controlled data passed to `Process.Start()` or `File` APIs without validation
+- Flag hardcoded connection strings — require `appsettings.json` + secrets management
+- Flag `[AllowAnonymous]` on endpoints that should be protected
+
+---
+
+## Async / Await
+
+- Flag `async void` methods outside of event handlers — cannot be awaited and swallow exceptions
+- Flag `.Result`, `.Wait()`, or `.GetAwaiter().GetResult()` on `Task` — causes deadlocks in ASP.NET contexts
+- Flag missing `ConfigureAwait(false)` in library (non-application) code
+- Flag `Task.Run()` wrapping synchronous code inside ASP.NET request handlers unnecessarily
+- Flag `CancellationToken` not threaded through to downstream async calls
+
+---
+
+## Resource Management
+
+- Flag `IDisposable` objects (`SqlConnection`, `HttpClient`, `FileStream`, etc.) not wrapped in `using` / `using var`
+- Flag `HttpClient` instantiated with `new` inside a method — use `IHttpClientFactory` or a shared static instance to avoid socket exhaustion
+- Flag `DbContext` registered as a singleton in DI — it must be scoped
+- Flag `MemoryStream` / `MemoryCache` growing unboundedly without eviction policy
+
+---
+
+## Exception Handling
+
+- Flag `catch { }` or `catch (Exception) { }` with no logging or re-throw — silent swallow
+- Flag `catch (Exception e) { throw e; }` — resets the stack trace; use `throw;` instead
+- Flag catching `Exception` when a specific type (`IOException`, `HttpRequestException`) is appropriate
+- Flag exception filters (`when`) used for side effects that suppress the exception
+- Flag exceptions used for control flow in hot paths — use `Try*` pattern methods instead
+
+---
+
+## Performance
+
+- Flag `.ToList()` / `.ToArray()` on `IQueryable` before filtering — forces all rows into memory; filter server-side first
+- Flag `string` concatenation in loops — use `StringBuilder`
+- Flag `Enumerable.Count()` on `IQueryable` when only an existence check is needed — use `Any()`
+- Flag `await` in a loop where `Task.WhenAll()` would parallelize the work
+- Flag synchronous file or network I/O in an `async` method — use the async overload
+
+---
+
+## Idioms and Best Practices
+
+### Null Safety
+- Ensure `<Nullable>enable</Nullable>` is set in the project file
+- Flag excessive use of `!` (null-forgiving) without a comment explaining why
+- Prefer `is null` / `is not null` over `== null` for null checks
+
+### LINQ
+- Flag `First()` where `FirstOrDefault()` is safer
+- Flag complex LINQ chains that would be clearer as explicit loops
+
+### Modern C# (10+)
+- Prefer `record` types for immutable data carriers
+- Prefer `switch` expressions over `switch` statements where a value is returned
+- Prefer primary constructors (C# 12) for simple dependency injection
+- Prefer file-scoped namespaces (`namespace Foo;`) over block-scoped
+- Prefer `is` pattern matching over explicit casts

package/engineering-team/skills/code-reviewer/languages/dart.md

@@ -0,0 +1,108 @@
+---
+language: dart
+extensions: [".dart"]
+---
+
+# Dart / Flutter — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Dart and Flutter-specific rules and idioms.
+
+---
+
+## PR Analyzer — Dart / Flutter Risk Signals
+
+- `print()` statements left in production code — use a logging package
+- `// ignore:` lint suppression comments — verify they are justified
+- `!` null assertion operator used broadly without justification
+- Hardcoded API keys, tokens, or URLs in Dart source — use environment variables or a secrets package
+- `TODO` / `FIXME` near widget lifecycle or state management code
+
+---
+
+## Code Quality — Dart Checks
+
+- `dynamic` used where a concrete type is known — defeats static analysis
+- `!` (null assertion) used broadly — prefer null-safe patterns
+- `StatefulWidget` used where `StatelessWidget` suffices — prefer stateless
+- `setState` called with heavy computation inside — offload before calling
+- `BuildContext` used across async gaps without checking `mounted`
+- Missing `const` constructor on widgets that could be constant
+
+---
+
+## Security
+
+- Flag API keys or secrets hardcoded in Dart source or `pubspec.yaml` — use `--dart-define` or a secrets manager
+- Flag `http` package used without certificate validation disabled intentionally
+- Flag `SharedPreferences` used to store sensitive data — use `flutter_secure_storage`
+- Flag user-controlled input used in `dart:io` file path operations without sanitization
+- Flag `WebView` loading arbitrary user-supplied URLs without validation
+- Flag deep link / URL scheme handlers that don't validate the incoming URL before acting on it
+
+---
+
+## Async / Concurrency
+
+- Flag `BuildContext` used after an `await` without checking `if (!mounted) return` — context may be invalid
+- Flag `Future` returned but not `await`-ed and without `.catchError()` or `unawaited()` — floating future
+- Flag `Isolate.spawn` without a clear message-passing protocol
+- Flag heavy computation on the main isolate — offload with `compute()` or `Isolate.run()`
+- Flag `StreamController` not closed when the owning widget is disposed — memory leak
+- Flag `async*` / `yield*` generators with no error handling on the stream consumer side
+
+---
+
+## Resource Management
+
+- Flag `StreamController` not closed in `dispose()`
+- Flag `AnimationController` not disposed in `dispose()`
+- Flag `TextEditingController` / `FocusNode` / `ScrollController` not disposed in `dispose()`
+- Flag `Timer` not cancelled in `dispose()`
+- Flag listeners added to `ChangeNotifier` / `ValueNotifier` without a corresponding `removeListener`
+
+---
+
+## Exception Handling
+
+- Flag empty `catch` blocks — swallowed errors
+- Flag `catchError` with no handler body — silent failure
+- Flag `Future.error` not surfaced to the UI — show an error state
+- Flag `FlutterError.onError` overridden without calling the original handler
+- Prefer typed `on ExceptionType catch (e)` over generic `catch (e)` where the exception type is known
+
+---
+
+## Performance
+
+- Flag `setState` called for changes that only affect a small subtree — use `ValueNotifier` / `provider` / `Riverpod` to scope rebuilds
+- Flag expensive computation inside `build()` — move to `initState`, a controller, or a `FutureBuilder`
+- Flag `ListView` without `ListView.builder` for long or infinite lists — builds all children at once
+- Flag missing `const` on widgets that never change — prevents unnecessary rebuilds
+- Flag `Image.network` without a caching package in a list — re-downloads on every scroll
+- Flag `RepaintBoundary` missing around frequently-repainted widgets (animations, counters)
+
+---
+
+## Idioms and Best Practices
+
+### Null Safety
+- Prefer `?.` safe navigation and `??` null coalescing over `!` assertions
+- Use `late` only when initialization is guaranteed before first access — document why
+- Prefer early returns over deeply nested null checks
+
+### Flutter Widget Patterns
+- Prefer `StatelessWidget` + external state management over `StatefulWidget` for business logic
+- Keep `build()` methods pure — no side effects, no heavy computation
+- Extract repeated widget subtrees into named widget classes, not just methods, for better rebuild granularity
+- Use `const` constructors wherever possible — compile-time constant widgets skip rebuilds entirely
+
+### State Management
+- Do not mix multiple state management approaches in the same feature
+- Flag business logic inside `build()` — it belongs in a ViewModel, Notifier, or BLoC
+- Prefer `Riverpod` / `provider` / `BLoC` over raw `setState` for anything beyond local UI state
+
+### Modern Dart (3.x)
+- Prefer `sealed` classes for exhaustive pattern matching on domain types
+- Use records (`(int, String)`) for lightweight multi-value returns instead of ad hoc classes
+- Use `switch` expressions with pattern matching instead of long `if/else` chains
+- Prefer `final` for local variables — immutability by default

package/engineering-team/skills/code-reviewer/languages/go.md

@@ -0,0 +1,92 @@
+---
+language: go
+extensions: [".go"]
+---
+
+# Go — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Go-specific rules and idioms.
+
+---
+
+## PR Analyzer — Go Risk Signals
+
+- `fmt.Println` / `log.Println` debug statements left in production code
+- `//nolint` comments — verify they are justified
+- `unsafe` package imports — require explicit sign-off
+- Hardcoded credentials or tokens in source
+
+---
+
+## Code Quality — Go Checks
+
+- Errors returned but not checked (`_ = someFunc()`)
+- `panic()` used outside of package initialization
+- Goroutines started without a clear lifetime or cancellation path
+- `interface{}` / `any` used where a concrete type or typed interface would work
+- Missing context propagation (`context.Context` not threaded through call chains)
+
+---
+
+## Security
+
+- Flag `database/sql` queries built with `fmt.Sprintf` — require `?` / `$N` placeholders
+- Flag `os/exec` calls with user-controlled arguments without sanitization
+- Flag `html/template` bypassed in favor of `text/template` for HTML output
+- Flag `http.ListenAndServeTLS` with `InsecureSkipVerify: true`
+
+---
+
+## Async / Concurrency
+
+- Flag goroutines started with no clear lifetime or cancellation path — always pass `context.Context`
+- Flag goroutines that write to a channel with no receiver and no `select` default — causes a leak
+- Flag `time.Sleep()` used inside a goroutine as a synchronization mechanism
+- Flag `sync.WaitGroup.Add()` called inside the goroutine it tracks — race condition
+- Flag `sync.Mutex` copied by value — must always be used as a pointer or embedded in a struct
+
+---
+
+## Resource Management
+
+- Flag `http.Response.Body` not closed after reading — even on error paths (`defer resp.Body.Close()`)
+- Flag `os.File` not closed — use `defer f.Close()` immediately after opening
+- Flag `rows.Close()` missing after `sql.Query()` — leaks the DB connection
+- Flag `context.WithCancel` / `context.WithTimeout` cancel function not called — context and resources leak
+
+---
+
+## Exception Handling
+
+- Flag errors assigned to `_` without a comment explaining why it is safe to ignore
+- Flag errors not wrapped with `fmt.Errorf("...: %w", err)` — loses stack context
+- Flag `errors.New` / `fmt.Errorf` strings starting with a capital letter or ending in punctuation — violates Go conventions
+- Flag `panic()` used for expected runtime errors — reserve for programming errors and unrecoverable states
+- Flag `recover()` used to silently swallow panics without logging
+
+---
+
+## Performance
+
+- Flag `fmt.Sprintf` used for simple string concatenation — use `strings.Builder` or `+` for small cases
+- Flag `append()` in a tight loop without pre-allocating slice capacity — use `make([]T, 0, n)`
+- Flag `json.Marshal` / `json.Unmarshal` on large structs in hot paths — consider `json.Encoder` / streaming
+- Flag goroutines spawned per-request without a worker pool for CPU-bound tasks
+
+---
+
+## Idioms and Best Practices
+
+### Error Handling
+- All returned errors must be checked — never assign to `_` without a comment
+- Prefer wrapping with `fmt.Errorf("...: %w", err)` for stack context
+- Use `errors.Is` / `errors.As` for error inspection — never string comparison
+
+### Concurrency
+- Every goroutine must have an owner responsible for its lifetime
+- Always pass `context.Context` as the first argument to functions that do I/O or block
+- Prefer `sync.WaitGroup` or `errgroup` over ad-hoc channel coordination
+
+### Modern Go (1.18+)
+- Prefer generics over `interface{}` for container types and utility functions
+- Use `any` (alias for `interface{}`) in new code for readability

package/engineering-team/skills/code-reviewer/languages/java.md

@@ -0,0 +1,103 @@
+---
+language: java
+extensions: [".java"]
+---
+
+# Java — Language-Specific Review Notes
+
+Load this file alongside `rules/universal.md`. Universal rules are not repeated here — only Java-specific rules and idioms.
+
+---
+
+## PR Analyzer — Java Risk Signals
+
+- `System.out.println` / `e.printStackTrace()` left in production code
+- `@SuppressWarnings` annotations — verify they are justified
+- Hardcoded JDBC URLs or credentials in source
+- Raw type usage (`List`, `Map` without generics)
+
+---
+
+## Code Quality — Java Checks
+
+- Empty `catch` blocks swallowing exceptions silently
+- Checked exceptions caught and not re-thrown with context
+- `Closeable` / `AutoCloseable` resources not in try-with-resources
+- Raw type usage — defeats generics type safety
+- Missing `@Override` on overriding methods
+- `InterruptedException` caught without calling `Thread.currentThread().interrupt()`
+
+---
+
+## Security
+
+- Flag JPQL / HQL or native SQL string concatenation — require named parameters or `CriteriaBuilder`
+- Flag `@RequestMapping` without explicit HTTP method restriction on state-changing endpoints
+- Flag user-controlled input passed to `Runtime.exec()` or `ProcessBuilder` without validation
+- Flag `ObjectInputStream.readObject()` on untrusted data — unsafe deserialization
+- Flag hardcoded JDBC URLs or credentials — require environment variables or a vault
+
+---
+
+## Async / Concurrency
+
+- Flag `ExecutorService.submit()` return value ignored — exceptions are swallowed
+- Flag `Thread.sleep()` used as a synchronization mechanism — use `CountDownLatch`, `CompletableFuture`, or `await()`
+- Flag `CompletableFuture` chains with no `.exceptionally()` or `.handle()` terminal handler
+- Flag `InterruptedException` caught without calling `Thread.currentThread().interrupt()`
+- Flag `synchronized` on a non-final field — the lock object can be replaced
+- Flag `HashMap` used in multi-threaded context — use `ConcurrentHashMap`
+
+---
+
+## Resource Management
+
+- Flag `InputStream`, `OutputStream`, `Connection`, `ResultSet`, `PreparedStatement` not wrapped in try-with-resources
+- Flag manual `finally { resource.close() }` — replace with try-with-resources
+- Flag `HttpURLConnection` not disconnected after use
+- Flag JDBC `Connection` obtained from a pool and not returned (missing `close()`) on all paths
+- Flag `static` `HttpClient` or `Connection` fields shared across threads without connection pool management
+
+---
+
+## Exception Handling
+
+- Flag empty `catch` blocks — `catch (Exception e) {}`
+- Flag `InterruptedException` caught without `Thread.currentThread().interrupt()` — breaks cooperative cancellation
+- Flag checked exceptions swallowed in a `catch` and not re-thrown or logged with context
+- Flag `throw new RuntimeException(e)` without a descriptive message — loses context
+- Flag `printStackTrace()` as the sole error handling — use a proper logger
+
+---
+
+## Performance
+
+- Flag `String` concatenation in loops — use `StringBuilder`
+- Flag `List.contains()` / `Map.get()` in a loop on large collections — review data structure choice
+- Flag N+1 JPA / Hibernate queries — use `JOIN FETCH` or `@BatchSize`
+- Flag `new ObjectMapper()` / `new Gson()` instantiated per-request — share a singleton
+- Flag `ResultSet` fully iterated when only the first result is needed — use `LIMIT 1` in the query
+
+---
+
+## Idioms and Best Practices
+
+### Null Safety
+- Prefer returning `Optional<T>` over `null` from methods
+- Flag unchecked dereferences without a prior null guard
+- Do not catch `NullPointerException` — fix the root cause instead
+
+### Collections and Streams
+- Flag `==` used to compare `String` or boxed types — use `.equals()`
+- Flag `.collect(Collectors.toList())` where `.toList()` (Java 16+) suffices
+- Flag premature `.stream().collect()` round-trips that could be a single-pass operation
+
+### Generics
+- Flag raw types in any new code — always parameterize (`List<String>`, not `List`)
+- Flag unchecked cast warnings suppressed without explanation
+
+### Modern Java (11+)
+- Prefer `var` for local variables where the type is obvious from the right-hand side
+- Prefer records for pure data carriers over manual POJOs with getters/setters
+- Prefer `instanceof` pattern matching (`if (obj instanceof String s)`) over explicit casts
+- Prefer `switch` expressions over `switch` statements where a value is returned