# Sage Review

> Review report with strengths, issues, risks, verdict

- Skill: `xoai/sage-review` (Agent Skill)
- Install (CLI): `npx skillmds@latest add xoai/sage-review`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xoai/sage-review/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: xoai (https://skillmd.com/u/xoai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xoai/sage-review

---


## When to Use
Load this skill when the user runs `/sage-review` or asks to review something (the Sage review workflow).

## Arguments
Hermes does NOT interpolate an in-body argument token. The user's arguments/flags arrive as a SEPARATE instruction line appended to this skill invocation. Wherever the steps below refer to "the user's arguments", use the text of that appended instruction line.

## Independent review (delegate_task)
When a step calls for an independent review, invoke `delegate_task` against the `sage-reviewer` skill. Hermes delegate_task has NO toolset-restriction parameter — read-only is prompt-enforced, and you MUST verify afterward that the reviewer made no edits (e.g. `git status` unchanged) before accepting its verdict.


# Review Workflow

Independent evaluation. Designed to work in a fresh session for maximum
objectivity, but also works within an existing session.

## Step 0: Mode Dispatch

`/review` has four modes. Parse `the arguments the user provided alongside this skill invocation (delivered as a separate instruction line, NOT a literal token)` for a mode flag; default is code /
artifact review.

| Invocation | Mode | Read the mode reference |
|---|---|---|
| `/review` (default) | Code / artifact quality | (this file, Steps 1–5) |
| `/review --ux` | UX assessment (audit → evaluate → heuristics) | `core/workflows/review-modes/ux.md` |
| `/review --design` | Design-system compliance + visual quality | `core/workflows/review-modes/design.md` |
| `/review --browser` | Functional / browser QA (optional Lightpanda) | `core/workflows/review-modes/browser.md` |

These modes fold in the former `/analyze`, `/design-review`, and `/qa`
workflows. On a mode flag, read the matching reference and follow it; the Rules
below still apply. `--ux` uses the `ux-review` skill, which ships in the
`sage-product` pack — if it is not installed, say so and offer
`sage add xoai/sage-product`.

## Step 1: Identify What to Review

If not specified, scan `.sage/work/` and `.sage/docs/` for recent
artifacts. Present them:

Sage: Available for review:

[1] .sage/work/20260316-checkout/brief.md (updated today)
[2] .sage/work/20260316-checkout/spec.md (updated today)
[3] .sage/docs/ux-audit-homepage.md (updated yesterday)

Which artifact should I review? Or describe what you'd like evaluated.

If the user specifies an artifact, proceed directly.

## Step 2: Gather Context

Search for prior knowledge using sage_memory_search — pass the
artifact topic and domain as query (string), limit as 5 (integer).
If the tool is not available, proceed without memory context.

Read the artifact fully.

Identify which skill or workflow produced this artifact — check for
skill prefixes in the filename, references in the content, or metadata.
Load the producing skill's quality criteria — these become the primary
evaluation framework. If the producing skill cannot be identified,
use the three general lenses in Step 3.

If this is a fresh session, note: "Sage: Reviewing with fresh eyes —
I wasn't involved in producing this work."

If this is the same session, note: "Sage: I produced this work, so my
review may have blind spots. For a more independent evaluation,
consider a fresh session or the /review command."

## Step 3: Evaluate

Review the artifact against three lenses:

For detailed code quality review, read
`sage/core/capabilities/review/quality-review/SKILL.md`.

**Completeness** — Does it cover what it should? Are there missing
sections, unaddressed scenarios, or gaps in reasoning? Check against
the producing skill's quality criteria if available.

**Consistency** — Does it align with other project artifacts? Does
the spec match the brief? Does the plan match the spec? Are there
contradictions within the document itself?

**Quality** — Is the thinking sound? Are claims supported by evidence?
Are trade-offs named explicitly? Would a domain expert find this
credible? Is anything vague where it should be specific?

For each finding, note:
- What you observed (specific, with quotes or references)
- Why it matters (impact on downstream work)
- Suggested action (fix, clarify, investigate, or accept as-is)

## Step 4: Present Findings

Structure the review clearly:

```
## Review: [artifact name]

### Strengths
[What's well-done — be specific, not generic praise]

### Issues Found
[Each issue: observation → impact → suggestion]

### Risks
[Things that aren't wrong but could cause problems downstream]

### Verdict

[One of:]
  ✓ Ready to proceed — [minor notes if any]
  ⚠ Needs revision — [specific items to address]
  ✗ Significant gaps — [recommend rework before proceeding]
```

## Step 5: Next Steps

Based on the verdict:

- **Ready:** Recommend the natural next step in the workflow
- **Needs revision:** List specific items to address, offer to help
- **Significant gaps:** Recommend which step to return to and why

[A] Accept findings — proceed with suggested next step
[R] Revise — I'll address the issues found
[D] Discuss — let's talk about specific findings

Prepend review findings to `.sage/decisions.md`.

## Rules

- Be specific. "The spec is good" is not a review. "The spec covers
  the happy path thoroughly but doesn't address what happens when the
  payment gateway times out" is a review.
- Be honest. The purpose of review is to catch problems before they
  become expensive. Diplomatic honesty serves the user better than
  comfortable vagueness.
- Evaluate against criteria, not preferences. Use the producing skill's
  quality criteria when available. When not, use the three lenses above.
- Fresh session review is always recommended for high-stakes artifacts
  (briefs, specs, architecture decisions).