prr-kit 1.1.2 → 1.2.0

package/src/prr/data/stacks/flutter.md

@@ -0,0 +1,75 @@
+# Flutter / Dart — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.dart` files · `pubspec.yaml` with `flutter:` · `import 'package:flutter/` · `Widget` · `StatefulWidget` · `BuildContext` · `Riverpod`/`Bloc`/`Provider`
+
+---
+
+## Security
+
+- **[HIGH]** Sensitive data (tokens, passwords, PINs) in `SharedPreferences` → not encrypted. Use `flutter_secure_storage` (Keychain on iOS, Keystore on Android).
+- **[HIGH]** `WebView` with `javaScriptMode: JavascriptMode.unrestricted` loading untrusted URLs → XSS, platform channel access.
+- **[HIGH]** API keys hardcoded in Dart source → extracted from APK/IPA via reverse engineering. Use `--dart-define` or backend proxy.
+- **[HIGH]** `dart:mirrors` used for dynamic invocation of user-controlled method names → code injection.
+- **[MEDIUM]** Certificate validation disabled (custom `HttpClient.badCertificateCallback`) → MITM.
+- **[MEDIUM]** `Platform.environment` in Flutter → may expose environment variables. Use `--dart-define` for build-time constants.
+- **[MEDIUM]** Deep link params not validated → malicious intent triggers action with crafted data.
+- **[LOW]** Debug flag (`kDebugMode`) not checked before logging sensitive data.
+
+---
+
+## Performance
+
+- **[HIGH]** `setState()` on high-level ancestor for leaf change → rebuilds entire subtree. Use `Provider`/`Riverpod`/`ValueNotifier` to scope rebuilds.
+- **[HIGH]** Heavy objects created inside `build()` → recreated on every rebuild. Move to `initState()` or `didChangeDependencies()`.
+- **[HIGH]** `ListView` (non-builder) for dynamic/long lists → all items rendered. Use `ListView.builder()`.
+- **[HIGH]** `FutureBuilder` without stable `future` reference → parent rebuild creates new Future, re-fetches every time. Store Future in `initState`.
+- **[HIGH]** `const` constructor missing on stateless widgets → prevents subtree optimization.
+- **[HIGH]** `build()` method doing I/O or heavy computation → blocks UI thread. Use `compute()` or `Isolate`.
+- **[MEDIUM]** `Image.network` without `cacheWidth`/`cacheHeight` → full resolution decoded for small display.
+- **[MEDIUM]** `AnimationController` not disposed → memory leak and assertion errors.
+- **[MEDIUM]** `StreamBuilder` subscribing to broadcast stream that never closes → subscription held forever.
+- **[LOW]** Not using `RepaintBoundary` to isolate frequently repainting widgets → whole tree repainted.
+- **[LOW]** `Opacity` widget used for animations instead of `AnimatedOpacity` or `FadeTransition`.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic inside `Widget.build()` → hard to test. Use BLoC, Provider, Riverpod, or GetX.
+- **[HIGH]** `BuildContext` used across `async` gap without `mounted` check → crash after navigation.
+- **[HIGH]** `Navigator.pop()` called without checking navigator stack → `FlutterError` on first route.
+- **[HIGH]** `StatefulWidget` used for everything → use `StatelessWidget` + state management for separation.
+- **[MEDIUM]** `GetX` controller not bound to widget lifecycle → controller persists after widget destroyed.
+- **[MEDIUM]** Not using `GoRouter` or `auto_route` for deep link + navigation → manual route management breaks.
+- **[MEDIUM]** Platform channel not handling errors → unhandled exception on plugin failure.
+- **[LOW]** Widget `build()` >100 lines → extract named sub-widgets or methods.
+- **[LOW]** Not organizing code by feature → flat `lib/` directory with hundreds of files.
+
+---
+
+## Code Quality
+
+- **[HIGH]** `dynamic` type used broadly → defeats Dart sound null safety. Use specific types or generics.
+- **[HIGH]** `TextEditingController`/`FocusNode`/`ScrollController` not disposed → memory leak + debug assertion.
+- **[HIGH]** `mounted` check missing after every `await` in `StatefulWidget` method.
+- **[MEDIUM]** `print()` in production → use `debugPrint()` (no-op in release) or structured logging.
+- **[MEDIUM]** Missing `Key` on list items → Flutter can't reconcile tree on reorder.
+- **[MEDIUM]** `late` variables accessed before initialization → `LateInitializationError` at runtime.
+- **[MEDIUM]** Nullable variable accessed with `!` without check → `Null check operator used on null value`.
+- **[LOW]** Not running `flutter analyze` in CI → lint issues uncaught.
+- **[LOW]** `pubspec.yaml` dependencies not version-pinned → unexpected breaking changes.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `async` `onPressed` without `mounted` check → `setState()` on unmounted widget.
+- **[HIGH]** `Column` with `Expanded` inside `ListView` → layout exception (unbounded height). Use `shrinkWrap` or restructure.
+- **[HIGH]** `StreamController` not closed → memory leak and lint warning.
+- **[MEDIUM]** `Image.network` without `errorBuilder` → broken image shown silently.
+- **[MEDIUM]** `FocusNode.dispose()` not called → memory leak.
+- **[MEDIUM]** `Riverpod` provider accessed after widget disposed → `ProviderScope` not found error.
+- **[MEDIUM]** `WillPopScope` deprecated (Flutter 3.12+) → use `PopScope` with `canPop` instead.
+- **[LOW]** `ThemeData` not using `ColorScheme.fromSeed` (Material 3) → inconsistent colors.
+- **[LOW]** Not testing on both iOS and Android → platform-specific bugs missed.

package/src/prr/data/stacks/gin.md

