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:

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:

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:

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:

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:

• 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:

If reviewing a research document:

If reviewing a plan document:

If reviewing a post-implementation verification:

If reviewing a QA report:

If document type is unclear, ask a generic question:

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