microsoft/hve-core
Publicmirrored fromhttps://github.com/microsoft/hve-coreAvailable
docs/rpi/task-reviewer.md
195lines · modecode
| 1 | --- |
| 2 | title: Task Reviewer Guide |
| 3 | description: Use the Task Reviewer custom agent to validate implementation against research and plan specifications |
| 4 | author: Microsoft |
| 5 | ms.date: 2026-01-24 |
| 6 | ms.topic: tutorial |
| 7 | keywords: |
| 8 | - task reviewer |
| 9 | - rpi workflow |
| 10 | - review phase |
| 11 | - github copilot |
| 12 | estimated_reading_time: 4 |
| 13 | --- |
| 14 | |
| 15 | The Task Reviewer custom agent validates completed implementation work against research and plan specifications. It checks convention compliance, runs validation commands, and produces review logs with findings and follow-up work. |
| 16 | |
| 17 | ## When to Use Task Reviewer |
| 18 | |
| 19 | Use Task Reviewer after completing implementation when you need: |
| 20 | |
| 21 | * ✅ **Specification validation** against research and plan documents |
| 22 | * 📋 **Convention compliance** checking against instruction files |
| 23 | * 🔍 **Change verification** comparing actual changes to planned changes |
| 24 | * 📝 **Structured findings** with severity levels and evidence |
| 25 | |
| 26 | ## What Task Reviewer Does |
| 27 | |
| 28 | 1. **Locates** review artifacts (research, plan, changes logs) |
| 29 | 2. **Extracts** implementation checklist from source documents |
| 30 | 3. **Validates** each item with evidence from the codebase |
| 31 | 4. **Runs** validation commands (lint, build, test) |
| 32 | 5. **Documents** findings with severity levels |
| 33 | 6. **Identifies** follow-up work for future implementation |
| 34 | |
| 35 | > [!NOTE] |
| 36 | > **Why the constraint matters:** Task Reviewer validates against documented specifications, not assumptions. Because it can only review what was documented, gaps in research or planning become visible. This feedback loop improves future RPI cycles. |
| 37 | |
| 38 | ## Output Artifact |
| 39 | |
| 40 | Task Reviewer creates a review log at: |
| 41 | |
| 42 | ```text |
| 43 | .copilot-tracking/reviews/{{YYYY-MM-DD}}-<topic>-review.md |
| 44 | ``` |
| 45 | |
| 46 | This document includes: |
| 47 | |
| 48 | * Implementation checklist from research and plan |
| 49 | * Validation results with evidence |
| 50 | * Additional or deviating changes found |
| 51 | * Missing work and follow-up items |
| 52 | * Overall status (Complete, Needs Rework, Blocked) |
| 53 | |
| 54 | ## How to Use Task Reviewer |
| 55 | |
| 56 | ### Option 1: Use the Prompt Shortcut (Recommended) |
| 57 | |
| 58 | Type `/task-review` in GitHub Copilot Chat to start the review: |
| 59 | |
| 60 | ```text |
| 61 | /task-review |
| 62 | ``` |
| 63 | |
| 64 | This automatically switches to Task Reviewer and begins the review protocol. |
| 65 | |
| 66 | ### Option 2: Select the Custom Agent Manually |
| 67 | |
| 68 | 1. Open GitHub Copilot Chat (`Ctrl+Alt+I`) |
| 69 | 2. Click the agent picker dropdown at the top |
| 70 | 3. Select **Task Reviewer** |
| 71 | 4. Describe the scope of your review |
| 72 | |
| 73 | ### Option 3: Using Scope Parameters |
| 74 | |
| 75 | Specify a time-based scope to filter artifacts: |
| 76 | |
| 77 | ```text |
| 78 | /task-review today |
| 79 | /task-review this week |
| 80 | /task-review since last review |
| 81 | ``` |
| 82 | |
| 83 | Task Reviewer filters `.copilot-tracking/` artifacts by date prefix when you provide a scope. |
| 84 | |
| 85 | ### Step 2: Let It Validate |
| 86 | |
| 87 | Task Reviewer works autonomously to: |
| 88 | |
| 89 | * Locate related research, plan, and changes files |
| 90 | * Extract implementation checklist items |
| 91 | * Validate each item against the codebase |
| 92 | * Run applicable validation commands |
| 93 | * Document findings with severity levels |
| 94 | |
| 95 | ### Step 3: Review the Findings |
| 96 | |
| 97 | When complete, Task Reviewer provides: |
| 98 | |
| 99 | * Summary of validation activities |
| 100 | * Findings count by severity (Critical, Major, Minor) |
| 101 | * Review log location for detailed reference |
| 102 | * Next steps based on review outcome |
| 103 | |
| 104 | ## Example Prompts |
| 105 | |
| 106 | Basic review of recent work: |
| 107 | |
| 108 | ```text |
| 109 | /task-review |
| 110 | Review the blob storage implementation completed today. |
| 111 | ``` |
| 112 | |
| 113 | Review with specific artifact reference: |
| 114 | |
| 115 | ```text |
| 116 | /task-review |
| 117 | Validate against: |
| 118 | - Research: .copilot-tracking/research/2025-01-28-blob-storage-research.md |
| 119 | - Plan: .copilot-tracking/plans/2025-01-28-blob-storage-plan.instructions.md |
| 120 | - Changes: .copilot-tracking/changes/2025-01-28-blob-storage-changes.md |
| 121 | ``` |
| 122 | |
| 123 | ## Understanding Severity Levels |
| 124 | |
| 125 | Task Reviewer categorizes findings by impact: |
| 126 | |
| 127 | | Severity | Description | Example | |
| 128 | |--------------|-----------------------------------------------------------------|------------------------------------------------| |
| 129 | | **Critical** | Implementation incorrect or missing required functionality | Missing authentication on public endpoint | |
| 130 | | **Major** | Implementation deviates from specifications or conventions | Used deprecated API instead of recommended one | |
| 131 | | **Minor** | Style issues, documentation gaps, or optimization opportunities | Missing inline comment on complex logic | |
| 132 | |
| 133 | ## Tips for Better Reviews |
| 134 | |
| 135 | ✅ **Do:** |
| 136 | |
| 137 | * Review after each implementation phase when possible |
| 138 | * Use time-based scopes for focused reviews |
| 139 | * Address Critical and Major findings before committing |
| 140 | * Let Minor findings accumulate for batch fixes |
| 141 | |
| 142 | ❌ **Don't:** |
| 143 | |
| 144 | * Skip reviews for multi-file changes |
| 145 | * Ignore convention compliance warnings |
| 146 | * Commit without addressing Critical findings |
| 147 | |
| 148 | ## Common Pitfalls |
| 149 | |
| 150 | | Pitfall | Solution | |
| 151 | |---------------------|----------------------------------------------------------| |
| 152 | | No artifacts found | Complete implementation first; verify changes log exists | |
| 153 | | Research not linked | Ensure plan references research document | |
| 154 | | Too many findings | Break implementation into smaller phases | |
| 155 | |
| 156 | ## Next Steps |
| 157 | |
| 158 | After Task Reviewer completes, the review status determines your path: |
| 159 | |
| 160 | ### When Status is Complete |
| 161 | |
| 162 | 1. **Commit** your changes with a descriptive message |
| 163 | 2. **Clean up** planning files if no longer needed |
| 164 | 3. **Start** the next RPI cycle for additional work |
| 165 | |
| 166 | ### When Findings Require Rework |
| 167 | |
| 168 | 1. **Clear context** using `/clear` |
| 169 | 2. **Open** the review log in your editor |
| 170 | 3. **Return to implementation** using `/task-implement` |
| 171 | |
| 172 | Task Implementor uses the review findings to address Critical and Major issues. |
| 173 | |
| 174 | ### When Follow-Up Items Need Research |
| 175 | |
| 176 | 1. **Clear context** using `/clear` |
| 177 | 2. **Open** the review log in your editor |
| 178 | 3. **Start research** using `/task-research` |
| 179 | |
| 180 | Review findings become input for the next research cycle. |
| 181 | |
| 182 | ### When Additional Planning Is Needed |
| 183 | |
| 184 | 1. **Clear context** using `/clear` |
| 185 | 2. **Open** the review log in your editor |
| 186 | 3. **Revise plan** using `/task-plan` |
| 187 | |
| 188 | Task Planner incorporates review findings into updated planning. |
| 189 | |
| 190 | --- |
| 191 | |
| 192 | <!-- markdownlint-disable MD036 --> |
| 193 | *🤖 Crafted with precision by ✨Copilot following brilliant human instruction, |
| 194 | then carefully refined by our team of discerning human reviewers.* |
| 195 | <!-- markdownlint-enable MD036 --> |
| 196 | |