suggest-review-flow · diff
git:20260821.eefdfab to git:20260822.462801e
9 added, 13 removed. Audit A to A.
---
name: suggest-review-flow
description: >-
- Use this skill to PROACTIVELY OFFER an independent review flow at a natural
- milestone — right after you finish writing or finalizing a spec/design, and
- right after implementation is complete (a feature or bugfix is functionally
- finished, or you are about to commit / open a PR / merge). It suggests handing
- the work to a SEPARATE reviewer harness and, using list_reviewer_vendors,
- recommends a reviewer that will actually run for this repo. Triggers:
- "implementation is complete", "I've finished implementing", "the feature is
- done", "ready to commit", "about to open a PR", "spec is finalized", "just
- wrote the design". It only OFFERS and asks — it never starts a flow on its
- own, and it hands execution to the review-flows skill once the user accepts.
- Do NOT use it when the user asks you to review something yourself ("review
- this", "code review this", "look over my spec") — just do that review
- directly; and do not use it to START a flow (that is the review-flows skill).
+ Use this skill when implementation is complete — a feature or bugfix is functionally
+ finished, tests pass, or you are about to commit / open a PR / merge — or when a spec is
+ finalized. At that moment, proactively OFFER an independent second-harness review even if
+ the user did not ask, because a fresh, separate reviewer catches what the author's own model
+ misses. It calls list_reviewer_vendors to recommend a reviewer that will actually run for
+ this repo, offers a spec-review or code-review flow, and hands off to the review-flows skill
+ only after the user accepts — it never starts a flow itself. Do NOT use it when the user
+ asks you to review something yourself ("review this", "code review this", "look over my
+ spec"), or mid-task before the work is finished.
---
# Suggest a review flow
You have reached a milestone where an **independent** review adds real value: a
separate coding-agent session, with none of this session's context, reviews the
work — and a different model catches what the author's own model glossed over.
Most people never think to do this. Your job here is to **offer** it at the
right moment, recommend a reviewer that will actually run, and — only if the
user says yes — hand off to the `review-flows` skill. **This skill never starts
a review flow itself.**
## When to offer (and when not to)
Offer at exactly two milestones:
- **Spec complete** — you just produced AND presented a finalized spec/design
this session → offer a `spec-review` flow.
- **Implementation complete** — the change is functionally finished (you say so,
or you are about to commit / open a PR / merge) → offer a `code-review` flow.
Do NOT offer (stay silent) when:
- The user asked you to **review something yourself** ("review this", "code
review this", "look over the spec"). Just perform that review locally — no
offer, no flow.
- You are only part-way through: rough mid-stream brainstorming, a partial plan,
a routine edit, or work whose known checks are still failing.
- A review flow for this artifact is already engaged, active, or just completed.
- Another skill (brainstorming, writing-plans, finishing-a-development-branch,
requesting-code-review) is mid-flow — let it finish; offer at the seam.
**Offer at most once per artifact.** Key the offer on (milestone type + the
target's identity + its revision): the same spec or the same change never gets
offered twice, but a materially revised artifact may be offered again, and a
second, different artifact of the same kind may be offered on its own. If the
user declines or moves on, stay silent for that artifact. A failed availability
lookup counts as the one prompt for that artifact — do not re-prompt.
## How to recommend a reviewer
1. Call **`list_reviewer_vendors`** (read-only; safe to call before offering).
It returns `reviewers[]` (vendors that can actually run for this repo now),
`driver_vendor` (the harness you are running in, or absent if unknown), and
`diagnostics`.
2. **Prefer a reviewer different from the driver.** A different model is the
highest-value review. If one non-driver reviewer is available, recommend it;
if several, offer a short choice — never assert one vendor is "better".
3. **If the only available reviewer is your own vendor, still offer it** —
framed as an independent, context-free reviewer session. The value is the
clean second look, not necessarily a different model.
4. **If `driver_vendor` is absent (unknown)**, do NOT claim "a different model";
frame the offer as "a separate, independent reviewer session" and offer a
choice from `reviewers[]`.
5. **If `reviewers[]` is empty**, read `diagnostics.reason` and give one line of
guidance instead of a dead end:
- `no_daemons_connected` → start a daemon (`kcap daemon start -d`).
- `no_repo_hosting_daemon` → run a daemon on a machine that has this repo.
- `no_unattended_reviewer` → install/certify a second harness as a reviewer.
- `repo_unresolved` → the current directory isn't a recognized repo.
- `lookup_failed` → couldn't reach the server; suggest checking `kcap status`.
- `schema_skew` → the kcap client/server is out of date; suggest updating.
## Handing off (only after the user accepts)
- You MAY run the read-only `list_reviewer_vendors` lookup automatically, but you
**MUST NOT start a review flow until the user affirmatively accepts THIS
offer.**
- On acceptance, invoke the **`review-flows`** skill to run it, preserving the
chosen `kind` (spec-review / code-review), the target, and the chosen reviewer
vendor.
- If the reviewer vendor turns out to be unavailable at start (a snapshot race),
`review-flows` surfaces the reason — do not silently substitute another vendor;
re-recommend and get fresh consent.
## If `list_reviewer_vendors` is not available
Your harness caches the kcap MCP tool list when it connects. If kcap was
upgraded mid-session, `list_reviewer_vendors` may be missing from this session.
Do NOT guess availability and do NOT shell out as a workaround — tell the user
to restart the harness (or reconnect the `kcap-flows` MCP server) so the tool
appears, then offer again.