@@ -0,0 +1,57 @@
+# Gin — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: "github.com/gin-gonic/gin", gin.Default(), gin.New(), c.JSON(, c.ShouldBindJSON, r.GET(, r.POST(
+
+---
+
+## Security
+- **[CRITICAL]** `c.ShouldBind` used without validation struct tags → unvalidated user input reaches business logic. Always define and enforce validation tags (`binding:"required"`, `validate:"email"`, etc.) on all bound structs.
+- **[CRITICAL]** SQL injection via `fmt.Sprintf` in database queries → attacker-controlled input alters query structure. Always use parameterized queries or an ORM with prepared statements.
+- **[HIGH]** Missing CORS configuration or wildcard CORS (`"*"`) in production → cross-origin requests accepted from any domain. Configure explicit allowed origins via gin-cors middleware.
+- **[HIGH]** No rate limiting middleware → DoS attacks succeed without throttling. Integrate a rate limiter such as `golang.org/x/time/rate` or a middleware library.
+- **[HIGH]** Server binding to `0.0.0.0` in production without TLS → traffic transmitted in plaintext over network. Terminate TLS at the load balancer or configure `tls.ListenAndServeTLS`.
+- **[HIGH]** SSRF via user-controlled URL in proxy or fetch handlers → attacker triggers requests to internal services. Validate and whitelist allowed URL schemes and hosts before making server-side requests.
+- **[MEDIUM]** Sensitive data (tokens, passwords) logged in debug mode → secrets appear in log files accessible to operators. Use structured logging with field redaction and disable debug logs in production.
+- **[MEDIUM]** Missing input length limits on string fields → oversized payloads cause excessive memory allocation or ReDoS in regex validators. Enforce maximum lengths in validation tags or middleware.
+
+---
+
+## Performance
+- **[HIGH]** Debug mode (`gin.Default()`) used in production → verbose logging and color output add unnecessary overhead. Use `gin.New()` with explicit middleware and set `GIN_MODE=release`.
+- **[MEDIUM]** No response caching for static or slow-changing data → repeated expensive queries for identical data on every request. Add cache-control headers or an in-memory cache layer.
+- **[MEDIUM]** Synchronous database calls in handlers without goroutines for independent queries → sequential round-trips increase total response latency. Use goroutines with `errgroup` for parallel independent DB calls.
+- **[MEDIUM]** Large JSON marshaling of full structs without streaming → entire response built in memory before sending. For very large datasets, use streaming encoders or pagination.
+- **[LOW]** Missing gzip middleware for large responses → uncompressed payloads increase bandwidth and client latency. Add `github.com/gin-contrib/gzip` to the middleware stack.
+- **[MEDIUM]** Allocating large slices with fixed capacity inside handlers → GC pressure accumulates under load. Pre-allocate with realistic capacity estimates or use sync.Pool for reusable buffers.
+- **[MEDIUM]** Not using Gin route groups for common middleware (e.g., auth, logging) → middleware applied redundantly or inconsistently across routes. Use `r.Group()` with shared middleware.
+
+---
+
+## Architecture
+- **[HIGH]** Business logic implemented in handler functions instead of a service layer → handlers become large, untestable, and tightly coupled to HTTP. Extract logic into service structs with well-defined interfaces.
+- **[HIGH]** Not using dependency injection → hardcoded global DB connections and singletons make testing impossible and hide coupling. Pass dependencies (DB, logger, services) through handler structs or closures.
+- **[MEDIUM]** Route groups not organized by domain or API version → route file becomes a flat, unnavigable list as the app grows. Group related routes with `r.Group("/api/v1/")` and domain prefixes.
+- **[MEDIUM]** Middleware not scoped appropriately to route groups → auth or logging middleware applied globally when only needed for specific paths. Attach middleware at the group level, not globally.
+- **[MEDIUM]** No graceful shutdown handling → in-flight requests dropped when the process receives SIGTERM. Implement `srv.Shutdown(ctx)` on SIGTERM/SIGINT signals.
+- **[LOW]** Single router file containing all route definitions → file grows unwieldy in large applications. Split route registration into per-domain files and register them in the main router setup.
+
+---
+
+## Code Quality
+- **[HIGH]** Missing `binding:"required"` tags on struct fields → optional fields treated as present when absent, leading to zero-value data passing validation silently. Tag all required fields explicitly.
+- **[MEDIUM]** Not using `c.Error()` for error accumulation during request processing → multiple errors not collected, only the last one surfaced. Use `c.Error(err)` and a centralized error handler middleware.
+- **[MEDIUM]** Handler returning `nil` error for all code paths → callers cannot differentiate success from business-logic errors. Return meaningful typed errors and let the error handler map them to HTTP status codes.
+- **[HIGH]** `c.Abort()` not called after `c.JSON()` in error path → handler chain continues executing after error response is sent. Always call `c.Abort()` when sending an early response in middleware.
+- **[MEDIUM]** Missing API versioning strategy → breaking changes break existing clients without warning. Use route groups with version prefixes (`/api/v1`) and document deprecation timelines.
+- **[LOW]** Not using Gin's custom validator tags via `validator.RegisterValidation` → complex validation rules duplicated across handlers. Register custom validators once and reference them via struct tags.
+
+---
+
+## Common Bugs & Pitfalls
+- **[MEDIUM]** Confusing `c.ShouldBindJSON` with `c.BindJSON` → `c.BindJSON` writes a 400 response automatically on error, preventing custom error handling. Prefer `c.ShouldBindJSON` and handle errors explicitly.
+- **[CRITICAL]** Handler goroutine using `c *gin.Context` after the request ends → Gin reuses context objects, causing data races and panics. Copy needed values before launching goroutines; never pass `c` directly.
+- **[MEDIUM]** `gin.Recovery()` swallowing panics silently in production without custom handler → panics logged at error level but client gets a generic 500 with no alerting. Replace with a custom recovery middleware that triggers alerting.
+- **[LOW]** Route params and paths being case-sensitive with trailing slash issues → clients get unexpected 404s due to URL casing or missing slash. Configure `RedirectTrailingSlash` and document case sensitivity.
+- **[HIGH]** Not validating `Content-Type` header before binding → unexpected content type causes a 400 error that is hard to debug. Check content-type early and return a clear error message.
+- **[MEDIUM]** Ignoring errors from `c.JSON()` or `c.String()` → write failures go undetected. Log write errors or use a response wrapper that captures write errors.

package/src/prr/data/stacks/github-actions.md

