ai-review

name

ai-review

description

Review a diff or feature against Sleek Coach's AI conventions (provider factory boundary, model config, tool registry, safety policy coverage, the token/tool_start/tool_end/done/error streaming contract, session and history caps, required tests). Use for the pre-commit AI agent check, when the user asks for an "AI review" / "coach review" / "safety check" on the coach, or before committing changes that touch apps/api/app/coach_ai or the mobile coach streaming client (apps/mobile/src/services/api/coachService.ts, apps/mobile/src/services/hooks/useCoach.ts). Reads docs/AI_CONVENTIONS.md as the source of truth.

AI Review

Check a change against Sleek Coach's AI conventions and report where it complies, where it violates a rule, and how to fix each violation.

This skill is a review tool, not a rubber stamp. Every rule in the conventions doc was earned by a shipped defect (the streamed-session continuity bug, the lb/kg policy bug, the stream path that skipped output checks); a change that violates one should be told so with the concrete failure it invites and the compliant fix, not waved through. Equally, do not invent violations: a rule that does not apply to the diff is simply not in play.

Step 1: Load the source of truth

Read docs/AI_CONVENTIONS.md. Its rule sections and the review checklist at the bottom are authoritative; if the doc has changed, follow the changed version, not any summary reproduced elsewhere (including this skill).

Step 2: Gather the change under review

In priority order:

1. A target the user named (a PR number, branch, file, or feature description).
2. The current working diff: git diff origin/main...HEAD, plus git diff HEAD if there are uncommitted changes (pre-commit reviews usually run before the commit exists).

If the diff is empty and no target was named, say so and stop. If the diff touches neither apps/api/app/coach_ai nor the mobile coach streaming client, say so and stop: this check is only for the AI layer and its cross-app contract. Prompt text changes count: prompts are product behavior.

Step 3: Walk the review checklist

Go through the checklist at the bottom of the conventions doc in order, applying each item to the diff. Run the mechanical greps as written rather than eyeballing. For the judgment items, read the full post-change files, not just the hunks: policy-engine calls, event emission, and session handling often live a few lines from the changed code.

Two cases deserve extra suspicion:

• Any change to the streaming path (service.chat_stream, router.py, the orchestrator's stream loop, or the mobile SSE client): verify the event contract field by field against rule 5, and treat a backend contract change without a paired mobile change in the same diff as a violation, not a note.
• Any change to a policy, a policy regex, or policies/extraction.py: confirm the changed behavior has an explicit test in the policy's dedicated test file or in test_policy_extraction.py, including unit handling (the lb/kg regression is the cautionary tale). A weakened or deleted safety assertion is a finding, not a cleanup; a metadata-only test deletion is not.

For each violation, report:

• file:line of the offending code.
• The rule it breaks, by section number from the doc.
• The concrete failure it invites: what breaks and who feels it (a stranded mobile session, an unlogged tool call, a policy that stops firing for metric input, a vendor lock reintroduced through a stray import).
• The compliant fix, naming the existing seam the doc prescribes (the factory, model_config.py, the registry, default_policies(), extraction.py, _record_exchange, the structured disclaimers field).

Step 4: Report

Output, in this order:

1. Verdict: clean, clean with notes, or violations found.
2. Violations (if any), each with the four fields from Step 3, ordered by how badly safety, auditability, or the cross-app contract is hurt.
3. Risks worth a look: things the diff makes easier to get wrong later, or rules it comes close to breaking.
4. Confirmed clean: the checklist areas the diff actually exercised and passed, so the reader knows what was checked rather than assuming everything was.

Keep the report tight: findings first, no praise, no restating the diff.