Basic Machines Review
Use this skill for repo-local review passes where ordinary code review needs Basic Machines
house style and architecture judgment. Report findings only; do not edit code unless the user
asks you to fix specific findings.
Scope
Review the current diff or named files against:
- The repo's
AGENTS.md / CLAUDE.md
docs/ENGINEERING_STYLE.md
- The touched code paths and tests
Apply only the guidance for the active repo. In basic-memory, prioritize local-first
file/database/MCP boundaries. In basic-memory-cloud, prioritize tenant/workspace isolation,
cloud worker behavior, and web-v2 state/runtime boundaries.
Review Rubric
Report only concrete, falsifiable risks:
- Cognitive load: Is the change harder to understand than the problem requires?
- Change propagation: Will one product change force edits across unrelated layers?
- Knowledge duplication: Is the same rule encoded in multiple places that can drift?
- Accidental complexity: Did the change add abstractions, fallbacks, or state without need?
- Dependency direction: Are API/MCP/CLI, services, repositories, and UI stores respecting
their intended boundaries?
- Domain model distortion: Do names and types still match the product concept, or did a
transport/storage detail leak into the domain?
- Test oracle quality: Would the tests fail for the bug or regression the change claims to
protect against?
House Rules To Check Explicitly
- No speculative
getattr(obj, "attr", default) for unknown model shapes.
- No broad exception swallowing, warning-only failure paths, or hidden fallback behavior.
- No casts or
Any that hide an unclear type relationship.
- Dataclasses for internal value/result objects; Pydantic at validation/serialization
boundaries.
- Narrow
Protocols when only a capability is needed.
- Explicit async/resource ownership, cancellation, and cleanup.
- Meaningful regression tests or verification for risky changes.
- Comments explain why, not what.
Reporting Format
Lead with findings ordered by severity. Each finding should include:
| Severity |
Use for |
high |
A likely correctness, security, data-loss, or tenant/workspace isolation failure |
medium |
A concrete maintainability or boundary risk that can cause future defects |
low |
A minor consistency issue, ambiguous guidance, or review-only cleanup |
severity | file:line | risk category | claim
Why: concrete behavior or code path that proves the risk.
Fix: smallest practical change, or "none obvious" if the risk needs product input.
If there are no findings, say so and note any verification gaps that remain.
1---
2name: code-review
3description: Use when reviewing Basic Machines code for house style, architecture risk, pre-merge hardening, or whether a change fits basic-memory/basic-memory-cloud conventions.
4license: MIT
5metadata:
6 source: https://skillmd.com/skills/basicmachines-co-basic-memory/code-review
7---
8
9# Basic Machines Review
10
11Use this skill for repo-local review passes where ordinary code review needs Basic Machines
12house style and architecture judgment. Report findings only; do not edit code unless the user
13asks you to fix specific findings.
14
15## Scope
16
17Review the current diff or named files against:
18
19- The repo's `AGENTS.md` / `CLAUDE.md`
20- `docs/ENGINEERING_STYLE.md`
21- The touched code paths and tests
22
23Apply only the guidance for the active repo. In `basic-memory`, prioritize local-first
24file/database/MCP boundaries. In `basic-memory-cloud`, prioritize tenant/workspace isolation,
25cloud worker behavior, and web-v2 state/runtime boundaries.
26
27## Review Rubric
28
29Report only concrete, falsifiable risks:
30
31- **Cognitive load:** Is the change harder to understand than the problem requires?
32- **Change propagation:** Will one product change force edits across unrelated layers?
33- **Knowledge duplication:** Is the same rule encoded in multiple places that can drift?
34- **Accidental complexity:** Did the change add abstractions, fallbacks, or state without need?
35- **Dependency direction:** Are API/MCP/CLI, services, repositories, and UI stores respecting
36 their intended boundaries?
37- **Domain model distortion:** Do names and types still match the product concept, or did a
38 transport/storage detail leak into the domain?
39- **Test oracle quality:** Would the tests fail for the bug or regression the change claims to
40 protect against?
41
42## House Rules To Check Explicitly
43
44- No speculative `getattr(obj, "attr", default)` for unknown model shapes.
45- No broad exception swallowing, warning-only failure paths, or hidden fallback behavior.
46- No casts or `Any` that hide an unclear type relationship.
47- Dataclasses for internal value/result objects; Pydantic at validation/serialization
48 boundaries.
49- Narrow `Protocol`s when only a capability is needed.
50- Explicit async/resource ownership, cancellation, and cleanup.
51- Meaningful regression tests or verification for risky changes.
52- Comments explain why, not what.
53
54## Reporting Format
55
56Lead with findings ordered by severity. Each finding should include:
57
58| Severity | Use for |
59| -------- | ------- |
60| `high` | A likely correctness, security, data-loss, or tenant/workspace isolation failure |
61| `medium` | A concrete maintainability or boundary risk that can cause future defects |
62| `low` | A minor consistency issue, ambiguous guidance, or review-only cleanup |
63
64```text
65severity | file:line | risk category | claim
66Why: concrete behavior or code path that proves the risk.
67Fix: smallest practical change, or "none obvious" if the risk needs product input.
68```
69
70If there are no findings, say so and note any verification gaps that remain.