@@ -0,0 +1,71 @@
+# GitHub Actions Stack Rules
+
+Detection signals: `.github/workflows/*.yml`, `.github/workflows/*.yaml`, `on:` trigger, `jobs:`, `steps:`, `uses:`, `runs-on:`, `actions/checkout`
+
+---
+
+## Security
+
+- **[CRITICAL]** User-controlled data interpolated directly in a `run:` step via expressions like `github.event.issue.title` passed as shell arguments → script injection allows an attacker to execute arbitrary commands with the runner's permissions. Always pass untrusted input via an env var and reference as `$VAR` in shell, never inline the expression.
+- **[CRITICAL]** `pull_request_target` trigger checking out and running code from the PR branch → this event runs with write permissions and access to secrets; a malicious PR can exfiltrate the `GITHUB_TOKEN` or deploy credentials. Never checkout the PR ref in `pull_request_target` without strict branch restrictions and required approvals.
+- **[CRITICAL]** Secrets echoed or logged in run steps → GitHub masks known secret values but transformed or encoded forms may still leak. Never echo, log, or interpolate secrets into shell output; pass them only as environment variables to commands that need them.
+- **[HIGH]** Actions pinned by mutable tag (e.g. `uses: actions/checkout@v4`) rather than a full commit SHA → the tag can be moved or deleted, enabling a supply-chain attack that substitutes malicious code. Pin to full SHA with a tag comment: `uses: actions/checkout@11bd71901... # v4`.
+- **[HIGH]** `permissions: write-all` or omitting the `permissions` key entirely (defaults to write on some repos) → the `GITHUB_TOKEN` is over-privileged, increasing the blast radius of any compromised step. Always declare minimal permissions per job.
+- **[HIGH]** Self-hosted runner on shared infrastructure with no job isolation between runs → one workflow can read another job's secrets, artifacts, or working directory state. Use ephemeral self-hosted runners or GitHub-hosted runners for sensitive jobs.
+- **[HIGH]** Workflow triggered on `pull_request` with write permissions and no approval requirement for fork PRs → fork PR can trigger a privileged workflow and leak secrets. Use environment protection rules with required reviewers for any job that accesses secrets.
+- **[MEDIUM]** Third-party action from an unverified publisher without SHA pinning → the action could be compromised at any future point without warning. Fork the action into your own org, or pin to a specific commit SHA and audit the source.
+- **[MEDIUM]** Secrets stored in repo-level env blocks visible in verbose runner logs → even masked secrets may appear in transformed form. Use step-level env blocks and minimize secret scope to the step that needs it.
+- **[MEDIUM]** `GITHUB_TOKEN` used beyond its intended repository scope without explicit permission grant → scoping errors cause unexpected access or unexpected failures. Declare permissions explicitly; use fine-grained PATs for cross-repository operations.
+- **[LOW]** Workflow files in public repositories not reviewed by a security-aware maintainer → any maintainer can introduce a step that exfiltrates secrets. Require CODEOWNERS review for all changes to `.github/workflows/`.
+- **[LOW]** `continue-on-error: true` on security-sensitive steps such as secret rotation or audit submission → failure is silently ignored, leaving the system in an insecure state. Only use this on genuinely optional steps.
+
+---
+
+## Performance
+
+- **[CRITICAL]** No dependency caching (`actions/cache` or setup action built-in cache) for package managers → npm/pip/maven/gradle install runs from scratch on every job, wasting 1-5 minutes. Cache with a key based on the lockfile hash using hashFiles.
+- **[HIGH]** All steps in a single monolithic job with no parallelism → serial bottleneck; the job is as slow as the sum of all steps. Split into parallel jobs using the `needs:` dependency graph to run independent work concurrently.
+- **[HIGH]** Uploading and downloading artifacts in every job when only specific jobs need them → unnecessary I/O and artifact storage costs. Upload once in the producing job; download only in jobs that explicitly need it.
+- **[HIGH]** Matrix strategy not used for multi-platform or multi-version testing → sequential test runs instead of parallel. Use `strategy: matrix: { os: [...], node: [...] }` to test all combinations concurrently.
+- **[MEDIUM]** Uploading large unused artifacts (full build directories, node_modules) → wastes storage quota and slows down the workflow summary. Filter artifacts to only the files needed by downstream jobs or for debugging.
+- **[MEDIUM]** Missing `timeout-minutes` on jobs → a hung job (deadlocked process, waiting for user input) runs until the 6-hour GitHub default limit, burning paid minutes. Set an explicit timeout appropriate for each job.
+- **[MEDIUM]** No concurrency cancellation for PR branch workflows → every push to a PR branch queues a new run while old runs are still active, wasting minutes. Add a concurrency group with cancel-in-progress: true for pull_request triggers.
+- **[MEDIUM]** Running the full test suite on every push to every branch without path filtering → a docs-only change triggers a full 10-minute test run. Use `on: push: paths:` or `paths-ignore:` filters to skip irrelevant runs.
+- **[LOW]** Tool installation repeated in every job because the runner environment is not cached → installing Node.js, Python, or other runtimes adds 30-60 seconds per job. Use setup actions (`actions/setup-node`) with their built-in caching options.
+- **[LOW]** Not using composite actions or reusable workflows for repeated step sequences → the same 5-step build setup copy-pasted across 8 workflows drifts over time. Extract to a composite action or reusable workflow called via `uses:`.
+- **[LOW]** Not gating expensive steps on PR draft status or fork conditions → expensive deployments and integration tests run on every commit including work-in-progress. Check `github.event.pull_request.draft` before expensive steps.
+- **[LOW]** Not using `fetch-depth: 1` for jobs that do not need git history → full clone adds seconds on large repos. Add `fetch-depth: 1` to the checkout step for pure build/test jobs.
+
+---
+
+## Architecture
+
+- **[HIGH]** All deployment and CI logic in a single monolithic workflow file → no reusability; every project duplicates the same steps. Extract shared logic to reusable workflows (`workflow_call`) or composite actions and call them from individual workflow files.
+- **[HIGH]** Workflow triggered on push to main with no branch protection rules → direct pushes bypass PR review and immediately trigger production deployment. Enforce branch protection: require PR, status checks, and at least one review before merge.
+- **[HIGH]** No environment protection rules on production deployment jobs → any branch or actor can trigger a production deploy. Use GitHub Environments with required reviewers and deployment wait timers for production.
+- **[HIGH]** Repository-level secrets used across all workflows regardless of need → any workflow can read any repo secret, increasing blast radius of a compromised workflow. Use environment-scoped secrets that are only available to jobs targeting that environment.
+- **[MEDIUM]** Environment URLs, account IDs, or regions hardcoded in workflow YAML → changing environments requires searching and editing all workflow files. Use GitHub Environments, the `vars` context, or repository variables for environment-specific values.
+- **[MEDIUM]** No concurrency group on deployment workflows → parallel deployments to the same environment create race conditions and partial rollouts. Add a concurrency group per environment and cancel-in-progress or queue-based strategy.
+- **[MEDIUM]** Reusable workflow not versioned with a release tag → callers get breaking changes automatically when the reusable workflow is updated. Tag reusable workflows with semver releases and have callers pin to a tag.
+- **[MEDIUM]** Complex job dependency graph (needs:) not documented → multi-job DAGs are impossible to understand without a visual aid. Add a Mermaid diagram or ASCII art of the workflow DAG to the README or workflow file header.
+- **[LOW]** No branch naming convention enforced on wildcard triggers → wildcard branch patterns in triggers match unintended branches. Document and enforce a branch naming convention (`feature/*`, `fix/*`) and use it in trigger patterns.
+- **[LOW]** `workflow_dispatch` inputs not validated before use → integer or enum inputs arrive as strings; invalid values cause obscure errors in later steps. Validate all inputs in the first step and fail fast with a clear error message.
+- **[LOW]** No staging environment between CI and production → code goes directly from CI green to production without a pre-production validation step. Add a staging environment job with a smoke test gate before the production deployment job.
+- **[LOW]** Secrets shared between staging and production environments → a staging breach exposes production credentials. Use separate secret sets per environment; rotate independently.
+
+---
+
+## Code Quality
+
+- **[HIGH]** Deprecated `set-output` command: `echo "::set-output name=foo::bar"` → command was removed; workflows using it silently fail or produce warnings. Replace with the environment file approach: `echo "foo=bar" >> 'GITHUB_OUTPUT var'`.
+- **[HIGH]** Deprecated `set-env` command: `echo "::set-env name=VAR::val"` → command was disabled due to security vulnerabilities. Replace with: `echo "VAR=val" >> 'GITHUB_ENV var'`.
+- **[HIGH]** Deprecated `add-path` command: `echo "::add-path::..."` → command was disabled. Replace with: `echo "/my/path" >> 'GITHUB_PATH var'`.
+- **[HIGH]** `continue-on-error: true` on critical steps (build, test, security scan, deploy) → the job shows green even when a critical step fails, hiding real failures. Only use `continue-on-error` for genuinely optional steps; always check step outcome.
+- **[MEDIUM]** Long inline shell scripts in `run:` blocks → inline scripts are untestable, unlintable, and hard to review. Extract scripts to files in the repository (`.github/scripts/`), test them locally, and call them from the workflow.
+- **[MEDIUM]** Missing `defaults.run.shell` at workflow or job level → shell behavior differs across ubuntu, windows, and macos runners. Be explicit: set `defaults: run: shell: bash` to ensure consistent behavior.
+- **[MEDIUM]** Hardcoded runner labels using specific OS versions (`ubuntu-20.04`) → end-of-life runners cause silent workflow failures when GitHub removes them. Use `ubuntu-latest` or document the pinned version and set a calendar reminder to update.
+- **[MEDIUM]** Not using `fromJSON()` for complex expressions involving JSON manipulation → string operations on JSON in expression context are fragile and hard to debug. Use `fromJSON(steps.id.outputs.value)` to parse JSON outputs properly.
+- **[MEDIUM]** YAML anchors not used for repeated step configurations (env vars, options) → the same environment variable block copy-pasted across 12 steps drifts when values change. Use YAML anchors and aliases to define once and reference many times.
+- **[LOW]** Missing `if: always()` on cleanup or notification steps → these steps are skipped when a previous step fails, leaving cleanup undone and stakeholders uninformed. Add `if: always()` to steps that must run regardless of prior step outcome.
+- **[LOW]** Workflow files not linted with `actionlint` or a similar tool → YAML syntax errors, unknown context references, and deprecated commands are only caught at runtime. Add `rhysd/actionlint` to a pre-commit hook or a dedicated lint workflow.
+- **[LOW]** No comments explaining non-obvious workflow logic or permission grants → future maintainers cannot understand why a permission is needed or why a step exists. Add inline comments for all non-obvious decisions.

