# Reviewing

> Structured critique of research, plan, and brainstorm documents for completeness, gaps, and quality.

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

---


# Reviewing

You are performing a structured critique of a document (research, plan, or brainstorm) to identify gaps, weaknesses, and quality issues. (For reviewing a code diff, use `desplega:code-reviewing` instead — this skill reviews documents.)

## Working Agreement

**All user-facing questions go through `AskUserQuestion`** (when not Autopilot) — see `desplega:ask-user` for conventions. Never ask in chat as plain bullets.

File-review is on by default — invoke it after the automated review (skip only if Autopilot).

### Output Mode

Unless Autopilot, ask once at the start:

| Question | Options |
|----------|---------|
| "How should I present the review findings?" | 1. Append errata section to the document (Recommended), 2. Auto-apply fixes to the document, 3. Write a separate review file to thoughts/*/reviews/ |

## When to Use

This skill activates when:
- User invokes `/review` command
- Another skill references the reviewing skill at completion
- User asks to review, critique, or check a document

## Autonomy Mode

At the start of review, adapt your interaction level based on the autonomy mode:

| Mode | Behavior |
|------|----------|
| **Autopilot** | Run full review, auto-fix minor issues, present summary at end |
| **Critical** (Default) | Ask about Critical/Important findings, auto-fix Minor ones |
| **Verbose** | Walk through each finding, confirm before any changes |

The autonomy mode is passed by the invoking command. If not specified, default to **Critical**.

## Process Steps

### Step 1: Read & Classify

Read the input document fully. Determine the document type from its path and content structure:

| Path contains | Type |
|---------------|------|
| `/research/` | Research document |
| `/plans/` | Plan |
| `/brainstorms/` | Brainstorm |
| `/qa/` | QA report |

If the type is ambiguous, infer from content structure or use **AskUserQuestion** to clarify.

### Step 2: Structural Check

Verify required sections exist based on document type:

**Research documents:**
- YAML frontmatter with required fields (date, researcher, topic, status)
- Research Question section
- Summary section
- Detailed Findings with file:line references
- Code References table
- Open Questions section

**Plans:**
- YAML frontmatter with required fields (date, planner, topic, status)
- Overview with Motivation + Related links
- Current State Analysis
- Desired End State
- What We're NOT Doing
- Implementation Approach (bullet one-liners)
- Quick Verification Reference
- Phases with Changes Required and Success Criteria (all three subsections: Automated Verification, Automated QA, Manual Verification)
- QA Spec (when present) is a link to a `desplega:qa`-generated doc, not inline scenarios
- Appendix (follow-up plans, derail notes, references)

**Brainstorms:**
- YAML frontmatter with required fields (date, author, topic, status)
- Context section
- Exploration section with Q&A pairs
- Synthesis section
- Next Steps section

**QA reports:**
- YAML frontmatter with required fields (date, author, topic, status)
- Context section
- Scope section (In Scope / Out of Scope)
- Test Cases with Steps, Expected, Actual, Status per case
- Evidence section (Screenshots, Videos, Logs, or External Links)
- Verdict section with overall status and summary

### Step 3: Content Analysis

Apply type-specific quality criteria:

**Research documents:**
- Are findings supported by specific file:line references?
- Are there claims without evidence from the codebase?
- Are there obvious areas that weren't investigated?
- Are open questions actually open (not answerable from the findings)?

**Plans:**
- Are there missing phases or gaps in the implementation sequence?
- Are success criteria specific enough to be actionable?
- Are there unstated assumptions about the codebase?
- Is error handling or rollback addressed?
- Is there scope creep risk (doing more than stated)?
- Is any phase over-built? Run proposed abstractions, layers, and new dependencies against `desplega:engineering-standards` (deletion test, two-adapters rule, new-dependency test) — flag failures as Important.

**Brainstorms:**
- Were important angles left unexplored?
- Were conclusions reached prematurely before sufficient exploration?
- Are constraints and requirements clearly identified?
- Is the document ready to feed into research or planning?

**QA reports:**
- Does every test case have an actual result and status?
- Is evidence provided for failures (screenshots, logs)?
- Is the verdict consistent with individual test case results?
- Are edge cases and exploratory testing documented?
- Are external references (Sentry, PRs, CI) linked where relevant?

### Step 4: Gap Identification

Look for what's missing or assumed:
- Cross-reference claims against the codebase if needed (spawn **codebase-analyzer** agent for verification)
- Identify unstated assumptions
- Check for internal contradictions
- Verify external references are still valid

### Step 5: Present Findings

Categorize all findings into three severity levels:

| Severity | Meaning | Action |
|----------|---------|--------|
| **Critical** | Blocks correctness or completeness — must be addressed | Discuss with user |
| **Important** | Significant gap or weakness — should be addressed | Discuss with user (or auto-fix in Autopilot) |
| **Minor** | Formatting, typos, small inconsistencies | Auto-fix unless Verbose mode |

Present a summary as text output with findings grouped by severity.

### Step 6: Apply or Discuss

Based on output mode preference:

**If "Append errata":**
- Auto-fix Minor issues directly in the document
- For Critical/Important items, append a `## Review Errata` section at the end of the document with:
  ```
  ## Review Errata

  _Reviewed: YYYY-MM-DD by [reviewer]_

  ### Critical
  - [ ] [Finding description and recommended action]

  ### Important
  - [ ] [Finding description and recommended action]

  ### Resolved
  - [x] [Minor issue] — auto-fixed
  ```

**If "Auto-apply":**
- Auto-fix Minor issues directly in the document
- Auto-fix Important issues directly in the document
- For Critical findings, use **AskUserQuestion** with:

| Question | Options |
|----------|---------|
| "There are [N] Critical findings. Would you like me to auto-apply fixes for those too?" | 1. Yes, apply Critical fixes too, 2. No, leave Critical items as errata for me to address |

- Apply Critical fixes if authorized, otherwise leave them as unchecked errata items
- Append a `## Review Errata` section summarizing all changes:
  ```
  ## Review Errata

  _Reviewed: YYYY-MM-DD by [reviewer]_

  ### Applied
  - [x] [Finding description] — auto-applied
  - [x] [Finding description] — auto-applied

  ### Remaining (if any Critical items were not auto-applied)
  - [ ] [Critical finding description and recommended action]
  ```

**If "Separate file":**
- Write review to `thoughts/*/reviews/YYYY-MM-DD-review-of-<original-slug>.md`
- Include all findings with references back to the original document

### Step 7: Workflow Handoff

After the review is complete, determine the document type (from frontmatter, file path, or content) and propose the appropriate next step.

Use **AskUserQuestion** with context-dependent options:

**If reviewing a brainstorm document:**

| Question | Options |
|----------|---------|
| "Review complete. What's next for this brainstorm?" | 1. Start research (→ `/research`), 2. Create a plan directly (→ `/create-plan`), 3. Done for now |

**If reviewing a research document:**

| Question | Options |
|----------|---------|
| "Review complete. What's next for this research?" | 1. Create a plan (→ `/create-plan`), 2. Done for now |

**If reviewing a plan document:**

| Question | Options |
|----------|---------|
| "Review complete. What's next for this plan?" | 1. Start implementation (→ `/implement-plan`), 2. Done for now |

**If reviewing a post-implementation verification:**

| Question | Options |
|----------|---------|
| "Review complete. What's next?" | 1. Done — mark as complete, 2. Address remaining items |

**If reviewing a QA report:**

| Question | Options |
|----------|---------|
| "Review complete. What's next for this QA report?" | 1. Run post-QA verification (→ `/verify-plan`), 2. Address issues found, 3. Done |

**If document type is unclear**, ask a generic question:

| Question | Options |
|----------|---------|
| "Review complete. Would you like to proceed to the next workflow step?" | 1. Yes, suggest next step, 2. Done for now |

## Learning Capture

**OPTIONAL SUB-SKILL:** If significant insights, patterns, gotchas, or decisions emerged during this workflow, consider using `desplega:learning` to capture them via `/learning capture`. Focus on learnings that would help someone else in a future session.

## No Rewriting Rule

**CRITICAL**: The reviewer identifies issues — the reviewer does NOT rewrite the document. Present findings and let the original author address them. Exceptions:
- Minor auto-fixes (typos, formatting) are always applied
- In **Auto-apply** mode, the reviewer applies Important and (optionally) Critical fixes directly, as authorized by the user

## Review Integration

File-review is on by default (unless Autopilot):
- After the automated review, invoke `/file-review:file-review <path>` for inline human comments
- Process feedback with the `file-review:process-review` skill