[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M75DNMSTXVN0JT8CSXMW7SCB":3,"skill-same:01M75DNMSTXVN0JT8CSXMW7SCB":45},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":19,"linkOnly":20,"markdownContent":21,"markdownBody":22,"frontMatter":23,"refName":25,"commitSha":26,"skillDirectory":27,"forksCount":28,"repositoryHtmlUrl":29,"repositoryHomepageUrl":6,"ownerHtmlUrl":30,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":31,"install":32,"resources":44},"01M75DNMSTXVN0JT8CSXMW7SCB","code-review",null,"Review changed code against project standards. Checks for missing tests, dead code, type safety, lint issues, and coding conventions. Run after completing any implementation work.","zhangmask\u002FC_AnimeCompanion","zhangmask","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F142085030?v=4","01M75DE4RMVR0PZNRT2CHBNB1K","Zeshan Zhang","01M75DE4SE8VQSYG2PMV66F3PE",2,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fhindsight-main\u002Fhindsight-main\u002F.claude\u002Fskills\u002Fcode-review\u002FSKILL.md",[],[],"2026-11-12 13:55:43",false,"---\nname: code-review\ndescription: Review changed code against project standards. Checks for missing tests, dead code, type safety, lint issues, and coding conventions. Run after completing any implementation work.\nuser_invocable: true\n---\n\n# Code Review\n\nReview all changed code against the project's quality standards and coding conventions.\n\n## Code Standards\n\nRead and internalize these standards before writing code. The review steps below verify compliance.\n\n### Python Style\n- Python 3.11+, type hints required\n- Async throughout (asyncpg, async FastAPI)\n- Pydantic models for request\u002Fresponse\n- Ruff for linting (line-length 120)\n- No Python files at project root - maintain clean directory structure\n- **Never use multi-item tuple return values** — not even for internal\u002Fprivate functions. Always use a dataclass or Pydantic model. No exceptions, no \"it's just two values\" shortcuts. If a function returns more than one value, define a named type for it.\n\n### Type Safety with Pydantic Models\n**NEVER use raw `dict` types for structured data** — this applies to all code, including internal helpers and private functions. If the dict has known keys, it must be a dataclass or Pydantic model:\n- Use Pydantic `BaseModel` for all data structures passed between functions\n- Use `@dataclass` for lightweight internal data containers when Pydantic validation isn't needed\n- Add `@field_validator` for type coercion (e.g., ensuring datetimes are timezone-aware)\n- Avoid `dict.get()` patterns - use typed model attributes instead\n- Parse external data (JSON, API responses) into Pydantic models at the boundary\n- This catches type errors at parse time, not deep in business logic\n- The only acceptable `dict` usage is for truly dynamic\u002Funknown keys (e.g., arbitrary metadata, JSON blobs with no fixed schema)\n\n```python\n# BAD - error-prone dict access\ndef process(data: dict) -> str:\n    return data.get(\"name\", \"\")  # No validation, silent failures\n\n# GOOD - typed and validated\nclass UserData(BaseModel):\n    name: str\n    created_at: datetime\n\n    @field_validator(\"created_at\", mode=\"before\")\n    @classmethod\n    def ensure_tz_aware(cls, v):\n        if isinstance(v, str):\n            v = datetime.fromisoformat(v.replace(\"Z\", \"+00:00\"))\n        if v.tzinfo is None:\n            return v.replace(tzinfo=timezone.utc)\n        return v\n\ndef process(data: UserData) -> str:\n    return data.name  # Type-safe, validated at construction\n```\n\n### TypeScript Style\n- Next.js App Router for control plane\n- Tailwind CSS with shadcn\u002Fui components\n\n### Code Comments\n- **Always comment non-trivial technical decisions** with the reasoning behind the choice. If someone would ask \"why is it done this way?\", there should be a comment.\n- **Keep comments up to date with history** — when changing an approach, update the comment to explain what was tried before and why it was changed. Comments serve as a tracker of previous implementations that likely had problems.\n- Don't comment obvious code — only where the \"why\" isn't self-evident from the code itself.\n\n```python\n# BAD - no context for future readers\nresults = await asyncio.gather(*tasks, return_exceptions=True)\n\n# GOOD - explains the non-obvious choice\n# Use return_exceptions=True to avoid cancelling sibling tasks on failure.\n# Previously we used TaskGroup but it cancelled all tasks when one failed,\n# causing partial writes that left orphaned entity links (see #412).\nresults = await asyncio.gather(*tasks, return_exceptions=True)\n```\n\n### API Layer & Data Access\n- **No direct database access in `api\u002Fhttp.py`** (or any API router). HTTP handlers must not build SQL, call `acquire_with_retry` \u002F `conn.fetch` \u002F `conn.fetchrow` \u002F `conn.execute`, or reference `fq_table(...)`. All persistence and queries live in `MemoryEngine` (the engine layer). A handler parses\u002Fvalidates the request, calls an engine method, shapes the HTTP response, and maps domain results to status codes (e.g. a `None` return → 404).\n- **Authentication\u002Ftenancy is enforced inside each engine method, not assumed by the handler.** Every engine method that touches bank-scoped data must authenticate via `request_context` — typically `await self._authenticate_tenant(request_context)` (often indirectly through `get_bank_profile(...)`) — so the correct tenant schema is resolved before any query runs. Handlers must thread `request_context` through to the engine method; never query a tenant-scoped table assuming the schema is already set.\n- Engine methods return typed models (Pydantic\u002Fdataclass), not raw dicts (see Type Safety).\n\n### Branch Hygiene\n- **Always start new feature branches from `origin\u002Fmain`** — rebase to ensure a clean base.\n- **Only include commits relevant to the PR\u002Fbranch\u002Ffeature** — no unrelated changes. If the branch contains commits that don't belong, they must be removed before merging.\n\n### General Principles\n- Don't add features, refactor code, or make \"improvements\" beyond what was asked\n- Don't add unnecessary error handling for impossible scenarios\n- Don't create helpers or abstractions for one-time operations\n- No backwards-compatibility hacks (unused vars, re-exports, \"removed\" comments)\n- Three similar lines of code is better than a premature abstraction\n\n## Review Steps\n\n### 1. Check branch hygiene\n\n- Run `git log --oneline main..HEAD` to list all commits on the branch.\n- Verify every commit is relevant to the feature\u002FPR. Flag any unrelated commits.\n- Check the branch is based on a recent `origin\u002Fmain` (no stale base).\n\n### 2. Identify changed files\n\nRun `git diff --name-only HEAD` (unstaged) and `git diff --cached --name-only` (staged) to get all changed files. If there are no local changes, diff against the base branch using `git diff main...HEAD --name-only` and `git diff main...HEAD` to review all commits on the current branch.\n\n### 3. Run linters\n\n```bash\n.\u002Fscripts\u002Fhooks\u002Flint.sh\n```\n\nReport any failures. Do NOT fix them yourself — just report.\n\n### 4. Check for dead code\n\nFor each changed Python file, check for:\n- Unused imports (Ruff should catch these, but verify)\n- Functions\u002Fmethods\u002Fclasses that were added but are never called from anywhere\n- Variables assigned but never read\n- Commented-out code blocks that should be removed\n\nFor each changed TypeScript file, check for:\n- Unused imports\n- Unused variables or functions\n- Commented-out code\n\n### 5. Check type safety (Python)\n\nFor each changed Python file, check for violations:\n- **No raw `dict` for structured data** — must use Pydantic model or dataclass, even for internal\u002Fprivate functions (only exception: truly dynamic\u002Funknown keys)\n- **No multi-item tuple returns** — must use dataclass or Pydantic model, even for internal\u002Fprivate functions (no exceptions)\n- **Missing type hints** on function parameters and return types\n- **Missing `@field_validator`** for datetime fields that should be timezone-aware\n\n### 6. Check for missing tests\n\nFor each new or significantly changed function\u002Fendpoint\u002Fclass:\n- Check if there is a corresponding test addition or update\n- New API endpoints MUST have integration tests\n- New utility functions MUST have unit tests\n- Bug fixes SHOULD have a regression test\n\nFlag any new logic that lacks test coverage.\n\n**LLM-behaviour changes need a real-LLM judge test, not MockLLM.** If the change alters how the model interprets a prompt — fact\u002Fobservation extraction, `fact_type` (world\u002Fexperience) classification, speaker attribution, instruction-following, prompt wording — there MUST be a test marked `pytest.mark.hs_llm_core` that runs the real pipeline and asserts via `tests.llm_judge.assert_meets_criteria` (not string\u002Fenum matching). Flag these as findings:\n- A prompt\u002Fclassification change verified only by MockLLM or string assertions (MockLLM echoes input — such tests pass spuriously). **Should fix.**\n- A test that hard-asserts `fact_type == \"world\"\u002F\"experience\"` (or other model-decided output) instead of judging it — non-deterministic, will flake across providers\u002Fruns. **Should fix** (move the classification check into the judge `criteria`; keep only genuinely deterministic structural asserts direct).\n- Deterministic mechanics (prompt assembly, suppression\u002Fbranching logic) that are covered *only* by a slow LLM test — these should also have fast non-LLM unit tests. **Note.**\n\nSee CLAUDE.md → Key Conventions → Testing for the full pattern.\n\n### 7. Check API consistency\n\nIf any files in `hindsight-api-slim\u002Fhindsight_api\u002Fapi\u002F` were changed:\n- Were the OpenAPI specs regenerated? (`.\u002Fscripts\u002Fgenerate-openapi.sh`)\n- Were the client SDKs regenerated? (`.\u002Fscripts\u002Fgenerate-clients.sh`)\n- Were the control plane proxy routes updated? (`hindsight-control-plane\u002Fsrc\u002Fapp\u002Fapi\u002F`)\n\n### 7b. Check API-layer data-access boundary\n\nFor each changed handler in `hindsight-api-slim\u002Fhindsight_api\u002Fapi\u002F` (e.g. `http.py`, `mcp.py`):\n- **Flag any direct DB access in the handler** — `acquire_with_retry`, `conn.fetch` \u002F `fetchrow` \u002F `execute`, raw SQL strings, or `fq_table(...)`. These are a **must fix**: the query must be moved into a `MemoryEngine` method that returns a typed model, and the handler must call that method.\n- **Verify authentication is enforced in the engine** — the handler must delegate to an engine method that authenticates via `request_context` (`_authenticate_tenant`, typically through `get_bank_profile`). A handler that reads\u002Fwrites tenant-scoped data without an engine method enforcing auth is a **must fix** (tenant data could leak across schemas).\n\n### 8. Check code comments\n\nFor each non-trivial change:\n- **New non-obvious logic** — is there a comment explaining the reasoning?\n- **Changed approach** — does the comment include what was done before and why it changed?\n- **Stale comments** — do existing comments near the changed code still accurately describe the behavior?\n\n### 9. Check integration completeness\n\nIf any files in `hindsight-integrations\u002F` were added or changed, verify:\n- **Tests exist** — the integration must have tests that simulate\u002Fexercise the external framework (not just pure unit tests of helpers). Check for a `tests\u002F` directory with meaningful test files.\n- **CI job exists** — check `.github\u002Fworkflows\u002Ftest.yml` for a corresponding `test-\u003Cname>-integration` job. If missing, flag it.\n- **Release process** — check that the integration name is in the `VALID_INTEGRATIONS` array in `scripts\u002Frelease-integration.sh` AND in the `INTEGRATIONS` dict in `hindsight-dev\u002Fhindsight_dev\u002Fgenerate_changelog.py` (the changelog generator keeps its own list; a release fails at the changelog step if the name is missing there). If either is missing, flag it.\n- **Docs gallery + sidebar entry** — the integration must have an entry in `hindsight-docs\u002Fsrc\u002Fdata\u002Fintegrations.json`. This file is the **single source of truth** that drives both the integrations gallery and the docs sidebar (the sidebar category is injected from it at render time across all docs versions). The entry needs an internal `\u002Fsdks\u002Fintegrations\u002F\u003Cslug>` `link` and a matching page at `hindsight-docs\u002Fdocs-integrations\u002F\u003Cslug>.md(x)`. The `hindsight-docs\u002Fscripts\u002Fcheck-integrations.mjs` build step enforces both directions — forward: every internal JSON entry has a doc page; reverse: every released tag (`integrations\u002F\u003Cname>\u002FvX.Y.Z`) appears in the JSON (private infra like `cloudflare-oauth-proxy` is in the script's `EXCLUDED` set). Flag any integration that is released (or being released) but missing from `integrations.json`, and any JSON entry without a doc page. Do **not** hand-edit `versioned_sidebars\u002F*.json` to add integration links — they are positional placeholders filled from the JSON.\n- **Code standards** — the integration code must follow all Python style rules (type hints, no raw dicts, no tuple returns, etc.).\n\n### 10. Check MCP tool registration completeness\n\nIf any new MCP tools were added or existing tools renamed in `hindsight-api-slim\u002Fhindsight_api\u002Fmcp_tools.py`:\n- **`_ALL_TOOLS` set** in `mcp_tools.py` — must include the new tool name\n- **`tools_to_register` default set** in `register_mcp_tools()` in `mcp_tools.py` — must include the new tool name\n- **`_SINGLE_BANK_TOOLS` set** in `hindsight-api-slim\u002Fhindsight_api\u002Fapi\u002Fmcp.py` — must include the new tool if it is bank-scoped (not a bank-management tool like `list_banks`\u002F`create_bank`)\n- **`MCP_TOOL_GROUPS`** in `hindsight-control-plane\u002Fsrc\u002Fcomponents\u002Fbank-config-view.tsx` — must include the new tool in the appropriate group for the UI tool selector\n- **Tool count assertions** in tests (e.g., `test_mcp_tools.py`) — must be updated to reflect the new count\n\n### 11. Check backup\u002Frestore table coverage\n\nIf a migration adds a new PostgreSQL table (look for `CREATE TABLE` \u002F `op.create_table` in `hindsight-api-slim\u002Fhindsight_api\u002Falembic\u002Fversions\u002F`):\n- **`BACKUP_TABLES`** in `hindsight-api-slim\u002Fhindsight_api\u002Fadmin\u002Fcli.py` — must include the new table, placed after any table it references via foreign key (parents before children). A missing entry is silent data loss: the table is never backed up, and restore's `TRUNCATE banks CASCADE` wipes any FK-to-banks child (e.g. `mental_models`, `directives`) on restore even though it was never saved.\n- The guard test `test_backup_tables_covers_entire_schema` in `tests\u002Ftest_admin_backup_restore.py` enforces this — flag it as a **must fix** if a new table is absent from `BACKUP_TABLES`.\n- Oracle-only tables (e.g. `observation_sources`) are intentionally excluded — admin backup\u002Frestore is PostgreSQL-only.\n\n### 11b. Check new config flags update the env template\n\nIf the diff adds a new configuration field (a new `ENV_*` \u002F `HINDSIGHT_*` env var\nin `hindsight-api-slim\u002Fhindsight_api\u002Fconfig.py`):\n- **`.env.example`** (repo root) — must add the variable (commented if optional)\n  alongside the docs entry in `hindsight-docs\u002Fdocs\u002Fdeveloper\u002Fconfiguration.md`.\n  A flag added to `config.py` but absent from `.env.example` is a **should fix**.\n- **`hindsight-embed\u002Fhindsight_embed\u002Fenv.example`** — the bundled copy must stay\n  byte-identical to the repo-root `.env.example` (it seeds embed\u002Fprofile configs).\n  The `test_bundled_template_matches_repo_root` sync test fails on drift; if the\n  root file changed without re-copying, flag it as a **must fix**.\n\n### 12. Review against other coding standards\n\nCheck the diff for violations of the standards listed above:\n- Python files at project root (not allowed)\n- Missing async patterns (should be async throughout)\n- Pydantic models for request\u002Fresponse\n- Line length > 120 chars\n- New features\u002Fcode beyond what was asked (over-engineering)\n- Unnecessary error handling for impossible scenarios\n- Premature abstractions or speculative helpers\n- Backwards-compatibility hacks (unused vars, re-exports, \"removed\" comments)\n\n### 13. Report findings\n\nPresent a clear summary organized by severity:\n\n**Must fix** — issues that will break CI or violate hard project rules:\n- Unrelated commits on the branch\n- Lint failures\n- Missing type hints on public functions\n- Raw dict usage for structured data (including internal code)\n- Multi-item tuple returns (including internal code)\n- Missing tests for new endpoints\n- Direct DB access (raw SQL \u002F `acquire_with_retry` \u002F `fq_table`) in an `api\u002F` handler instead of a `MemoryEngine` method\n- Tenant-scoped data accessed without authentication enforced in the engine (`_authenticate_tenant` \u002F `get_bank_profile`)\n- New integration missing tests, CI job, or release-integration.sh entry\n- Released\u002Fadded integration missing from `hindsight-docs\u002Fsrc\u002Fdata\u002Fintegrations.json`, or a JSON entry with no `docs-integrations\u002F\u003Cslug>` page (fails the docs build via `check-integrations.mjs`)\n- New PostgreSQL table missing from `BACKUP_TABLES` in `admin\u002Fcli.py` (silent data loss on restore)\n\n**Should fix** — issues that hurt code quality:\n- Dead code \u002F unused imports missed by linter\n- Missing tests for non-trivial utility functions\n- Over-engineering beyond the task scope\n\n**Note** — observations that may or may not need action:\n- API changes that might need client regeneration\n- Patterns that deviate from nearby code style\n\nFor each finding, include the file path, line number, and a brief explanation.\n\nDo NOT auto-fix any issues. Report all findings and let the user decide what to address. If there are no findings, confirm the code looks good.\n","# Code Review\n\nReview all changed code against the project's quality standards and coding conventions.\n\n## Code Standards\n\nRead and internalize these standards before writing code. The review steps below verify compliance.\n\n### Python Style\n- Python 3.11+, type hints required\n- Async throughout (asyncpg, async FastAPI)\n- Pydantic models for request\u002Fresponse\n- Ruff for linting (line-length 120)\n- No Python files at project root - maintain clean directory structure\n- **Never use multi-item tuple return values** — not even for internal\u002Fprivate functions. Always use a dataclass or Pydantic model. No exceptions, no \"it's just two values\" shortcuts. If a function returns more than one value, define a named type for it.\n\n### Type Safety with Pydantic Models\n**NEVER use raw `dict` types for structured data** — this applies to all code, including internal helpers and private functions. If the dict has known keys, it must be a dataclass or Pydantic model:\n- Use Pydantic `BaseModel` for all data structures passed between functions\n- Use `@dataclass` for lightweight internal data containers when Pydantic validation isn't needed\n- Add `@field_validator` for type coercion (e.g., ensuring datetimes are timezone-aware)\n- Avoid `dict.get()` patterns - use typed model attributes instead\n- Parse external data (JSON, API responses) into Pydantic models at the boundary\n- This catches type errors at parse time, not deep in business logic\n- The only acceptable `dict` usage is for truly dynamic\u002Funknown keys (e.g., arbitrary metadata, JSON blobs with no fixed schema)\n\n```python\n# BAD - error-prone dict access\ndef process(data: dict) -> str:\n    return data.get(\"name\", \"\")  # No validation, silent failures\n\n# GOOD - typed and validated\nclass UserData(BaseModel):\n    name: str\n    created_at: datetime\n\n    @field_validator(\"created_at\", mode=\"before\")\n    @classmethod\n    def ensure_tz_aware(cls, v):\n        if isinstance(v, str):\n            v = datetime.fromisoformat(v.replace(\"Z\", \"+00:00\"))\n        if v.tzinfo is None:\n            return v.replace(tzinfo=timezone.utc)\n        return v\n\ndef process(data: UserData) -> str:\n    return data.name  # Type-safe, validated at construction\n```\n\n### TypeScript Style\n- Next.js App Router for control plane\n- Tailwind CSS with shadcn\u002Fui components\n\n### Code Comments\n- **Always comment non-trivial technical decisions** with the reasoning behind the choice. If someone would ask \"why is it done this way?\", there should be a comment.\n- **Keep comments up to date with history** — when changing an approach, update the comment to explain what was tried before and why it was changed. Comments serve as a tracker of previous implementations that likely had problems.\n- Don't comment obvious code — only where the \"why\" isn't self-evident from the code itself.\n\n```python\n# BAD - no context for future readers\nresults = await asyncio.gather(*tasks, return_exceptions=True)\n\n# GOOD - explains the non-obvious choice\n# Use return_exceptions=True to avoid cancelling sibling tasks on failure.\n# Previously we used TaskGroup but it cancelled all tasks when one failed,\n# causing partial writes that left orphaned entity links (see #412).\nresults = await asyncio.gather(*tasks, return_exceptions=True)\n```\n\n### API Layer & Data Access\n- **No direct database access in `api\u002Fhttp.py`** (or any API router). HTTP handlers must not build SQL, call `acquire_with_retry` \u002F `conn.fetch` \u002F `conn.fetchrow` \u002F `conn.execute`, or reference `fq_table(...)`. All persistence and queries live in `MemoryEngine` (the engine layer). A handler parses\u002Fvalidates the request, calls an engine method, shapes the HTTP response, and maps domain results to status codes (e.g. a `None` return → 404).\n- **Authentication\u002Ftenancy is enforced inside each engine method, not assumed by the handler.** Every engine method that touches bank-scoped data must authenticate via `request_context` — typically `await self._authenticate_tenant(request_context)` (often indirectly through `get_bank_profile(...)`) — so the correct tenant schema is resolved before any query runs. Handlers must thread `request_context` through to the engine method; never query a tenant-scoped table assuming the schema is already set.\n- Engine methods return typed models (Pydantic\u002Fdataclass), not raw dicts (see Type Safety).\n\n### Branch Hygiene\n- **Always start new feature branches from `origin\u002Fmain`** — rebase to ensure a clean base.\n- **Only include commits relevant to the PR\u002Fbranch\u002Ffeature** — no unrelated changes. If the branch contains commits that don't belong, they must be removed before merging.\n\n### General Principles\n- Don't add features, refactor code, or make \"improvements\" beyond what was asked\n- Don't add unnecessary error handling for impossible scenarios\n- Don't create helpers or abstractions for one-time operations\n- No backwards-compatibility hacks (unused vars, re-exports, \"removed\" comments)\n- Three similar lines of code is better than a premature abstraction\n\n## Review Steps\n\n### 1. Check branch hygiene\n\n- Run `git log --oneline main..HEAD` to list all commits on the branch.\n- Verify every commit is relevant to the feature\u002FPR. Flag any unrelated commits.\n- Check the branch is based on a recent `origin\u002Fmain` (no stale base).\n\n### 2. Identify changed files\n\nRun `git diff --name-only HEAD` (unstaged) and `git diff --cached --name-only` (staged) to get all changed files. If there are no local changes, diff against the base branch using `git diff main...HEAD --name-only` and `git diff main...HEAD` to review all commits on the current branch.\n\n### 3. Run linters\n\n```bash\n.\u002Fscripts\u002Fhooks\u002Flint.sh\n```\n\nReport any failures. Do NOT fix them yourself — just report.\n\n### 4. Check for dead code\n\nFor each changed Python file, check for:\n- Unused imports (Ruff should catch these, but verify)\n- Functions\u002Fmethods\u002Fclasses that were added but are never called from anywhere\n- Variables assigned but never read\n- Commented-out code blocks that should be removed\n\nFor each changed TypeScript file, check for:\n- Unused imports\n- Unused variables or functions\n- Commented-out code\n\n### 5. Check type safety (Python)\n\nFor each changed Python file, check for violations:\n- **No raw `dict` for structured data** — must use Pydantic model or dataclass, even for internal\u002Fprivate functions (only exception: truly dynamic\u002Funknown keys)\n- **No multi-item tuple returns** — must use dataclass or Pydantic model, even for internal\u002Fprivate functions (no exceptions)\n- **Missing type hints** on function parameters and return types\n- **Missing `@field_validator`** for datetime fields that should be timezone-aware\n\n### 6. Check for missing tests\n\nFor each new or significantly changed function\u002Fendpoint\u002Fclass:\n- Check if there is a corresponding test addition or update\n- New API endpoints MUST have integration tests\n- New utility functions MUST have unit tests\n- Bug fixes SHOULD have a regression test\n\nFlag any new logic that lacks test coverage.\n\n**LLM-behaviour changes need a real-LLM judge test, not MockLLM.** If the change alters how the model interprets a prompt — fact\u002Fobservation extraction, `fact_type` (world\u002Fexperience) classification, speaker attribution, instruction-following, prompt wording — there MUST be a test marked `pytest.mark.hs_llm_core` that runs the real pipeline and asserts via `tests.llm_judge.assert_meets_criteria` (not string\u002Fenum matching). Flag these as findings:\n- A prompt\u002Fclassification change verified only by MockLLM or string assertions (MockLLM echoes input — such tests pass spuriously). **Should fix.**\n- A test that hard-asserts `fact_type == \"world\"\u002F\"experience\"` (or other model-decided output) instead of judging it — non-deterministic, will flake across providers\u002Fruns. **Should fix** (move the classification check into the judge `criteria`; keep only genuinely deterministic structural asserts direct).\n- Deterministic mechanics (prompt assembly, suppression\u002Fbranching logic) that are covered *only* by a slow LLM test — these should also have fast non-LLM unit tests. **Note.**\n\nSee CLAUDE.md → Key Conventions → Testing for the full pattern.\n\n### 7. Check API consistency\n\nIf any files in `hindsight-api-slim\u002Fhindsight_api\u002Fapi\u002F` were changed:\n- Were the OpenAPI specs regenerated? (`.\u002Fscripts\u002Fgenerate-openapi.sh`)\n- Were the client SDKs regenerated? (`.\u002Fscripts\u002Fgenerate-clients.sh`)\n- Were the control plane proxy routes updated? (`hindsight-control-plane\u002Fsrc\u002Fapp\u002Fapi\u002F`)\n\n### 7b. Check API-layer data-access boundary\n\nFor each changed handler in `hindsight-api-slim\u002Fhindsight_api\u002Fapi\u002F` (e.g. `http.py`, `mcp.py`):\n- **Flag any direct DB access in the handler** — `acquire_with_retry`, `conn.fetch` \u002F `fetchrow` \u002F `execute`, raw SQL strings, or `fq_table(...)`. These are a **must fix**: the query must be moved into a `MemoryEngine` method that returns a typed model, and the handler must call that method.\n- **Verify authentication is enforced in the engine** — the handler must delegate to an engine method that authenticates via `request_context` (`_authenticate_tenant`, typically through `get_bank_profile`). A handler that reads\u002Fwrites tenant-scoped data without an engine method enforcing auth is a **must fix** (tenant data could leak across schemas).\n\n### 8. Check code comments\n\nFor each non-trivial change:\n- **New non-obvious logic** — is there a comment explaining the reasoning?\n- **Changed approach** — does the comment include what was done before and why it changed?\n- **Stale comments** — do existing comments near the changed code still accurately describe the behavior?\n\n### 9. Check integration completeness\n\nIf any files in `hindsight-integrations\u002F` were added or changed, verify:\n- **Tests exist** — the integration must have tests that simulate\u002Fexercise the external framework (not just pure unit tests of helpers). Check for a `tests\u002F` directory with meaningful test files.\n- **CI job exists** — check `.github\u002Fworkflows\u002Ftest.yml` for a corresponding `test-\u003Cname>-integration` job. If missing, flag it.\n- **Release process** — check that the integration name is in the `VALID_INTEGRATIONS` array in `scripts\u002Frelease-integration.sh` AND in the `INTEGRATIONS` dict in `hindsight-dev\u002Fhindsight_dev\u002Fgenerate_changelog.py` (the changelog generator keeps its own list; a release fails at the changelog step if the name is missing there). If either is missing, flag it.\n- **Docs gallery + sidebar entry** — the integration must have an entry in `hindsight-docs\u002Fsrc\u002Fdata\u002Fintegrations.json`. This file is the **single source of truth** that drives both the integrations gallery and the docs sidebar (the sidebar category is injected from it at render time across all docs versions). The entry needs an internal `\u002Fsdks\u002Fintegrations\u002F\u003Cslug>` `link` and a matching page at `hindsight-docs\u002Fdocs-integrations\u002F\u003Cslug>.md(x)`. The `hindsight-docs\u002Fscripts\u002Fcheck-integrations.mjs` build step enforces both directions — forward: every internal JSON entry has a doc page; reverse: every released tag (`integrations\u002F\u003Cname>\u002FvX.Y.Z`) appears in the JSON (private infra like `cloudflare-oauth-proxy` is in the script's `EXCLUDED` set). Flag any integration that is released (or being released) but missing from `integrations.json`, and any JSON entry without a doc page. Do **not** hand-edit `versioned_sidebars\u002F*.json` to add integration links — they are positional placeholders filled from the JSON.\n- **Code standards** — the integration code must follow all Python style rules (type hints, no raw dicts, no tuple returns, etc.).\n\n### 10. Check MCP tool registration completeness\n\nIf any new MCP tools were added or existing tools renamed in `hindsight-api-slim\u002Fhindsight_api\u002Fmcp_tools.py`:\n- **`_ALL_TOOLS` set** in `mcp_tools.py` — must include the new tool name\n- **`tools_to_register` default set** in `register_mcp_tools()` in `mcp_tools.py` — must include the new tool name\n- **`_SINGLE_BANK_TOOLS` set** in `hindsight-api-slim\u002Fhindsight_api\u002Fapi\u002Fmcp.py` — must include the new tool if it is bank-scoped (not a bank-management tool like `list_banks`\u002F`create_bank`)\n- **`MCP_TOOL_GROUPS`** in `hindsight-control-plane\u002Fsrc\u002Fcomponents\u002Fbank-config-view.tsx` — must include the new tool in the appropriate group for the UI tool selector\n- **Tool count assertions** in tests (e.g., `test_mcp_tools.py`) — must be updated to reflect the new count\n\n### 11. Check backup\u002Frestore table coverage\n\nIf a migration adds a new PostgreSQL table (look for `CREATE TABLE` \u002F `op.create_table` in `hindsight-api-slim\u002Fhindsight_api\u002Falembic\u002Fversions\u002F`):\n- **`BACKUP_TABLES`** in `hindsight-api-slim\u002Fhindsight_api\u002Fadmin\u002Fcli.py` — must include the new table, placed after any table it references via foreign key (parents before children). A missing entry is silent data loss: the table is never backed up, and restore's `TRUNCATE banks CASCADE` wipes any FK-to-banks child (e.g. `mental_models`, `directives`) on restore even though it was never saved.\n- The guard test `test_backup_tables_covers_entire_schema` in `tests\u002Ftest_admin_backup_restore.py` enforces this — flag it as a **must fix** if a new table is absent from `BACKUP_TABLES`.\n- Oracle-only tables (e.g. `observation_sources`) are intentionally excluded — admin backup\u002Frestore is PostgreSQL-only.\n\n### 11b. Check new config flags update the env template\n\nIf the diff adds a new configuration field (a new `ENV_*` \u002F `HINDSIGHT_*` env var\nin `hindsight-api-slim\u002Fhindsight_api\u002Fconfig.py`):\n- **`.env.example`** (repo root) — must add the variable (commented if optional)\n  alongside the docs entry in `hindsight-docs\u002Fdocs\u002Fdeveloper\u002Fconfiguration.md`.\n  A flag added to `config.py` but absent from `.env.example` is a **should fix**.\n- **`hindsight-embed\u002Fhindsight_embed\u002Fenv.example`** — the bundled copy must stay\n  byte-identical to the repo-root `.env.example` (it seeds embed\u002Fprofile configs).\n  The `test_bundled_template_matches_repo_root` sync test fails on drift; if the\n  root file changed without re-copying, flag it as a **must fix**.\n\n### 12. Review against other coding standards\n\nCheck the diff for violations of the standards listed above:\n- Python files at project root (not allowed)\n- Missing async patterns (should be async throughout)\n- Pydantic models for request\u002Fresponse\n- Line length > 120 chars\n- New features\u002Fcode beyond what was asked (over-engineering)\n- Unnecessary error handling for impossible scenarios\n- Premature abstractions or speculative helpers\n- Backwards-compatibility hacks (unused vars, re-exports, \"removed\" comments)\n\n### 13. Report findings\n\nPresent a clear summary organized by severity:\n\n**Must fix** — issues that will break CI or violate hard project rules:\n- Unrelated commits on the branch\n- Lint failures\n- Missing type hints on public functions\n- Raw dict usage for structured data (including internal code)\n- Multi-item tuple returns (including internal code)\n- Missing tests for new endpoints\n- Direct DB access (raw SQL \u002F `acquire_with_retry` \u002F `fq_table`) in an `api\u002F` handler instead of a `MemoryEngine` method\n- Tenant-scoped data accessed without authentication enforced in the engine (`_authenticate_tenant` \u002F `get_bank_profile`)\n- New integration missing tests, CI job, or release-integration.sh entry\n- Released\u002Fadded integration missing from `hindsight-docs\u002Fsrc\u002Fdata\u002Fintegrations.json`, or a JSON entry with no `docs-integrations\u002F\u003Cslug>` page (fails the docs build via `check-integrations.mjs`)\n- New PostgreSQL table missing from `BACKUP_TABLES` in `admin\u002Fcli.py` (silent data loss on restore)\n\n**Should fix** — issues that hurt code quality:\n- Dead code \u002F unused imports missed by linter\n- Missing tests for non-trivial utility functions\n- Over-engineering beyond the task scope\n\n**Note** — observations that may or may not need action:\n- API changes that might need client regeneration\n- Patterns that deviate from nearby code style\n\nFor each finding, include the file path, line number, and a brief explanation.\n\nDo NOT auto-fix any issues. Report all findings and let the user decide what to address. If there are no findings, confirm the code looks good.\n",{"name":5,"description":7,"user_invocable":24},true,"main","89af4b6bd8e57a4af34127bcd3e74beba2960c99","othergithubdemo\u002Fhindsight-main\u002Fhindsight-main\u002F.claude\u002Fskills\u002Fcode-review",0,"https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion","https:\u002F\u002Fgithub.com\u002Fzhangmask","2026-08-12 23:25:19",{"source":8,"skillName":5,"commands":33,"prompt":43,"zipAvailable":24},[34,37,40],{"tool":35,"command":36},"npx","npx skills add zhangmask\u002FC_AnimeCompanion --skill code-review",{"tool":38,"command":39},"bunx","bunx skills add zhangmask\u002FC_AnimeCompanion --skill code-review",{"tool":41,"command":42},"pnpm","pnpm dlx skills add zhangmask\u002FC_AnimeCompanion --skill code-review","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fhindsight-main\u002Fhindsight-main\u002F.claude\u002Fskills\u002Fcode-review\u002FSKILL.md",[],[46,54,62,70,78,86],{"skillNo":47,"name":48,"nameZh":6,"description":49,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":50,"sourceHtmlUrl":51,"categories":52,"keywords":53,"publishedAt":19},"01M75DWFRG97DMF5XB527G18KQ","mem0","Mem0 Platform SDK for adding persistent memory to AI applications. TRIGGER when: user mentions \"mem0\", \"MemoryClient\", \"memory layer\", \"remember user preferences\", \"persistent context\", \"personalization\", or needs to add long-term memory to chatbots, agents, or AI apps. Covers Python SDK (mem0ai), TypeScript SDK (mem0ai), and framework integrations (LangChain, CrewAI, OpenAI Agents SDK, Pipecat, LlamaIndex, AutoGen, LangGraph). Also covers the open-source self-hosted Memory class. This is the DEFAULT mem0 skill for ambiguous queries. DO NOT TRIGGER when: user asks about CLI commands, terminal usage, or shell scripts (use mem0-cli), or Vercel AI SDK \u002F @mem0\u002Fvercel-ai-provider \u002F createMem0 (use mem0-vercel-ai-sdk).","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0\u002FSKILL.md",[],[],{"skillNo":55,"name":56,"nameZh":6,"description":57,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":58,"sourceHtmlUrl":59,"categories":60,"keywords":61,"publishedAt":19},"01M75DWA6DYJVW82BRA7PGWAWP","mem0-vercel-ai-sdk","Mem0 provider for Vercel AI SDK (@mem0\u002Fvercel-ai-provider). TRIGGER when: user mentions \"vercel ai sdk\", \"@mem0\u002Fvercel-ai-provider\", \"createMem0\", \"retrieveMemories\", \"addMemories\", \"getMemories\", \"searchMemories\", \"mem0 vercel\", \"AI SDK provider\", \"AI SDK memory\", or is using generateText\u002FstreamText with mem0. Also triggers for Next.js apps needing memory-augmented AI. DO NOT TRIGGER when: user asks about direct Python\u002FTS SDK calls without Vercel (use mem0 skill), or CLI terminal commands (use mem0-cli skill).","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-vercel-ai-sdk\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-vercel-ai-sdk\u002FSKILL.md",[],[],{"skillNo":63,"name":64,"nameZh":6,"description":65,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":66,"sourceHtmlUrl":67,"categories":68,"keywords":69,"publishedAt":19},"01M75DW1BKX9416VYXSV0MWWKK","mem0-test-integration","Verify a Mem0 integration produced by \u002Fmem0-integrate. Runs in the same workspace on the same branch (loose coupling) — installs dependencies, runs the repo's native test suite, then exercises a real end-to-end smoke flow against the user's API key. Produces a scorecard. TRIGGER when: user has just run \u002Fmem0-integrate and says \"verify\", \"test the integration\", \"run \u002Fmem0-test-integration\", or when a .mem0-integration\u002F directory exists and tests have not been run yet on the current branch. DO NOT TRIGGER when: the user wants to run general project tests (defer to the repo's native test command), or when no prior \u002Fmem0-integrate run exists in the current branch (ask them to run \u002Fmem0-integrate first). This skill ONLY catches compile and runtime bugs by design. Logical integration errors — wrong data stored, wrong time retrieved, wrong user scoping — are on the human reviewer.","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-test-integration\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-test-integration\u002FSKILL.md",[],[],{"skillNo":71,"name":72,"nameZh":6,"description":73,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":74,"sourceHtmlUrl":75,"categories":76,"keywords":77,"publishedAt":19},"01M75DVRVCQK3DNHFASD8SD2A2","mem0-oss-to-platform","Plan and then execute a migration of a project from the mem0 open-source \u002F self-hosted SDK (the local `Memory` class) to the mem0 Platform \u002F hosted \u002F managed SDK (the `MemoryClient` class). Use this whenever a developer wants to move, switch, or migrate their mem0 usage off OSS\u002Fself-hosted to the hosted API — e.g. \"migrate my mem0 setup to the platform\", \"switch from self-hosted mem0 to MemoryClient\", \"use my mem0 API key instead of a local Qdrant\", \"move mem0 to the cloud\u002Fhosted\u002Fmanaged service\", or \"replace my local mem0 vector store + embedder config with the platform\". Applies to Python (`from mem0 import Memory` → `from mem0 import MemoryClient`) and TypeScript\u002FJavaScript (`import { Memory } from \"mem0ai\u002Foss\"` → `import MemoryClient from \"mem0ai\"`). Trigger even when the user doesn't say the word \"migrate\" but clearly wants their existing mem0 integration to run against the hosted platform. It first produces a reviewable migration plan, then executes it after the developer approves. Strictly scoped to the mem0 integration — it does not refactor, restructure, or \"improve\" any unrelated code.","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-oss-to-platform\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-oss-to-platform\u002FSKILL.md",[],[],{"skillNo":79,"name":80,"nameZh":6,"description":81,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":82,"sourceHtmlUrl":83,"categories":84,"keywords":85,"publishedAt":19},"01M75DVH4QN1KKJ6JWFH0ZEP4K","mem0-integrate","Integrate Mem0 into an existing repository using a goal-driven, TDD pipeline. Detects the repo's language automatically and asks the user to pick between Mem0 Platform (managed) and Mem0 Open Source (self-hosted). Writes failing tests before any implementation. Produces a local feature branch plus `.mem0-integration\u002F` artifacts consumed by the paired verification skill. TRIGGER when: user says \"integrate mem0\", \"add mem0 to this repo\", \"wire mem0 into \u003Crepo>\", or asks how to add memory to an existing project. DO NOT TRIGGER when: the user wants general SDK usage (use skill:mem0), CLI usage (use skill:mem0-cli), or Vercel AI SDK (use skill:mem0-vercel-ai-sdk). After success, invoke skill:mem0-test-integration to verify in the same workspace (loose coupling).","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-integrate\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-integrate\u002FSKILL.md",[],[],{"skillNo":87,"name":88,"nameZh":6,"description":89,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":90,"sourceHtmlUrl":91,"categories":92,"keywords":93,"publishedAt":19},"01M75DV93TE88NQW790RDN7WRY","mem0-cli","Mem0 CLI -- the command-line interface for mem0 memory operations. TRIGGER when: user mentions \"mem0 cli\", \"mem0 command line\", \"@mem0\u002Fcli\", \"mem0-cli\", \"pip install mem0-cli\", \"npm install -g @mem0\u002Fcli\", or is running mem0 commands in a terminal\u002Fshell (mem0 add, mem0 search, mem0 list, mem0 get, mem0 init, mem0 config, mem0 import). Also triggers when query includes CLI flags like --user-id, --output, --json, --agent, or describes bash\u002Fzsh\u002Fterminal\u002Fshell usage. DO NOT TRIGGER when: user asks about programmatic SDK integration in Python\u002FTS code (use mem0 skill), or Vercel AI SDK provider (use mem0-vercel-ai-sdk skill).","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-cli\u002FLICENSE","https:\u002F\u002Fgithub.com\u002Fzhangmask\u002FC_AnimeCompanion\u002Fblob\u002Fmain\u002Fothergithubdemo\u002Fmem0-main\u002Fmem0-main\u002Fskills\u002Fmem0-cli\u002FSKILL.md",[],[]]