package/src/prr/data/stacks/go.md

@@ -0,0 +1,88 @@
+# Go — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.go` files, `go.mod`, `package main`, `func main()`, `goroutine`, `chan`, `go vet`, `golangci-lint`
+
+---
+
+## Security
+
+- **[CRITICAL]** SQL query with `fmt.Sprintf` / string concatenation of user input → SQL injection. Use `db.Query("SELECT ... WHERE id = ?", userInput)`.
+- **[CRITICAL]** `os/exec.Command` with user input as string to shell → command injection. Use argument list form.
+- **[HIGH]** `html/template` replaced with `text/template` for HTML rendering → XSS, `text/template` doesn't escape.
+- **[HIGH]** Sensitive data in error messages returned to client → info disclosure.
+- **[HIGH]** `math/rand` for security-sensitive values (tokens, IDs) → predictable. Use `crypto/rand`.
+- **[HIGH]** `filepath.Join` not used for user-controlled paths → path traversal via `../`.
+- **[HIGH]** `http.ListenAndServe` without TLS in production → plaintext traffic.
+- **[HIGH]** Goroutine spawned to handle request without context cancellation → goroutine leak on client disconnect.
+- **[HIGH]** CORS wildcard with credentials in HTTP handler → credential leakage to any origin.
+- **[MEDIUM]** Secrets loaded with `os.Getenv()` without validation for empty string → app runs with empty secret.
+- **[MEDIUM]** Race condition on shared map without `sync.Mutex` or `sync.RWMutex`.
+- **[LOW]** `regexp.MustCompile` with user input at runtime → panic on invalid regex.
+
+---
+
+## Performance
+
+- **[HIGH]** Goroutine leak — goroutine started but never signaled to stop (no `ctx.Done()`, no WaitGroup) → memory grows indefinitely.
+- **[HIGH]** Mutex held during I/O → blocks all goroutines waiting for lock.
+- **[HIGH]** Unbuffered channel for high-frequency events → sender blocks on every send.
+- **[HIGH]** `append` in tight loop without pre-allocated capacity → many reallocations. Use `make([]T, 0, knownSize)`.
+- **[HIGH]** `fmt.Sprintf` in hot path for string building → use `strings.Builder`.
+- **[HIGH]** Missing context timeout/deadline on HTTP client calls → requests hang indefinitely.
+- **[HIGH]** `sync.Mutex` protecting large struct when `sync.RWMutex` allows parallel reads.
+- **[MEDIUM]** Pointer to small struct unnecessarily → passing small structs by value is cheaper.
+- **[MEDIUM]** `defer` inside loop → defers execute at function end, not loop end → resource exhaustion.
+- **[MEDIUM]** Goroutine per request without worker pool → goroutine explosion under load.
+- **[MEDIUM]** JSON marshaling/unmarshaling in hot path without pooling encoder/decoder.
+- **[LOW]** `interface{}` / `any` in hot path → boxing/unboxing overhead.
+- **[LOW]** Not using `sync.Pool` for frequently allocated/freed objects.
+
+---
+
+## Architecture
+
+- **[HIGH]** Error ignored with `_` on operations that can fail → silent failures.
+- **[HIGH]** Panic used for expected error conditions → use error returns. Panic only for programmer errors.
+- **[HIGH]** Global mutable state (`var globalDB *sql.DB` mutated after init) → race conditions.
+- **[HIGH]** `init()` functions doing side effects (DB init, file I/O) → hard to test, unpredictable order.
+- **[HIGH]** Context not propagated through function call chain → cancellation doesn't work.
+- **[MEDIUM]** Interface defined by implementer instead of consumer → breaks dependency inversion.
+- **[MEDIUM]** Package names too generic (`util`, `common`, `helper`) → hard to discover.
+- **[MEDIUM]** Struct embedding for code reuse when composition/interfaces cleaner → hidden method promotion.
+- **[MEDIUM]** Not using `errors.Is()` / `errors.As()` for error inspection → string comparison brittle.
+- **[MEDIUM]** Not using sentinel errors or custom error types → callers can't distinguish error categories.
+- **[LOW]** Exported type without methods returning interface → unnecessary coupling.
+- **[LOW]** Not using `go generate` for repetitive boilerplate.
+
+---
+
+## Code Quality
+
+- **[HIGH]** Error not checked: `result, _ := someFunc()` when error indicates real failure.
+- **[HIGH]** `defer file.Close()` after error check omitted → resource leak if `Open()` fails.
+- **[HIGH]** Goroutine closure capturing loop variable → all goroutines use last value. Shadow: `v := v`.
+- **[MEDIUM]** Named return values with naked `return` in long functions → confusing.
+- **[MEDIUM]** Returning concrete type instead of interface from constructor → couples callers to implementation.
+- **[MEDIUM]** Not using `golangci-lint` / `staticcheck` → issues not caught.
+- **[MEDIUM]** `go vet` not run in CI → common mistakes missed.
+- **[MEDIUM]** Test files not using `_test` package for black-box testing → testing internal state.
+- **[LOW]** Missing `golint` compliance (exported types without comments).
+- **[LOW]** Not using table-driven tests → duplicated test setup.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** Loop variable captured by goroutine: `go func() { use(v) }()` in range → all use last value (fixed in Go 1.22).
+- **[HIGH]** Map/slice concurrent read+write without mutex → data race, undefined behavior.
+- **[HIGH]** `time.Sleep` for synchronization → use channels or `sync.WaitGroup`.
+- **[HIGH]** `nil` interface vs nil concrete pointer — `interface{}` wrapping nil pointer is not `== nil`.
+- **[HIGH]** `http.Response.Body` not closed after reading → connection leak.
+- **[HIGH]** Goroutine panics not recovered → crashes entire program.
+- **[MEDIUM]** `json.Unmarshal` ignoring error → silently retains zero values on malformed JSON.
+- **[MEDIUM]** Integer conversion between `int32` and `int64` losing data on 32-bit platforms.
+- **[MEDIUM]** `select` with default case in timing-sensitive code → busy loop.
+- **[MEDIUM]** `context.WithCancel` defer cancel not called → context leak.
+- **[LOW]** `make(chan T)` vs `make(chan T, 1)` — unbuffered vs buffered behavior difference not understood.
+- **[LOW]** `strings.Contains` used where `strings.HasPrefix`/`HasSuffix` is more appropriate.

