Agent-Skills.md

Agent Skills: Reviewing

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

UncategorizedID: desplega-ai/ai-toolbox/reviewing

Repository

desplega-ai/ai-toolbox
desplega-ai
202

Install this agent skill to your local

pnpm dlx add-skill https://github.com/desplega-ai/ai-toolbox/tree/HEAD/cc-plugin/base/skills/reviewing

Skill Files

Browse the full folder contents for reviewing.

Download Skill

Loading file tree…

cc-plugin/base/skills/reviewing/SKILL.md

Skill Metadata

Name
reviewing
Description
Structured critique of research, plan, and brainstorm documents for completeness, gaps, and quality.

Reviewing

You are performing a structured critique of a document (research, plan, or brainstorm) to identify gaps, weaknesses, and quality issues.

Working Agreement

These instructions establish a working agreement between you and the user. The key principles are:

  1. AskUserQuestion is your primary communication tool - Whenever you need to ask the user anything (clarifications, preferences, decisions), use the AskUserQuestion tool. Don't output questions as plain text - always use the structured tool so the user can respond efficiently.

  2. Establish preferences upfront - Ask about user preferences at the start of the workflow, not at the end when they may want to move on.

  3. Autonomy mode guides interaction level - The user's chosen autonomy level determines how often you check in, but AskUserQuestion remains the mechanism for all questions.

User Preferences

Before starting review (unless autonomy is Autopilot), establish these preferences:

Output Mode - Use AskUserQuestion with:

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

File Review Preference - Check if the file-review plugin is available (look for file-review:file-review in available commands).

If file-review plugin is installed, use AskUserQuestion with:

| Question | Options | |----------|---------| | "Would you like to use file-review for inline feedback after the automated review?" | 1. Yes, open file-review after review (Recommended), 2. No, the automated review is sufficient |

Store these preferences and act on them during the review process.

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 section
  • Current State Analysis
  • Desired End State with Key Discoveries
  • What We're NOT Doing
  • Phases with Changes Required and Success Criteria (both Automated and Manual Verification)
  • Quick Verification Reference

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)?

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 "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. The only exception is Minor auto-fixes (typos, formatting).

Review Integration

If the file-review plugin is available and the user selected "Yes" during User Preferences setup:

  • After the automated review, invoke /file-review:file-review <path> for inline human comments
  • Process feedback with file-review:process-review skill
  • If user selected "No" or autonomy mode is Autopilot, skip this step