Kamae review

Kamae Code Review

Adversarial review against the kamae principles. The knowledge base lives in ../kamae/; this skill links rather than duplicates.

Step 0: Load applicable rules

Before any other step, glob and Read rules in priority order:

1. .claude/rules/*.md (project-level overrides at the working-tree root)
2. ~/.claude/rules/*.md (user-global preferences)
3. ../../rules/defaults/*.md relative to this SKILL.md (plugin defaults)

For each file:

• Read the YAML frontmatter. Skip the rule unless applies-to is kamae-review or *.
• Group by name. For each name, keep only the highest-tier instance (1 > 2 > 3); within a tier the lexicographically last filename wins.
• A check-toggle rule with enabled: false removes the named check from the walk in step 3 below.
• A convention rule sets project-specific expectations the review respects (e.g., a designated location for Branded Types).

If no rules are found, proceed with all checks active. See ../../rules/README.md for the rule format.

Review Procedure

1. Load principle knowledge. Before reading any code under review, read:

   • ../kamae/SKILL.md — principle index
   • The validation library guide matching the project's package.json under ../kamae/validation-libraries/ (zod.md / valibot.md / arktype.md)
   • The Result library guide matching the project's package.json under ../kamae/result-libraries/ (neverthrow.md / byethrow.md / fp-ts.md / option-t.md)
   • Each topic file under ../kamae/ cited by the checklist sub-files you read.

2. Read the files under review.

3. Walk the checklist. Read each checklist sub-file in order; match findings to its items.

   • checklist/domain-modeling.md — Discriminated Unions, Companion Objects, Branded Types, file structure (items 1.x)
   • checklist/state-transitions.md — pure state transitions, exhaustiveness (items 2.x)
   • checklist/error-handling.md — Result types, no thrown exceptions, DU error types (items 3.x)
   • checklist/boundary.md — schema validation, no as assertions, schema-derived types (items 4.1, 4.2, 4.4)
   • checklist/pii-protection.md — Sensitive<T> for PII (item 4.3)
   • checklist/declarative-and-tests.md — array operations, events, fixtures (items 5.x, 6.x)

4. Report findings. For each violation:

   1. Location (path:line).
   2. Why it is a problem — cite the principle (link back to ../kamae/...) and the risk of violating it.
   3. How to fix — code example showing the corrected version.

5. Suggestions (non-violations with room for improvement) are communicated with the same format but framed as suggestions rather than findings.

Severity classes

Each checklist item is tagged High / Medium / Low.

• High — direct cause of runtime errors or compliance violations (as, missing PII protection, missing schema validation, missing Branded Types on semantically distinct primitives).
• Medium — invalid state representation, inconsistent error handling, missing exhaustiveness, catch-all type files, classes for domain models.
• Low — stylistic, readability, edge-case correctness (method notation, interface for domain types, missing Readonly<>, non-kind discriminants, imperative array loops, fixtures without as const satisfies, matching schema/type duplication). An existing schema/type mismatch is raised according to its incorrect acceptance, rejection, or data-exposure impact.

Example Finding

### Use of method notation

`src/repository/task-repository.ts:15`

`save(task: Task): Promise<void>` uses method notation. Per
[`../kamae/SKILL.md` §1 "Use function property notation"](../kamae/SKILL.md),
parameters become bivariant under method notation, so a narrower implementation
such as `save(task: DoingTask): Promise<void>` will pass type checking at the
injection site.

Suggested fix:
\`\`\`typescript
type TaskRepository = {
  save: (task: Task) => Promise<void>;
};
\`\`\`