package/src/prr/data/stacks/godot.md

@@ -0,0 +1,56 @@
+# Godot — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.gd` GDScript files, `*.tscn` scenes, `extends Node`, `func _ready()`, `func _process()`, `export var`, `@export`, `Godot`, `project.godot`
+
+---
+
+## Security
+- **[HIGH]** `OS.execute()` or `OS.shell_open()` called with user-controlled arguments → command injection on the host OS; never pass untrusted input to OS execution APIs.
+- **[HIGH]** HTTP requests made to user-provided URLs without validation → SSRF and malicious content fetching; validate URLs against an allowlist before any network request.
+- **[HIGH]** Save game files loaded with `JSON.parse()` or `ResourceLoader.load()` without schema validation → crashes or exploits from malformed data; validate all fields and types after deserialization.
+- **[MEDIUM]** `get_node()` called with a `NodePath` derived from user input → accessing arbitrary nodes in the scene tree; never construct node paths from untrusted data.
+- **[MEDIUM]** Autoload singletons storing authentication tokens or private game state accessible from any script → overly broad attack surface; restrict sensitive data access to dedicated, narrowly scoped systems.
+- **[LOW]** GDScript source files not encrypted in exported project (`Export > Resources > Script export mode`) → readable with PCK extraction tools; use bytecode-only export and PCK encryption for commercial titles.
+
+---
+
+## Performance
+- **[HIGH]** Heavy computation (pathfinding, collision queries, string building) in `_process(delta)` → called every frame at full refresh rate; move to `_physics_process`, signals, timers, or background threads via `Thread`.
+- **[HIGH]** `get_node()` or `$NodePath` shorthand called every frame instead of cached in `_ready()` → repeated scene-tree traversal; cache all node references as member variables in `_ready()`.
+- **[HIGH]** Nodes instantiated and freed every frame (bullets, particles, effects) without pooling → GC pressure and frame spikes; implement a node pool using `queue_free()` + `visible = false` recycling.
+- **[HIGH]** Large images imported without enabling appropriate compression (VRAM-compressed formats like S3TC, ETC2, BPTC) → excessive VRAM usage; configure import settings per texture type.
+- **[MEDIUM]** `await get_tree().process_frame` used in tight loops without frame budget awareness → logic spread across many deferred frames; batch work with explicit budgeting.
+- **[MEDIUM]** Signals not disconnected when nodes are freed → potential callbacks on freed objects; always disconnect signals in `_exit_tree()` or use `connect(..., CONNECT_ONE_SHOT)`.
+- **[LOW]** `VisibleOnScreenNotifier2D`/`VisibleOnScreenNotifier3D` not used for off-screen objects that run `_process` → wasted CPU on invisible nodes; disable processing when off-screen.
+
+---
+
+## Architecture
+- **[HIGH]** Scene tree traversal using `get_parent().get_parent().get_child(2)` chains → brittle structural coupling; use signals, groups, or exported node references for cross-node communication.
+- **[HIGH]** Autoloads used as a dumping ground for all shared state and logic → implicit global coupling that makes scenes non-portable; limit autoloads to truly global services and use scene-local composition otherwise.
+- **[MEDIUM]** Node-to-node communication done by calling methods directly on sibling or parent nodes instead of emitting signals → tight coupling; emit signals upward and call methods downward.
+- **[MEDIUM]** Game logic embedded in UI nodes (`Button`, `Label` subclasses with game rules) → untestable in isolation; separate game logic into non-UI Node or RefCounted classes.
+- **[MEDIUM]** Data not modeled as `Resource` subclasses → ad-hoc dictionaries passed everywhere; use typed `Resource` subclasses with `@export` fields for all structured data.
+- **[LOW]** Scenes not decomposed into reusable sub-scenes → monolithic tscn files that are hard to maintain; extract repeating structures into their own scenes.
+
+---
+
+## Code Quality
+- **[HIGH]** `@export` variables declared without type hints (`@export var speed` instead of `@export var speed: float`) → no editor type validation or static analysis; always type all exported variables.
+- **[HIGH]** Return value of `get_node()` used without null check on nodes that may be absent → "Invalid get index" runtime error; null-check or use `has_node()` before access.
+- **[MEDIUM]** GDScript functions and variables declared without type hints → static analyzer and Godot's type checker cannot catch errors; add type annotations to all declarations.
+- **[MEDIUM]** `match` statement without a default `_:` branch for enum-like values → unhandled states silently fall through; always include a default branch that asserts or logs.
+- **[MEDIUM]** Signals defined but never emitted, or emitted but never connected → dead code or broken communication channels; audit all signal definitions for use.
+- **[LOW]** Node names containing spaces (e.g., `"My Node"`) → `$My Node` shorthand breaks; use PascalCase or snake_case node names consistently.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** Holding a reference to a node after `queue_free()` and accessing it on the next frame → "Object was deleted" crash; use `is_instance_valid(node)` before accessing any potentially freed node.
+- **[HIGH]** Signal connected multiple times (e.g., inside `_process` or on scene re-entry) without checking for existing connections → callback invoked multiple times per event; use `is_connected()` guard or `CONNECT_ONE_SHOT`.
+- **[HIGH]** `_ready()` called before parent node's `_ready()` has completed in child-first order → child accesses parent state that is not yet initialized; use `call_deferred()` or `await owner.ready` for deferred initialization.
+- **[MEDIUM]** `CharacterBody2D`/`CharacterBody3D` velocity not reset to zero before applying new movement each frame → accumulated velocity causing unintended drift; reset or reassign `velocity` explicitly each physics frame.
+- **[MEDIUM]** `@export` variable default value changed in script after the scene has been saved → saved scene retains old serialized value, script default ignored; reset the property in the scene inspector after changing script defaults.
+- **[MEDIUM]** `Timer` node not stopped and freed when the owning node is removed → timer fires callback on a freed object; always call `timer.stop()` in `_exit_tree()`.
+- **[LOW]** Integer division used unintentionally in GDScript 4 (`5 / 2 == 2`) → use `float(5) / 2` or `5.0 / 2.0` for fractional results.

