hive-skills 0.1.0

package/assets/skills/authored/code-review/composable/BUNDLE.md

@@ -0,0 +1,192 @@
+<!-- GENERATED by tools/hive.py compile. Do not hand-edit. -->
+# code-review: Compiled Skill Bundle (v1.0.0)
+
+All composable mini-skills for `code-review` concatenated in index order, frontmatter stripped. Regenerate with `tools/hive.py compile <skill-dir>`. Do not edit by hand.
+
+---
+<!-- module: 01-review-method.md -->
+
+# Review Mindset & Method
+
+A review's job is to find the defects that matter and communicate them so they get fixed. Everything else is secondary.
+
+**Read with a threat model.** For the code in front of you, ask: what does it trust? What can an attacker or a buggy caller feed it? What happens when each assumption is false? Bugs live where assumptions meet reality.
+
+**Read enough context.** Review the diff, but read the surrounding code to understand invariants. A change is only correct relative to the contract of the functions it calls and the callers it serves. A line that looks fine in isolation may violate a precondition established elsewhere.
+
+**Work in passes, not one linear read:**
+1. Understand intent and the happy path: what is this trying to do?
+2. Hunt correctness and security defects: where does it break?
+3. Consider concurrency, error handling, and performance.
+4. Assess tests and design: is the change complete and maintainable?
+
+**Prioritize by impact.** A security hole or data-corruption bug outranks a style nit every time. Spend your attention budget on the code that can hurt: input handling, auth, money, state mutation, external calls. Skim boilerplate.
+
+**Reproduce before you report.** For each candidate defect, construct the concrete input or interleaving that triggers it. A finding you can trace to a failing scenario is strong; a vague "this looks risky" is weak and erodes trust in the review.
+
+**Stay collaborative.** Assume competence; ask when intent is unclear rather than assuming a mistake. The goal is better code merged, not a scorecard. Lead with the findings that matter and don't bury a critical issue under a pile of nits.
+
+**A fast sweep to run against any non-trivial change:**
+- Security: untrusted input reaching SQL/shell/templates parameterized? Paths canonicalized and contained? No hardcoded secrets? Strong password hashing, CSPRNG for tokens? Every object access authorized, not just authenticated?
+- Correctness: boundaries (empty/one/last) handled? `None` guarded? No mutable default args? Money in `Decimal`/integers?
+- Concurrency: shared state locked or avoided? Check-then-act atomic? No blocking call in async code?
+- Errors: no bare `except`/silent swallow? Cleanup on every path? Multi-step mutations transactional?
+- Performance: no query/network call in a loop (N+1)? No list-membership tests in hot loops? Large data streamed?
+- Design & tests: interfaces single-purpose and backward-compatible? Risky branches and the new security check covered by meaningful tests, with a regression test for any fix?
+
+Run the sweep, then focus your attention on the two or three areas the change actually touches: the checklist finds candidates, deep reading confirms them.
+
+---
+<!-- module: 02-security-review.md -->
+
+# Security Review
+
+Security bugs are the highest-value finding. Work these categories on any change touching input, storage, or external systems.
+
+**Injection.** Untrusted input reaching an interpreter (SQL, shell, LDAP, XML, template) needs parameterization, not concatenation. Flag `f"SELECT ... WHERE id = {user_id}"` and `execute("... %s" % val)`; require bound parameters: `execute("... WHERE id = %s", (user_id,))`. For shell, flag `os.system` and `subprocess.run(..., shell=True)` with interpolated input; require `shell=False` with an arg list. Watch ORM/NoSQL operators injected via user-controlled dicts.
+
+**Path traversal.** When a path comes from input, `../` can escape the intended directory. Require canonicalization + containment: resolve the real path and verify it's inside the base (`Path.resolve().is_relative_to(base)` or `realpath(p).startswith(base)`). Reject absolute paths and null bytes.
+
+**Secrets.** Flag hardcoded API keys, passwords, tokens, private keys in source, including test fixtures and example configs. Secrets belong in env vars or a secret manager, never the repo or logs. Check that logs and error messages don't echo credentials.
+
+**Crypto.** Flag MD5/SHA-1 for security use and passwords stored with a fast hash or none. Passwords need bcrypt/scrypt/argon2 with per-user salt. Flag ECB mode, static/zero IVs, and reused IVs. Require a CSPRNG (`secrets`, `os.urandom`) for tokens, never `random`. Check TLS verification isn't disabled (`verify=False`).
+
+**AuthN vs AuthZ.** Authentication is who you are; authorization is what you may do. The classic bug (IDOR): an endpoint authenticates the user but never checks the requested object belongs to them. Verify every object access is scoped to the caller's permissions, and that "internal"/admin routes have access control.
+
+**Other high-value checks.** SSRF (server fetching a user-supplied URL: allowlist hosts, block internal ranges); unsafe deserialization (`pickle`, `yaml.load` without `SafeLoader`); open redirects; missing rate limits on auth endpoints. Validate and bound all input at the trust boundary.
+
+---
+<!-- module: 03-correctness-bugs.md -->
+
+# Correctness Bugs
+
+These defects make code do the wrong thing on some input. Check each category, and for every candidate construct the concrete triggering input.
+
+- **Off-by-one / boundary:** empty collections, single-element cases, the last index, inclusive vs exclusive ranges. Most boundary bugs hide at size 0 and size 1.
+- **None/null handling:** a value that can be `None` used without a guard; `dict.get()` returning `None` then dereferenced; a function returning `None` on a path the caller doesn't expect.
+- **Type and coercion bugs:** comparing strings to ints, truthiness of `0` / `""` / `[]` mistaken for "missing" (use explicit `is None`), integer vs float division.
+- **Incorrect conditionals:** inverted logic, `and`/`or` precedence, `==` vs `is`, De Morgan mistakes, a `not` binding to the wrong clause.
+- **Mutable default arguments:** `def f(x, acc=[])`: the default is created once and shared across all calls, so it accumulates. Use `None` and initialize inside the function.
+- **Loop and state bugs:** modifying a collection while iterating it; an accumulator reset in the wrong scope; an early `return`/`break` that skips cleanup or a later necessary step.
+- **Resource leaks:** files, sockets, DB connections not closed on every path (including exceptions). Require context managers (`with`).
+- **Floating-point money:** never use binary floats for currency. Rounding errors accumulate. Use integer cents or `Decimal`.
+
+The discipline that separates a strong finding from noise: name the exact input and the wrong output it produces. "This crashes when `items` is empty because line 12 indexes `items[0]`" is actionable; "the loop looks off" is not.
+
+---
+<!-- module: 04-concurrency.md -->
+
+# Concurrency
+
+Concurrency defects are subtle and rarely covered by tests, so review them deliberately whenever code is threaded, async, or shares state across requests.
+
+- **Race conditions / check-then-act:** `if not exists(k): create(k)` run by two threads can both pass the check and both create. Require atomic operations, locks, or DB-level guarantees: a unique constraint plus `INSERT ... ON CONFLICT`, or a compare-and-swap. Any read-modify-write on shared data is suspect.
+- **Shared mutable state:** module-level dicts, lists, counters, or caches mutated by concurrent requests without a lock. Remember `counter += 1` is not atomic: it's a read, an add, and a write, any of which can interleave. Prefer per-request state or thread-safe structures.
+- **Deadlocks:** two locks acquired in inconsistent order across different code paths. Establish and follow a global lock ordering; hold locks for the shortest span possible.
+- **Async pitfalls:** a blocking call (sync I/O, `time.sleep`, CPU-heavy loop) inside `async` code freezes the whole event loop and stalls every concurrent task. Also flag a forgotten `await` (the coroutine never runs), and task exceptions that are swallowed because no one awaits the task.
+- **TOCTOU on the filesystem:** check-then-use races, such as `if os.path.exists(p): open(p)`, where the file changes between the two calls. Prefer a single atomic operation (open with the right flags, `O_CREAT|O_EXCL`) over stat-then-open.
+
+Because these bugs surface only under specific interleavings, reason about "what if two callers hit this simultaneously" for every piece of shared state, rather than relying on tests to catch them. A useful mental model: mark every read-modify-write on shared data, then ask whether another thread could slip between the read and the write. If it could, and the outcome would be wrong, you have a race that needs a lock, an atomic primitive, or a database-level guarantee.
+
+---
+<!-- module: 05-error-handling.md -->
+
+# Error Handling
+
+Good error handling is about failing safely and visibly, never silently.
+
+- **Bare and blanket excepts.** Flag `except:` and `except Exception: pass`. They hide bugs and turn failures into silent wrong behavior. Catch the specific exceptions you can handle; log or re-raise the rest.
+- **Silent failure via sentinels.** Don't swallow an error and return a sentinel (`None`, `-1`, `[]`, `False`) that callers treat as success. If you can't handle it, fail loudly. If you return a sentinel, make sure every caller checks it.
+- **Cleanup on every path.** Files, locks, connections, and transactions must be released whether the code succeeds or raises. Use `finally` or context managers rather than duplicating cleanup before each `return`: the duplicated version always misses a path.
+- **Message hygiene.** Error messages should aid debugging without leaking internals to end users: log the detail (stack trace, ids) server-side, return a generic message to the client. Don't echo secrets, SQL, or file paths.
+- **Consistent state on partial failure.** A multi-step mutation that fails halfway can leave data inconsistent. Wrap it in a transaction and roll back on error, or design idempotent/compensating steps. Verify the code doesn't commit step 1, then throw on step 2.
+- **Don't lose context.** Catching an exception only to raise a vaguer one discards the stack and the root cause. Chain exceptions (`raise NewError(...) from exc`) or let the original propagate.
+
+The core question for any `try` block: if this raises, does the system end up in a known-good state, and will someone find out it happened? If either answer is no, it's a finding.
+
+---
+<!-- module: 06-performance.md -->
+
+# Performance
+
+Focus on algorithmic and I/O issues that scale badly with data or load. Ignore micro-optimizations that don't move the needle.
+
+- **N+1 queries.** A database (or network) call inside a loop over rows is the most common real-world performance bug: 1 query to list, then N to fetch each item's detail. Batch it into one query, or eager-load the relationship. Spotting a `.get`/`.query`/`fetch` inside a `for` loop is a red flag.
+- **Accidental O(n²).** Membership tests against a list inside a loop (`if x in big_list`) turn linear work quadratic. Use a `set`/`dict` for O(1) lookup. Watch nested loops over the same large collection, and invariant work recomputed each iteration that could be hoisted out.
+- **Unbounded memory.** Loading an entire large file or result set into memory (`f.read()`, `.all()` on a huge table) risks OOM. Stream, chunk, or paginate instead.
+- **Missing indexes / full scans.** Query patterns filtering or joining on unindexed columns imply table scans. Repeated identical queries that should be cached also count.
+- **Chatty I/O.** Many small network or disk calls that could be batched; a new connection per call instead of a reused pooled client.
+
+Discipline: **distinguish hot paths from cold.** A slow one-time startup step rarely matters; a slow per-request or per-row path does. Estimate the input size: O(n²) on n=10 is fine, on n=10⁶ it's fatal. When you claim something is slow, point to the scaling factor (data size or request rate) that makes it bite, and prefer measuring over asserting.
+
+---
+<!-- module: 07-api-design.md -->
+
+# API & Interface Design
+
+Interfaces are contracts; review them for clarity, consistency, and stability.
+
+- **Intent-revealing naming.** Names should say what a thing is or does. Consistent parameter order and return types across a module reduce caller mistakes. A function named `get_user` that sometimes creates one is a lie.
+- **Single responsibility.** A function should do one thing. Be wary of a boolean flag parameter that switches behavior (`render(data, is_admin=True)`). It usually means two functions crammed into one; split them so each name describes exactly what it does.
+- **Predictable return types.** Don't sometimes return a list and sometimes a single item, or `None` on one path and `[]` on another for "nothing." Callers can't handle a type that shifts. Pick one shape (empty collection over `None` is usually kinder) and hold it.
+- **Backward compatibility.** For public/shared interfaces, a changed signature or response shape breaks existing callers. Require additive change or a deprecation path, not a silent breaking change. Watch for a renamed field, a removed parameter, or a newly-required argument.
+- **Fail-fast validation.** Validate arguments at the boundary with clear errors, so bad input is rejected where it enters rather than causing a confusing failure three layers down.
+- **Small, injectable dependencies.** Prefer focused interfaces over god-objects, and pass dependencies in (injectable) rather than reaching for globals: it makes the unit testable and its contract explicit.
+
+When reviewing a new interface, imagine writing a caller against it: is the correct usage obvious, is misuse hard, and will next year's change break me? If any answer is uncomfortable, note it.
+
+Prefer interfaces that make the illegal state unrepresentable: a type or enum that can't hold a bad value beats runtime validation, and a required constructor argument beats a settable field the caller might forget. If a function needs a long comment to explain when to call it or what its return means, that's usually a sign the interface should be reshaped, not documented around.
+
+---
+<!-- module: 08-missing-tests.md -->
+
+# Missing Tests
+
+A change without tests for its risky behavior is incomplete. Reviewing tests is part of reviewing the change, not an afterthought.
+
+**Hunt untested branches.** The happy path is usually covered; the defects hide in what isn't:
+- Error paths: does anything exercise the `except`, the validation rejection, the "not found" case?
+- Boundary inputs: empty, single-element, maximum size, zero, negative, null.
+- The security check that was just added: is there a test proving the unauthorized caller is actually denied?
+
+**Regression tests for fixes.** When a bug is fixed, there should be a test that fails without the fix and passes with it. A fix with no test invites the bug's return and gives no evidence the fix works.
+
+**Judge test quality, not just presence.** A test that runs code but asserts nothing proves only that it doesn't crash. Require assertions on observable behavior: return values, side effects, raised exceptions. Flag:
+- Tests with no meaningful assertion (can't fail).
+- Tests coupled to implementation detail (they break on every refactor and don't validate contract).
+- Mocks of the very unit under test: you end up testing the mock, not the code. Mock external boundaries, not the subject.
+
+**Prioritize.** You won't demand tests for everything. Ask for them where risk is highest and correctness is least obvious: the intricate branching logic, the security boundary, the money calculation, the concurrency-sensitive path. A trivial getter needs less than a permissions check.
+
+When you flag missing coverage, name the specific scenario that's untested and why it matters, for example "no test covers a withdrawal larger than the balance", so the author knows exactly what to add.
+
+---
+<!-- module: 09-refactoring-and-communication.md -->
+
+# Refactoring Strategy & Communicating Findings
+
+## Refactoring safely
+
+Refactor to reduce duplication and complexity, but protect behavior while you do it.
+
+- **Characterize before you change.** Put tests around behavior-critical code before refactoring it, so you can prove behavior didn't change.
+- **One kind of change at a time.** Keep pure refactors (no behavior change) in separate commits from behavior changes. This keeps review honest and lets `git bisect` isolate regressions.
+- **Small, reversible steps:** extract a function, rename for clarity, replace a conditional with polymorphism, introduce a parameter object. Each step should leave the code working.
+- **Watch false duplication.** Don't unify two blocks that only look alike: if they can evolve independently or already differ subtly, merging them couples unrelated things.
+- **Resist scope creep.** Leave code better than you found it, but a refactor that balloons the diff balloons the risk and the review cost. Stay near the change you came to make.
+
+## Severity triage
+
+- **Critical / blocker:** security holes, data loss/corruption, crashes on common input. Must fix before merge.
+- **Major:** correctness bugs on plausible inputs, missing error handling on important paths, significant performance regressions.
+- **Minor:** edge cases, smaller performance issues, missing tests for lower-risk code.
+- **Nit:** style, naming, non-blocking suggestions. Label them so they aren't mistaken for blockers.
+
+## Communicating findings
+
+A finding only matters if it lands.
+- Be specific and cite the line.
+- Explain *why* it's a problem (the failing scenario), not just what to change.
+- Suggest a concrete fix.
+- Separate must-fix from nice-to-have; lead with what matters and don't bury a critical issue under nits.
+- Ask when intent is unclear rather than assuming a mistake; praise good solutions. Review is collaborative, not adversarial.

package/assets/skills/authored/code-review/composable/INDEX.md

@@ -0,0 +1,13 @@
+# Code Review & Refactoring: Mini-Skill Index
+
+Loading policy: read this menu, then load 00-core (if present) plus the minis relevant to your task. If most of this skill is relevant, load BUNDLE.md (or a matching presets/*.md) in one read instead.
+
+- `01-review-method.md` - Mindset, passes, prioritization. Load at the start of any review.
+- `02-security-review.md` - Injection, path traversal, secrets, crypto, authz/IDOR, SSRF. Load when code touches input, storage, or external systems.
+- `03-correctness-bugs.md` - Off-by-one, None handling, coercion, mutable defaults, leaks, money. Load when checking logic correctness.
+- `04-concurrency.md` - Races, shared state, deadlocks, async, TOCTOU. Load when code is threaded, async, or shares state.
+- `05-error-handling.md` - Bare excepts, silent failure, cleanup, transactions. Load when reviewing error paths.
+- `06-performance.md` - N+1, O(n²), unbounded memory, chatty I/O. Load when assessing efficiency.
+- `07-api-design.md` - Naming, single responsibility, compatibility, return types. Load when reviewing interfaces.
+- `08-missing-tests.md` - Untested branches, regression tests, weak tests. Load when assessing test coverage.
+- `09-refactoring-and-communication.md` - Safe refactoring + severity triage and feedback. Load when refactoring or writing up findings.

package/assets/skills/authored/code-review/composable/VERSION

@@ -0,0 +1 @@
+1.0.0

package/assets/skills/authored/code-review/composable/mini/01-review-method.md

@@ -0,0 +1,34 @@
+---
+pairs-with:
+  - 09-refactoring-and-communication.md
+---
+
+# Review Mindset & Method
+
+A review's job is to find the defects that matter and communicate them so they get fixed. Everything else is secondary.
+
+**Read with a threat model.** For the code in front of you, ask: what does it trust? What can an attacker or a buggy caller feed it? What happens when each assumption is false? Bugs live where assumptions meet reality.
+
+**Read enough context.** Review the diff, but read the surrounding code to understand invariants. A change is only correct relative to the contract of the functions it calls and the callers it serves. A line that looks fine in isolation may violate a precondition established elsewhere.
+
+**Work in passes, not one linear read:**
+1. Understand intent and the happy path: what is this trying to do?
+2. Hunt correctness and security defects: where does it break?
+3. Consider concurrency, error handling, and performance.
+4. Assess tests and design: is the change complete and maintainable?
+
+**Prioritize by impact.** A security hole or data-corruption bug outranks a style nit every time. Spend your attention budget on the code that can hurt: input handling, auth, money, state mutation, external calls. Skim boilerplate.
+
+**Reproduce before you report.** For each candidate defect, construct the concrete input or interleaving that triggers it. A finding you can trace to a failing scenario is strong; a vague "this looks risky" is weak and erodes trust in the review.
+
+**Stay collaborative.** Assume competence; ask when intent is unclear rather than assuming a mistake. The goal is better code merged, not a scorecard. Lead with the findings that matter and don't bury a critical issue under a pile of nits.
+
+**A fast sweep to run against any non-trivial change:**
+- Security: untrusted input reaching SQL/shell/templates parameterized? Paths canonicalized and contained? No hardcoded secrets? Strong password hashing, CSPRNG for tokens? Every object access authorized, not just authenticated?
+- Correctness: boundaries (empty/one/last) handled? `None` guarded? No mutable default args? Money in `Decimal`/integers?
+- Concurrency: shared state locked or avoided? Check-then-act atomic? No blocking call in async code?
+- Errors: no bare `except`/silent swallow? Cleanup on every path? Multi-step mutations transactional?
+- Performance: no query/network call in a loop (N+1)? No list-membership tests in hot loops? Large data streamed?
+- Design & tests: interfaces single-purpose and backward-compatible? Risky branches and the new security check covered by meaningful tests, with a regression test for any fix?
+
+Run the sweep, then focus your attention on the two or three areas the change actually touches: the checklist finds candidates, deep reading confirms them.

package/assets/skills/authored/code-review/composable/mini/02-security-review.md

@@ -0,0 +1,20 @@
+---
+pairs-with:
+  - python-api/05-dependencies-and-auth.md
+---
+
+# Security Review
+
+Security bugs are the highest-value finding. Work these categories on any change touching input, storage, or external systems.
+
+**Injection.** Untrusted input reaching an interpreter (SQL, shell, LDAP, XML, template) needs parameterization, not concatenation. Flag `f"SELECT ... WHERE id = {user_id}"` and `execute("... %s" % val)`; require bound parameters: `execute("... WHERE id = %s", (user_id,))`. For shell, flag `os.system` and `subprocess.run(..., shell=True)` with interpolated input; require `shell=False` with an arg list. Watch ORM/NoSQL operators injected via user-controlled dicts.
+
+**Path traversal.** When a path comes from input, `../` can escape the intended directory. Require canonicalization + containment: resolve the real path and verify it's inside the base (`Path.resolve().is_relative_to(base)` or `realpath(p).startswith(base)`). Reject absolute paths and null bytes.
+
+**Secrets.** Flag hardcoded API keys, passwords, tokens, private keys in source, including test fixtures and example configs. Secrets belong in env vars or a secret manager, never the repo or logs. Check that logs and error messages don't echo credentials.
+
+**Crypto.** Flag MD5/SHA-1 for security use and passwords stored with a fast hash or none. Passwords need bcrypt/scrypt/argon2 with per-user salt. Flag ECB mode, static/zero IVs, and reused IVs. Require a CSPRNG (`secrets`, `os.urandom`) for tokens, never `random`. Check TLS verification isn't disabled (`verify=False`).
+
+**AuthN vs AuthZ.** Authentication is who you are; authorization is what you may do. The classic bug (IDOR): an endpoint authenticates the user but never checks the requested object belongs to them. Verify every object access is scoped to the caller's permissions, and that "internal"/admin routes have access control.
+
+**Other high-value checks.** SSRF (server fetching a user-supplied URL: allowlist hosts, block internal ranges); unsafe deserialization (`pickle`, `yaml.load` without `SafeLoader`); open redirects; missing rate limits on auth endpoints. Validate and bound all input at the trust boundary.

package/assets/skills/authored/code-review/composable/mini/03-correctness-bugs.md

@@ -0,0 +1,19 @@
+---
+pairs-with:
+  - 08-missing-tests.md
+---
+
+# Correctness Bugs
+
+These defects make code do the wrong thing on some input. Check each category, and for every candidate construct the concrete triggering input.
+
+- **Off-by-one / boundary:** empty collections, single-element cases, the last index, inclusive vs exclusive ranges. Most boundary bugs hide at size 0 and size 1.
+- **None/null handling:** a value that can be `None` used without a guard; `dict.get()` returning `None` then dereferenced; a function returning `None` on a path the caller doesn't expect.
+- **Type and coercion bugs:** comparing strings to ints, truthiness of `0` / `""` / `[]` mistaken for "missing" (use explicit `is None`), integer vs float division.
+- **Incorrect conditionals:** inverted logic, `and`/`or` precedence, `==` vs `is`, De Morgan mistakes, a `not` binding to the wrong clause.
+- **Mutable default arguments:** `def f(x, acc=[])`: the default is created once and shared across all calls, so it accumulates. Use `None` and initialize inside the function.
+- **Loop and state bugs:** modifying a collection while iterating it; an accumulator reset in the wrong scope; an early `return`/`break` that skips cleanup or a later necessary step.
+- **Resource leaks:** files, sockets, DB connections not closed on every path (including exceptions). Require context managers (`with`).
+- **Floating-point money:** never use binary floats for currency. Rounding errors accumulate. Use integer cents or `Decimal`.
+
+The discipline that separates a strong finding from noise: name the exact input and the wrong output it produces. "This crashes when `items` is empty because line 12 indexes `items[0]`" is actionable; "the loop looks off" is not.

package/assets/skills/authored/code-review/composable/mini/04-concurrency.md

@@ -0,0 +1,16 @@
+---
+pairs-with:
+  - python-api/07-async-performance.md
+---
+
+# Concurrency
+
+Concurrency defects are subtle and rarely covered by tests, so review them deliberately whenever code is threaded, async, or shares state across requests.
+
+- **Race conditions / check-then-act:** `if not exists(k): create(k)` run by two threads can both pass the check and both create. Require atomic operations, locks, or DB-level guarantees: a unique constraint plus `INSERT ... ON CONFLICT`, or a compare-and-swap. Any read-modify-write on shared data is suspect.
+- **Shared mutable state:** module-level dicts, lists, counters, or caches mutated by concurrent requests without a lock. Remember `counter += 1` is not atomic: it's a read, an add, and a write, any of which can interleave. Prefer per-request state or thread-safe structures.
+- **Deadlocks:** two locks acquired in inconsistent order across different code paths. Establish and follow a global lock ordering; hold locks for the shortest span possible.
+- **Async pitfalls:** a blocking call (sync I/O, `time.sleep`, CPU-heavy loop) inside `async` code freezes the whole event loop and stalls every concurrent task. Also flag a forgotten `await` (the coroutine never runs), and task exceptions that are swallowed because no one awaits the task.
+- **TOCTOU on the filesystem:** check-then-use races, such as `if os.path.exists(p): open(p)`, where the file changes between the two calls. Prefer a single atomic operation (open with the right flags, `O_CREAT|O_EXCL`) over stat-then-open.
+
+Because these bugs surface only under specific interleavings, reason about "what if two callers hit this simultaneously" for every piece of shared state, rather than relying on tests to catch them. A useful mental model: mark every read-modify-write on shared data, then ask whether another thread could slip between the read and the write. If it could, and the outcome would be wrong, you have a race that needs a lock, an atomic primitive, or a database-level guarantee.

package/assets/skills/authored/code-review/composable/mini/05-error-handling.md

@@ -0,0 +1,12 @@
+# Error Handling
+
+Good error handling is about failing safely and visibly, never silently.
+
+- **Bare and blanket excepts.** Flag `except:` and `except Exception: pass`. They hide bugs and turn failures into silent wrong behavior. Catch the specific exceptions you can handle; log or re-raise the rest.
+- **Silent failure via sentinels.** Don't swallow an error and return a sentinel (`None`, `-1`, `[]`, `False`) that callers treat as success. If you can't handle it, fail loudly. If you return a sentinel, make sure every caller checks it.
+- **Cleanup on every path.** Files, locks, connections, and transactions must be released whether the code succeeds or raises. Use `finally` or context managers rather than duplicating cleanup before each `return`: the duplicated version always misses a path.
+- **Message hygiene.** Error messages should aid debugging without leaking internals to end users: log the detail (stack trace, ids) server-side, return a generic message to the client. Don't echo secrets, SQL, or file paths.
+- **Consistent state on partial failure.** A multi-step mutation that fails halfway can leave data inconsistent. Wrap it in a transaction and roll back on error, or design idempotent/compensating steps. Verify the code doesn't commit step 1, then throw on step 2.
+- **Don't lose context.** Catching an exception only to raise a vaguer one discards the stack and the root cause. Chain exceptions (`raise NewError(...) from exc`) or let the original propagate.
+
+The core question for any `try` block: if this raises, does the system end up in a known-good state, and will someone find out it happened? If either answer is no, it's a finding.

package/assets/skills/authored/code-review/composable/mini/06-performance.md

@@ -0,0 +1,11 @@
+# Performance
+
+Focus on algorithmic and I/O issues that scale badly with data or load. Ignore micro-optimizations that don't move the needle.
+
+- **N+1 queries.** A database (or network) call inside a loop over rows is the most common real-world performance bug: 1 query to list, then N to fetch each item's detail. Batch it into one query, or eager-load the relationship. Spotting a `.get`/`.query`/`fetch` inside a `for` loop is a red flag.
+- **Accidental O(n²).** Membership tests against a list inside a loop (`if x in big_list`) turn linear work quadratic. Use a `set`/`dict` for O(1) lookup. Watch nested loops over the same large collection, and invariant work recomputed each iteration that could be hoisted out.
+- **Unbounded memory.** Loading an entire large file or result set into memory (`f.read()`, `.all()` on a huge table) risks OOM. Stream, chunk, or paginate instead.
+- **Missing indexes / full scans.** Query patterns filtering or joining on unindexed columns imply table scans. Repeated identical queries that should be cached also count.
+- **Chatty I/O.** Many small network or disk calls that could be batched; a new connection per call instead of a reused pooled client.
+
+Discipline: **distinguish hot paths from cold.** A slow one-time startup step rarely matters; a slow per-request or per-row path does. Estimate the input size: O(n²) on n=10 is fine, on n=10⁶ it's fatal. When you claim something is slow, point to the scaling factor (data size or request rate) that makes it bite, and prefer measuring over asserting.

package/assets/skills/authored/code-review/composable/mini/07-api-design.md

@@ -0,0 +1,20 @@
+---
+pairs-with:
+  - python-api/02-routing-and-app.md
+  - tech-writing/06-breaking-changes-migrations.md
+---
+
+# API & Interface Design
+
+Interfaces are contracts; review them for clarity, consistency, and stability.
+
+- **Intent-revealing naming.** Names should say what a thing is or does. Consistent parameter order and return types across a module reduce caller mistakes. A function named `get_user` that sometimes creates one is a lie.
+- **Single responsibility.** A function should do one thing. Be wary of a boolean flag parameter that switches behavior (`render(data, is_admin=True)`). It usually means two functions crammed into one; split them so each name describes exactly what it does.
+- **Predictable return types.** Don't sometimes return a list and sometimes a single item, or `None` on one path and `[]` on another for "nothing." Callers can't handle a type that shifts. Pick one shape (empty collection over `None` is usually kinder) and hold it.
+- **Backward compatibility.** For public/shared interfaces, a changed signature or response shape breaks existing callers. Require additive change or a deprecation path, not a silent breaking change. Watch for a renamed field, a removed parameter, or a newly-required argument.
+- **Fail-fast validation.** Validate arguments at the boundary with clear errors, so bad input is rejected where it enters rather than causing a confusing failure three layers down.
+- **Small, injectable dependencies.** Prefer focused interfaces over god-objects, and pass dependencies in (injectable) rather than reaching for globals: it makes the unit testable and its contract explicit.
+
+When reviewing a new interface, imagine writing a caller against it: is the correct usage obvious, is misuse hard, and will next year's change break me? If any answer is uncomfortable, note it.
+
+Prefer interfaces that make the illegal state unrepresentable: a type or enum that can't hold a bad value beats runtime validation, and a required constructor argument beats a settable field the caller might forget. If a function needs a long comment to explain when to call it or what its return means, that's usually a sign the interface should be reshaped, not documented around.

package/assets/skills/authored/code-review/composable/mini/08-missing-tests.md

@@ -0,0 +1,25 @@
+---
+pairs-with:
+  - 03-correctness-bugs.md
+  - python-api/08-testing.md
+---
+
+# Missing Tests
+
+A change without tests for its risky behavior is incomplete. Reviewing tests is part of reviewing the change, not an afterthought.
+
+**Hunt untested branches.** The happy path is usually covered; the defects hide in what isn't:
+- Error paths: does anything exercise the `except`, the validation rejection, the "not found" case?
+- Boundary inputs: empty, single-element, maximum size, zero, negative, null.
+- The security check that was just added: is there a test proving the unauthorized caller is actually denied?
+
+**Regression tests for fixes.** When a bug is fixed, there should be a test that fails without the fix and passes with it. A fix with no test invites the bug's return and gives no evidence the fix works.
+
+**Judge test quality, not just presence.** A test that runs code but asserts nothing proves only that it doesn't crash. Require assertions on observable behavior: return values, side effects, raised exceptions. Flag:
+- Tests with no meaningful assertion (can't fail).
+- Tests coupled to implementation detail (they break on every refactor and don't validate contract).
+- Mocks of the very unit under test: you end up testing the mock, not the code. Mock external boundaries, not the subject.
+
+**Prioritize.** You won't demand tests for everything. Ask for them where risk is highest and correctness is least obvious: the intricate branching logic, the security boundary, the money calculation, the concurrency-sensitive path. A trivial getter needs less than a permissions check.
+
+When you flag missing coverage, name the specific scenario that's untested and why it matters, for example "no test covers a withdrawal larger than the balance", so the author knows exactly what to add.

package/assets/skills/authored/code-review/composable/mini/09-refactoring-and-communication.md

@@ -0,0 +1,32 @@
+---
+pairs-with:
+  - 01-review-method.md
+---
+
+# Refactoring Strategy & Communicating Findings
+
+## Refactoring safely
+
+Refactor to reduce duplication and complexity, but protect behavior while you do it.
+
+- **Characterize before you change.** Put tests around behavior-critical code before refactoring it, so you can prove behavior didn't change.
+- **One kind of change at a time.** Keep pure refactors (no behavior change) in separate commits from behavior changes. This keeps review honest and lets `git bisect` isolate regressions.
+- **Small, reversible steps:** extract a function, rename for clarity, replace a conditional with polymorphism, introduce a parameter object. Each step should leave the code working.
+- **Watch false duplication.** Don't unify two blocks that only look alike: if they can evolve independently or already differ subtly, merging them couples unrelated things.
+- **Resist scope creep.** Leave code better than you found it, but a refactor that balloons the diff balloons the risk and the review cost. Stay near the change you came to make.
+
+## Severity triage
+
+- **Critical / blocker:** security holes, data loss/corruption, crashes on common input. Must fix before merge.
+- **Major:** correctness bugs on plausible inputs, missing error handling on important paths, significant performance regressions.
+- **Minor:** edge cases, smaller performance issues, missing tests for lower-risk code.
+- **Nit:** style, naming, non-blocking suggestions. Label them so they aren't mistaken for blockers.
+
+## Communicating findings
+
+A finding only matters if it lands.
+- Be specific and cite the line.
+- Explain *why* it's a problem (the failing scenario), not just what to change.
+- Suggest a concrete fix.
+- Separate must-fix from nice-to-have; lead with what matters and don't bury a critical issue under nits.
+- Ask when intent is unclear rather than assuming a mistake; praise good solutions. Review is collaborative, not adversarial.