Review Workflow Design Skill

Design review workflows that validate implementation against specifications with visual proof.

When to Use

Setting up review processes for features
Creating proof-of-value workflows
Designing spec-based validation
Implementing auto-resolution loops

Core Concept

Review answers: "Is what we built what we asked for?"

This is different from testing which answers: "Does it work?"

Design Workflow

Step 1: Define Spec Location Pattern

Establish where specifications live:

specs/
├── feature-{name}.md
├── bug-{name}.md
└── chore-{name}.md

Or:

specs/issue-{number}-{type}.md

Step 2: Design Screenshot Capture Points

Identify critical paths that need visual proof:

Initial State: Before any interaction
Key Actions: After significant user actions
Final State: End result of the feature

Example:

1. Take screenshot of dashboard (initial state)
2. Click "Export" button
3. Take screenshot of export modal
4. Complete export
5. Take screenshot of success message

Step 3: Define Severity Classification

Configure issue severity levels:

Severity	Criteria	Action
blocker	Prevents release, harms UX	Auto-resolve
tech_debt	Quality issue, works	Document
skippable	Polish, preference	Ignore

Step 4: Set Up Resolution Workflow

Design the auto-resolution loop:

Review
  ├── Issues found?
  │     ├── Blockers? → /patch → /implement → Re-review
  │     └── No blockers → Success
  └── No issues → Success

Maximum 3 retry attempts

Step 5: Configure Proof Storage

Options for screenshot storage:

Local: agents/{adw_id}/review_img/
Cloud: R2, S3, or similar (public URLs)
Git: Committed with review artifacts

Review Command Structure

# Review Implementation Against Spec

## Variables
spec_file: $1

## Instructions

1. **Read Specification**
   - Understand requirements
   - Note success criteria

2. **Analyze Changes**
   - git diff origin/main
   - Compare against spec

3. **Capture Screenshots**
   - 1-5 screenshots of critical functionality
   - Number: 01_name.png, 02_name.png

4. **Classify Issues**
   - blocker: Must fix before release
   - tech_debt: Document for later
   - skippable: Can ignore

## Output Format

{
  "success": boolean,
  "review_summary": "string",
  "review_issues": [...]
}

Issue Structure

{
  "issue_description": "What's wrong",
  "issue_resolution": "How to fix it",
  "issue_severity": "blocker| tech_debt |skippable"
}

Resolution Loop Pattern

for attempt in range(1, MAX_ATTEMPTS + 1):
    review_result = run_review()

    if review_result.success:
        break  # No blockers

    blockers = filter(issues, severity="blocker")

    for blocker in blockers:
        create_patch(blocker)
        implement_patch()

    # Loop continues with re-review

Integration with SDLC

/plan    → What are we building?
/build   → Make it real
/test    → Does it work?
/review  → Is it what we asked for? ← THIS SKILL
/patch   → Fix blockers
/document → How does it work?

Best Practices

Screenshots are proof: They show stakeholders what was delivered
Specs are truth: Review against spec, not assumptions
Severity matters: Only blockers need immediate resolution
Retry limits: Prevent infinite loops (3 attempts typical)
Document tech debt: Don't lose the information

Memory References

@review-vs-test.md - The distinction this skill implements
@issue-severity-classification.md - How to classify issues
@one-agent-one-purpose.md - Review as a focused purpose

Version History

v1.0.0 (2025-12-26): Initial release

Last Updated

Date: 2025-12-26 Model: claude-opus-4-5-20251101

review-workflow-design