package/src/prr/data/stacks/graphql.md

@@ -0,0 +1,76 @@
+# GraphQL — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.graphql` / `*.gql` files, `gql\`\``, `GraphQLSchema`, `typeDefs`, `resolvers`, `ApolloServer`, `graphql-yoga`, `pothos`, `nexus`
+
+---
+
+## Security
+
+- **[CRITICAL]** Missing field-level authorization in resolver → any authenticated user queries any field/mutation. Check permissions per-resolver, not just at route level.
+- **[CRITICAL]** Introspection enabled in production → full schema exposed to attackers. Set `introspection: false` in production.
+- **[HIGH]** Missing query depth limit → nested queries cause exponential DB calls (DoS). Use `graphql-depth-limit` (max 7-10 levels).
+- **[HIGH]** Missing query complexity limit → single query requesting thousands of nodes. Use `graphql-query-complexity`.
+- **[HIGH]** User-controlled field names in dynamic resolver → injection or over-fetching of sensitive fields.
+- **[HIGH]** Batch query abuse — 1000 aliases in single query bypassing per-query rate limit. Limit max aliases.
+- **[HIGH]** Missing rate limiting at GraphQL endpoint → high-complexity queries bypass REST-level limits.
+- **[HIGH]** GraphQL errors leaking stack traces → configure custom error formatter to strip internal details.
+- **[MEDIUM]** IDOR in resolver — fetching resource by ID in args without ownership check.
+- **[MEDIUM]** Subscription not authenticated → real-time events delivered to unauthenticated WebSocket.
+- **[LOW]** `directives` not documented or enforced on sensitive fields → ad-hoc security.
+
+---
+
+## Performance
+
+- **[CRITICAL]** N+1 in resolver — DB query per parent node's children. Use `DataLoader` for batching + per-request caching.
+- **[HIGH]** Resolver fetching all related data regardless of selection set → over-fetching. Use projection based on `info.fieldNodes`.
+- **[HIGH]** No persisted queries → clients send full query string each request, larger payload, no CDN caching.
+- **[HIGH]** `DataLoader` not scoped per-request → stale data served from previous request's loader cache.
+- **[HIGH]** Subscription sending full object on every update when client only needs changed fields.
+- **[MEDIUM]** Missing `@cacheControl` directives → CDN cannot cache GraphQL responses.
+- **[MEDIUM]** Over-fetching in resolvers — entire DB record loaded for 2-field selection.
+- **[MEDIUM]** `context.dataloaders` not used → DataLoader instances not shared across resolvers in request.
+- **[MEDIUM]** Deeply nested fragment spread causing resolver chain traversal on every request.
+- **[LOW]** Not using `graphql-jit` for hot query compilation.
+
+---
+
+## Architecture
+
+- **[HIGH]** Business logic in resolver functions → move to service/domain layer; resolvers orchestrate only.
+- **[HIGH]** Schema-first vs code-first inconsistency in same project → pick one, enforce via lint.
+- **[HIGH]** Mutations not returning affected type → client must do extra query to refresh; return mutated entity.
+- **[HIGH]** Missing input validation on mutation args → invalid data reaches business logic.
+- **[MEDIUM]** Overloaded `Query` type with dozens of top-level fields → use namespaced query types.
+- **[MEDIUM]** Not using schema federation for microservices → monolithic schema becomes bottleneck.
+- **[MEDIUM]** Context not used for shared services (DB, auth, DataLoader) → instantiating per-resolver.
+- **[MEDIUM]** Union/interface types not used for polymorphic data → overloaded nullable fields.
+- **[LOW]** Missing `description` on types/fields → poor schema documentation, bad DX.
+- **[LOW]** Not using code-generation (`graphql-codegen`) for TypeScript types → resolvers typed as `any`.
+
+---
+
+## Code Quality
+
+- **[HIGH]** `any` type on resolver `context` or `parent` → no type safety.
+- **[HIGH]** Missing `__resolveType` on union/interface → Apollo can't distinguish members.
+- **[MEDIUM]** Resolver returning `undefined` for nullable field → client gets `null` unexpectedly.
+- **[MEDIUM]** `async` resolver not returning Promise → Apollo silently resolves, async work never awaited.
+- **[MEDIUM]** Mutations not following `input` type convention → inline args instead of typed `input` object.
+- **[MEDIUM]** Error handling inconsistent — some resolvers throw, others return `null` → client can't distinguish.
+- **[LOW]** Not using `graphql-scalars` for common scalars (DateTime, URL, Email) → custom validator reinvented.
+- **[LOW]** Schema not validated with `graphql-inspector` → breaking changes undetected.
+
+---
+
+## Common Bugs & Pitfalls
+
+- **[HIGH]** `DataLoader` key type mismatch (string vs number) → batching function receives mixed types, wrong results.
+- **[HIGH]** Subscription not cleaned up on client disconnect → resource leak (DB connection, event listener).
+- **[HIGH]** Resolver error not wrapped in `GraphQLError` → error format inconsistent, stack trace leaked.
+- **[MEDIUM]** `context` mutated inside resolver → shared between parallel field resolvers, race condition.
+- **[MEDIUM]** DataLoader `batchLoadFn` not returning results in same order as keys → wrong data mapped to wrong parents.
+- **[MEDIUM]** `@deprecated` directive added but not enforced in CI → clients continue using deprecated fields.
+- **[LOW]** Union type `__resolveType` missing → Apollo returns null for union field.
+- **[LOW]** `null` vs empty array not distinguished in list fields → client gets wrong "no results" state.

package/src/prr/data/stacks/grpc.md

@@ -0,0 +1,56 @@
+# gRPC — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: grpc, .proto files, protoc, grpc-js, grpcio, google.golang.org/grpc, @grpc/grpc-js, protobuf
+
+---
+
+## Security
+- **[CRITICAL]** gRPC server not configured with TLS → all traffic transmitted in plaintext over the network. Configure mutual TLS or server-side TLS for all production gRPC servers.
+- **[CRITICAL]** No authentication interceptor → unauthenticated calls accepted by all service methods. Add a server interceptor that validates JWT, mTLS certificate, or API key on every incoming RPC.
+- **[HIGH]** Metadata headers not validated for auth tokens → auth data present in metadata but not verified, allowing forged tokens. Extract and validate tokens from incoming metadata in the auth interceptor.
+- **[HIGH]** Server reflection enabled in production → attackers can enumerate all service definitions and methods, aiding targeted attacks. Disable server reflection in production; enable only in development.
+- **[HIGH]** Unvalidated proto message fields → missing required field validation allows invalid data into business logic, causing panics or incorrect behavior. Use protoc-gen-validate or protovalidate to enforce field constraints.
+- **[HIGH]** SSRF via server-side gRPC calls to user-provided service addresses → attacker routes internal requests to arbitrary targets. Validate and whitelist allowed gRPC endpoints before dialing.
+- **[MEDIUM]** Error messages in gRPC status details exposing internal implementation → stack traces or DB errors sent to clients aid attackers. Return sanitized error messages; log detailed errors server-side only.
+- **[MEDIUM]** Insufficient input size limits on streaming RPCs → oversized messages exhaust server memory. Configure max message size limits on the server and validate message sizes in streaming handlers.
+
+---
+
+## Performance
+- **[HIGH]** Unary RPC used for streaming use cases (large result sets, real-time events) → high latency and excessive overhead from repeated round-trips. Use server-streaming or bidirectional-streaming RPCs for continuous data flows.
+- **[HIGH]** Large proto messages not using field streaming or chunking → entire payload buffered in memory, causing high latency and memory pressure. Break large payloads into streaming chunks or paginate with server-streaming.
+- **[HIGH]** Client connection not reused across calls → TLS handshake and TCP connection established per call, adding significant latency. Create a single gRPC client connection or connection pool and reuse it.
+- **[HIGH]** Missing deadline or timeout on every RPC call → slow or unresponsive servers hold goroutines/threads indefinitely, exhausting client resources. Always set a deadline via context: ctx, cancel := context.WithTimeout(ctx, 5*time.Second).
+- **[MEDIUM]** No client-side load balancing configured → all calls routed to a single server instance, negating horizontal scaling. Configure gRPC client-side load balancing (round-robin, pick-first) or use a service mesh.
+- **[MEDIUM]** Not retrying idempotent RPCs on transient failures → network blips cause unnecessary failures for safe-to-retry operations. Configure retry policy or implement exponential backoff for UNAVAILABLE and DEADLINE_EXCEEDED errors.
+- **[LOW]** Not enabling gzip compression for large message payloads → large proto messages consume excess bandwidth. Enable compression codec on both client and server for message-heavy services.
+
+---
+
+## Architecture
+- **[MEDIUM]** Proto definitions not in a separate shared proto repository or directory → service teams duplicate definitions, leading to drift and incompatibility. Centralize proto files in a shared repo with versioned packages.
+- **[HIGH]** Breaking proto changes (renaming fields, changing field numbers, removing fields) without versioning → existing clients break when server updates. Create new package versions (v2, v3) for breaking changes; never alter field numbers.
+- **[HIGH]** Business logic in gRPC server handler methods instead of a service layer → handlers become untestable monoliths. Extract domain logic into service types and call them from thin handler methods.
+- **[MEDIUM]** Not using interceptors for logging, tracing, and metrics → observability data absent, making production debugging difficult. Add unary and streaming interceptors for structured logging, OpenTelemetry tracing, and Prometheus metrics.
+- **[MEDIUM]** Proto-generated code committed to the repository instead of generated in CI → generated code drifts from proto definitions when developers forget to regenerate. Run protoc as a CI step and check for uncommitted changes.
+
+---
+
+## Code Quality
+- **[MEDIUM]** Generated proto code committed to repo instead of generated in CI → generated files drift from proto source when developers forget to regenerate. Add proto compilation to CI and fail the build on uncommitted generated changes.
+- **[HIGH]** Missing protoc-gen-validate or protovalidate for field-level validation → business logic receives invalid field values (empty required strings, out-of-range numbers). Add validation annotations to proto files and enforce them at the RPC boundary.
+- **[MEDIUM]** gRPC status codes not semantically correct (e.g., INTERNAL returned for NOT_FOUND) → clients cannot distinguish error categories to implement correct retry or fallback logic. Map domain errors to appropriate gRPC status codes (NOT_FOUND, INVALID_ARGUMENT, etc.).
+- **[LOW]** Not documenting proto service and message fields with comments → API consumers cannot understand expected values or semantics without reading source code. Add proto comment annotations; use buf.build or similar for generated API docs.
+- **[MEDIUM]** Not using well-known types (google.protobuf.Timestamp, google.protobuf.Duration) for time fields → custom time representations lead to parsing bugs across language implementations. Use official well-known proto types for temporal data.
+- **[MEDIUM]** Service definitions not following proto naming conventions → inconsistent naming confuses consumers and makes tooling harder. Follow Google API design guide naming conventions for RPCs, fields, and enums.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** Deadline not propagated from the incoming parent context to downstream RPC calls → child calls run past the parent deadline, consuming resources after the client has given up. Always derive child contexts from the incoming request context.
+- **[HIGH]** ClientConn not closed after use → goroutines and TCP connections leak indefinitely. Always defer conn.Close() after creating a gRPC client connection.
+- **[MEDIUM]** Streaming server not sending an error status before closing the stream → client receives an EOF with no error context, making debugging difficult. Send a non-OK status via stream.SendMsg or return an error from the handler before returning.
+- **[MEDIUM]** Proto oneof fields not handled exhaustively in switch statements → new oneof variants introduced in future proto versions silently fall through to a default case. Add a default branch that logs an unknown variant warning.
+- **[HIGH]** Not handling stream context cancellation in server-streaming handlers → handlers continue sending after the client disconnects, wasting server resources. Check stream.Context().Done() in the streaming loop and exit cleanly.
+- **[MEDIUM]** Reusing proto message structs across goroutines without copying → concurrent mutation of proto messages causes data races. Clone proto messages before passing to goroutines using proto.Clone().

package/src/prr/data/stacks/haskell.md

@@ -0,0 +1,48 @@
+# Haskell — Stack-Specific Review Rules
+
+> Applies to: GR · SR · PR · AR · BR
+> Detection signals: `*.hs`, `import Control.`, `import Data.`, `module `, `where`, `do`, `IO ()`, `cabal.project`, `stack.yaml`, `ghc`
+
+---
+
+## Security
+- **[HIGH]** `unsafePerformIO` used in ostensibly pure code → violates referential transparency and can introduce data races when the IO action is shared across threads. Replace with properly threaded `IO` or use `IORef`/`MVar` for shared mutable state.
+- **[HIGH]** `read` called on untrusted input → throws an exception (partial function) on any parse failure, crashing the thread. Use `readMaybe` from `Text.Read` and handle the `Nothing` case explicitly.
+- **[MEDIUM]** Lazy IO via `readFile` / `hGetContents` → file handle not closed until the lazy string is fully consumed; if evaluation is deferred, handle leaks occur. Use `withFile` + strict `Data.ByteString` / `Data.Text` IO or the `conduit`/`pipes` streaming library.
+- **[MEDIUM]** Cryptographic operations using unmaintained or unaudited libraries → known vulnerabilities unpatched. Use `cryptonite` or `botan-bindings` and pin exact versions; review library update history before adoption.
+
+---
+
+## Performance
+- **[HIGH]** Lazy evaluation causing space leaks — thunks accumulate in long-running folds or accumulator patterns → process RSS grows unboundedly. Force strict evaluation with `seq`, `deepseq`, `BangPatterns`, or strict data fields (`{-# LANGUAGE StrictData #-}`).
+- **[HIGH]** `String` (linked list of `Char`) used for text processing → 5–20× memory overhead and poor cache performance compared to `Text`. Use `Data.Text` (UTF-16 packed) or `Data.ByteString` for all string-heavy code.
+- **[HIGH]** `Data.List` operations (`!!`, `length`) on large lists → O(n) traversal. Use `Data.Sequence` for O(log n) indexed access or `Data.Vector` for O(1) arrays.
+- **[MEDIUM]** Accumulator in recursive function not forced with `!` (BangPattern) → thunk chain of size n built before evaluation begins, consuming O(n) stack/heap. Add `BangPatterns` or use `foldl'` (strict fold from `Data.List`).
+- **[MEDIUM]** No profiling performed with GHC's `+RTS -p -s` runtime flags → space leaks and hot spots remain undetected until production. Run with `-prof -fprof-auto` during development to generate heap profiles.
+
+---
+
+## Architecture
+- **[HIGH]** `IO` actions scattered throughout pure business logic → untestable without executing real effects. Separate pure logic from effects using the `ReaderT` pattern, `MTL` type classes, or an algebraic effects library (`effectful`, `polysemy`).
+- **[HIGH]** Partial functions (`head`, `tail`, `fromJust`, `!!`) used in production code → `Exception` thrown on empty list or `Nothing`. Replace with total alternatives: `listToMaybe`, `maybe`, pattern match with an explicit empty case.
+- **[MEDIUM]** Not using the `ReaderT` pattern for passing configuration and dependencies → functions take many explicit arguments or rely on global `IORef`s. Thread a `Env` record through `ReaderT Env IO` for implicit dependency injection.
+- **[MEDIUM]** `State` monad overused for logic that is actually a pure fold → unnecessary monad overhead. Prefer `foldl'` or explicit accumulator arguments for simple stateful transformations.
+- **[LOW]** Library and executable sources not separated in the Cabal file → internal modules exposed inadvertently; slower test compilation. Define a `library` stanza with the `exposed-modules` list and have the `executable` depend on it.
+
+---
+
+## Code Quality
+- **[HIGH]** Partial functions in production: `head []`, `fromJust Nothing`, `arr !! outOfBounds` → runtime `Exception` with no meaningful error site. Use `listToMaybe`, `maybe default id`, and bounds-checked indexing; compile with `-Wall -Werror` to catch incomplete patterns.
+- **[HIGH]** `error "TODO"` or `undefined` left in non-test code → crashes at runtime when the code path is reached. Replace with proper `Either`/`Maybe` returns or typed not-implemented errors before merging.
+- **[MEDIUM]** Not running `hlint` and `ormolu`/`fourmolu` in CI → stylistic inconsistencies and common anti-patterns accumulate. Add `hlint` and formatter checks as CI steps; fail on any hint.
+- **[MEDIUM]** Type signatures missing on top-level functions → GHC infers types but they may be more general than intended, causing subtle bugs or confusing error messages elsewhere. Add explicit type signatures to all top-level and exported functions.
+- **[LOW]** Pattern matching not exhaustive with `-Wall` suppressed → `Non-exhaustive patterns` warning hidden, crashes in production. Compile with `-Wall -Wexhaustive-fields` and treat warnings as errors in CI.
+
+---
+
+## Common Bugs & Pitfalls
+- **[HIGH]** Lazy `foldl` instead of strict `foldl'` for summation or accumulation → O(n) thunk chain causes stack overflow on large inputs. Always use `Data.List.foldl'` or `Data.Foldable.foldl'`; never use `foldl` on a strict result.
+- **[HIGH]** `show` / `read` round-trip assumed for all types → `read (show x) /= x` for types like `Double` (NaN, Infinity) or custom `Show` instances. Use explicit serialization (Aeson, binary) for persistence rather than `show`/`read`.
+- **[MEDIUM]** Monad transformer stack order not carefully chosen → `StateT s (ExceptT e IO)` (state lost on error) vs `ExceptT e (StateT s IO)` (state preserved on error) have different semantics. Document the intended error/state interaction and encode it in the type stack order.
+- **[MEDIUM]** `unsafeCoerce` used to work around a type-checker error → type safety voided, potential runtime crash or memory corruption. Fix the underlying type mismatch; use `Data.Coerce.coerce` only for `newtype` coercions where it is guaranteed safe.
+- **[LOW]** `deriving (Eq, Ord)` field order determines comparison semantics → adding a field changes the `Ord` instance, breaking `Map`/`Set` ordering. Document the intended comparison key and consider a manual `Ord` instance or `newtype` wrapper for maps.