Review

Purpose

The /review skill provides a human-in-the-loop feedback mechanism after the implementation plan is generated. It allows stakeholders to:

• Provide review comments on the proposed plan
• Ask clarifying questions about the implementation approach
• Approve the plan and proceed to coding

This skill bridges the gap between automated planning and implementation, ensuring human oversight of critical technical decisions.

Usage

/review [optional: review comments or questions]

Examples:

/review
# Interactive mode: asks for review comments, questions, or approval

/review Can we use React Query instead of manual state management?
# Direct question mode: processes the question and updates the plan

/review The error handling approach should include retry logic for network failures
# Direct feedback mode: incorporates feedback into the plan

Instructions

Prerequisites

1. Verify that the implementation plan exists:

   • Read the file at workflow/jira-to-github/<JIRA-NUMBER>/implementation-plan.md
   • If the file doesn't exist, inform the user to run /plan first

2. Read the current JIRA issue for context:

   • Read the file at workflow/jira-to-github/<JIRA-NUMBER>/current-issue.md

Review Process

Step 1: Determine Review Mode

If user provided input (review comments or questions):

• Parse the input to determine if it's:
  • Review comments (suggestions for changes)
  • Questions (seeking clarification)
  • Approval (e.g., "looks good", "approved", "skip")

If no input provided:

• Use the AskUserQuestion tool with these options:

Question: "How would you like to proceed with the implementation plan? (You can iterate multiple times before approving)"
Header: "Plan Review"
multiSelect: false
Options:
1. "Provide review comments"
   - Description: "I have specific suggestions or changes"
2. "Ask questions"
   - Description: "I need clarification on the approach"
3. "Approve and continue"
   - Description: "Plan looks good, proceed to implementation"

Step 1.5: Determine if Direct Input Was Provided

If user provided input as argument (e.g., /review Add retry logic):

• Parse the input as review comments
• Skip the AskUserQuestion step
• Proceed directly to Step 2: Process Feedback
• After processing, LOOP BACK to Step 1 (ask for next action)

If no input provided:

• Use AskUserQuestion as described in Step 1

Step 2: Process Feedback

For Review Comments:

1. Capture the feedback:

   • If "Provide review comments" selected: User provides specific comments
   • If direct argument provided (e.g., /review Add retry logic): Use that as feedback
   • If unclear or ambiguous: Ask follow-up clarification questions before proceeding

2. Analyze the feedback against current plan:

   • Identify which sections need updates (Implementation, Files, Testing, etc.)
   • Document changes needed

3. Spawn "Plan" sub-agent to revise the plan:

   Task: Revise implementation plan based on review feedback
   Context:
   - Current issue: <from current-issue.md>
   - Current plan: <from implementation-plan.md>
   - Review feedback: <user's comments>
   
   Generate updated implementation-plan.md incorporating the feedback
   

4. Save updated plan to workflow/jira-to-github/<JIRA-NUMBER>/implementation-plan.md

5. Create review log entry in workflow/jira-to-github/<JIRA-NUMBER>/review-log.md:

   ## Review Session <N> - <timestamp>
   
   ### Feedback Provided
   <numbered list of concise, actionable review comments>
   
   ### User Selection
   Option: [Provide review comments | Ask questions | Approve and continue]
   
   ### Changes Made
   | Section | Update | Impact |
   |---------|--------|--------|
   | <section> | <change> | <impact> |
   
   ### Status
   Plan revised → pending approval (proceeding to iteration <N+1>)
   

6. CRITICAL: Loop back to Step 1 - Ask user again: "How would you like to proceed with the updated plan?"

   • This ensures iterative refinement until approval
   • Track iteration count in review-log.md
   • Use the same AskUserQuestion format from Step 1

   Token Optimization Guidelines:

   • Use diff format for code comparisons:

     - old code
     + new code
     

   • Use bullet points for benefits (not paragraphs):

     **Benefits**:
     - Benefit 1
     - Benefit 2
     

   • Use tables for structured changes
   • Be concise: Focus on what changed, avoid verbose explanations
   • Avoid duplication: Don't repeat information from the plan

For Questions:

1. Analyze questions in context of the plan

2. Provide detailed answers addressing:

   • Technical approach rationale
   • Alternative approaches considered
   • Trade-offs and implications
   • Implementation details

3. Ask follow-up using AskUserQuestion:

   Question: "Does this answer your questions, or would you like to proceed differently?"
   Header: "Next Step"
   multiSelect: false
   Options:
   1. "Approve plan"
      - Description: "Questions answered, plan looks good"
   2. "More questions"
      - Description: "I have additional questions"
   3. "Request changes"
      - Description: "I'd like to revise the plan"
   

4. Handle response:

   • If "Approve plan": Mark as approved, log in review-log.md, EXIT
   • If "More questions": LOOP BACK to Step 1 (ask for next action)
   • If "Request changes": LOOP BACK to Step 2 (process as feedback)

5. Log Q&A in workflow/jira-to-github/<JIRA-NUMBER>/review-log.md

For Approval:

1. Mark the plan as approved
2. Create concise approval entry in workflow/jira-to-github/<JIRA-NUMBER>/review-log.md:

   ## Review Session - <timestamp>
   
   ### Status
   ✓ Plan approved
   
   ### Next Steps
   - `/branch` - create development branch
   - `/code` - implement the plan
   
   **Note**: If `/code` already ran, re-run to implement updated plan
   

3. Inform the user that the workflow can continue with /branch or return to /jira-to-github orchestrator
4. If /code was already executed and the plan was updated, inform the user they can re-run /code to implement the updated plan changes

Step 3: Iteration Tracking

• Each time feedback is provided, increment iteration counter
• Track all review cycles in review-log.md with timestamps and iteration numbers
• Support unlimited iterations until approval
• After each plan revision, automatically re-enter review mode (loop back to Step 1)
• Each iteration is logged as:

  ## Review Session <N> - <timestamp>
  
  ### Feedback Provided
  [Iteration N feedback]
  
  ### User Selection
  Option: [Provide review comments | Ask questions | Approve and continue]
  
  ### Changes Made
  | Section | Update | Impact |
  |---------|--------|--------|
  | [...] | [...] | [...] |
  
  ### Status
  Plan revised → pending approval (iteration <N+1>)
  

Output Files

1. review-log.md: Complete audit trail of all review sessions

   • Timestamp for each session
   • Feedback provided
   • Questions asked and answered
   • Plan revisions made
   • Approval status

2. implementation-plan.md (updated): Revised plan incorporating all feedback

Token Optimization Principles

Target: 6.5-7 KB per review-log.md (current average: 8.8 KB) Savings Goal: 20-25% token reduction

Key Strategies

1. Use Diff Format for Code:

   - old code
   + new code
   

   Instead of separate "Before" and "After" sections

2. Bullet Points for Benefits:

   **Benefits**:
   - Benefit 1
   - Benefit 2
   

   Instead of paragraph explanations

3. Tables for Structured Data:

   | File | Update | Impact |
   |------|--------|--------|
   

   Instead of verbose descriptions

4. Concise Language:

   • Focus on what changed
   • Avoid verbose explanations
   • Remove redundant information

Error Handling

• If implementation-plan.md doesn't exist:

  Error: No implementation plan found. Please run /plan first.
  Suggested next step: /plan
  

• If current-issue.md doesn't exist:

  Error: No JIRA issue context found. Please run /pull <JIRA-KEY> first.
  Suggested next step: /pull <JIRA-KEY>
  

• If unable to parse review feedback or direct input argument:

  Error: Could not understand the feedback. Please rephrase or choose from:
  1. Provide specific review comments
  2. Ask clarifying questions
  3. Approve the plan with "approved" or "looks good"
  
  Tip: You can use /review without arguments for interactive mode.
  

Example Sessions

Example 1: Interactive Review with Approval

User: /review
Agent: How would you like to proceed with the implementation plan?

Options:
1. Provide review comments
2. Ask questions
3. Approve and continue

User: [Selects option 3]

Agent: Plan approved!

Plan review log created at: workflow/jira-to-github/DRT-17270/review-log.md

Next steps:
- /branch (create development branch)
- /code (implement the plan)

Review Log Output (Optimized Format):

## Review Session 1 - 2026-02-19

### User Selection
Option: Approve and continue

### Status
✓ Plan approved after 1 iteration

### Next Steps
- `/branch` - create development branch
- `/code` - implement the plan

Example 2: Direct Feedback with Plan Revision

User: /review Add exponential backoff retry logic for all network calls

Agent: Analyzing feedback and updating plan...

[Spawns Plan agent to revise implementation plan]

Plan updated - see review-log.md for details

Would you like to:
1. Review the updated plan again
2. Approve and continue

User: [Selects option 2]

Agent: Plan approved! Ready to proceed with /branch or /code

Review Log Output (Optimized Format):

## Review Session 1 - 2026-02-19T14:22:00Z

### Feedback Provided
1. Add exponential backoff retry logic for all network calls

### User Selection
Option: Provide review comments (direct argument: `/review Add exponential backoff retry logic for all network calls`)

### Changes Made
| Section | Update | Impact |
|---------|--------|--------|
| Utilities | Added retry utility with exponential backoff | New file |
| Network calls | Wrapped all calls with retry logic | 5 files modified |
| Error handling | Added retry support | Updated |

### Status
Plan revised → pending approval (iteration 2)

---

## Review Session 2 - 2026-02-19T14:28:00Z

### User Selection
Option: Approve and continue

### Status
✓ Plan approved after 2 iterations

### Next Steps
- `/branch` - create development branch
- `/code` - implement the plan

Example 3: Code Comparison with Diff Format

User: /review In AddCardForm, can we use a cardType prop instead of detecting via activeScreen?

Agent: Analyzing architectural improvement...

Plan updated to use prop-based approach instead of hook dependency.

Review Log Output (Optimized Format):

## Review Session 1 - 2026-02-19T18:32:00Z

### Feedback Provided
1. Use `cardType` prop instead of detecting via `activeScreen` in AddCardForm

### User Selection
Option: Provide review comments (direct argument)

### Approach Change
```diff
- const { activeScreen } = useFlyoutState();
- const isFsaHsaFlow = activeScreen === FlyoutScreens.ADD_FSA_HSA_CARD;
+ interface AddCardFormProps {
+   cardType?: 'regular' | 'benefit';
+ }
+ const isBenefitCard = cardType === 'benefit';

Benefits

• Better separation of concerns
• Easier testing (no hook mocking)
• Improved component reusability
• Clearer component contract

Changes Made

Status

Plan revised → pending approval (iteration 2)

Review Session 2 - 2026-02-19T18:35:00Z

User Selection

Option: Approve and continue

Status

✓ Plan approved after 2 iterations

Next Steps

• /branch - create development branch
• /code - implement the plan

### Example 4: Re-Implementation After Initial Coding

Initial workflow

User: /pull DRT-17270 User: /plan User: /review User: (approves plan) User: /branch User: /code

Code is implemented, but user realizes plan needs changes

User: /review The error handling should use toast notifications instead of modal dialogs

Agent: Analyzing feedback and updating plan...

Plan updated with the following changes:

• Changed error UI from modal dialogs to toast notifications
• Updated error handling utility to use toast API
• Removed modal dialog components
• Added toast notification styling

Plan review log updated at: workflow/jira-to-github/DRT-17270/review-log.md

Note: Since /code was already run, you can re-run it to implement these changes:

/code

This will read the updated plan and apply incremental changes to the codebase.

Would you like to approve this updated plan?

User: Yes

Agent: Plan approved! Run /code to implement the updated plan changes.

### Example 4: Question and Answer Session

User: /review Why are we using Zustand instead of React Context for this feature?

Agent: Good question! The plan chose Zustand over React Context for the following reasons:

1. Performance: Zustand provides fine-grained subscriptions, so components only re-render when their specific slice of state changes. React Context would cause all consumers to re-render on any state change.

2. Team Pattern: The WHPP application already uses Zustand for state management (see src/store/), so this maintains consistency with existing code.

3. Developer Experience: Zustand has simpler syntax and doesn't require Provider wrapper components, reducing boilerplate.

4. Testing: Zustand stores are easier to test in isolation compared to Context-based state.

Alternative approaches considered:

• React Context: Simple but performance concerns for frequent updates
• Redux Toolkit: More powerful but overkill for this feature's scope

Does this answer your question, or would you like to revise the plan?

Options:

1. This answers my questions - approve plan
2. I have more questions
3. I'd like to request plan changes

User: [Selects option 1]

Agent: Plan approved! Ready to proceed with /branch and /code

### Example 5: Iterative Review with Direct Input Argument

User: /review Add exponential backoff

Agent: Analyzing feedback and updating plan...

[Spawns Plan agent to revise implementation plan]

Plan updated with retry logic using exponential backoff.

How would you like to proceed with the updated plan? (You can iterate multiple times before approving)

Options:

1. Provide review comments
2. Ask questions
3. Approve and continue

User: [Selects option 2 - Ask questions]

User: Will the backoff apply to all API calls or just specific ones?

Agent: The exponential backoff will apply to all network calls that can be safely retried (GET requests and idempotent operations). POST/PUT/DELETE operations that are not idempotent will have single retry with user confirmation.

Does this answer your questions, or would you like to proceed differently?

Options:

1. Approve plan
2. More questions
3. Request changes

User: [Selects option 3 - Request changes]

User: Let's make all retry logic configurable per-endpoint instead

Agent: Analyzing feedback and updating plan...

[Spawns Plan agent to revise implementation plan]

Plan updated with configurable retry policies per endpoint.

How would you like to proceed with the updated plan?

Options:

1. Provide review comments
2. Ask questions
3. Approve and continue

User: [Selects option 3]

Agent: Plan approved after 3 iterations! Ready to proceed with /branch and /code

**Review Log Output**:
```markdown
## Review Session 1 - 2026-02-19T10:15:00Z

### Feedback Provided
1. Add exponential backoff

### User Selection
Option: Provide review comments (direct argument: `/review Add exponential backoff`)

### Changes Made
| Section | Update | Impact |
|---------|--------|--------|
| Utilities | Added retry utility with exponential backoff | New file |
| Network calls | Wrapped all calls with retry logic | 5 files modified |

### Status
Plan revised → pending approval (iteration 2)

---

## Review Session 2 - 2026-02-19T10:18:00Z

### Question Asked
Will the backoff apply to all API calls or just specific ones?

### Answer Provided
The exponential backoff will apply to all network calls that can be safely retried (GET requests and idempotent operations). POST/PUT/DELETE operations that are not idempotent will have single retry with user confirmation.

### User Selection
Option: Request changes

### Feedback Provided
1. Make all retry logic configurable per-endpoint instead

### Changes Made
| Section | Update | Impact |
|---------|--------|--------|
| Utilities | Updated retry utility to accept per-endpoint config | Modified |
| Network calls | Added retry configuration interface | New type |
| API config | Added retry policy definitions | New file |

### Status
Plan revised → pending approval (iteration 3)

---

## Review Session 3 - 2026-02-19T10:22:00Z

### User Selection
Option: Approve and continue

### Status
✓ Plan approved after 3 iterations

### Next Steps
- `/branch` - create development branch
- `/code` - implement the plan

Example 6: Multiple Iterations Until Approval

User: /review

Agent: How would you like to proceed with the implementation plan? (You can iterate multiple times before approving)

Options:
1. Provide review comments
2. Ask questions
3. Approve and continue

User: [Selects option 1]

User: The component should use compound pattern instead of prop drilling

Agent: Analyzing feedback and updating plan...

[Updates plan to use compound component pattern]

Plan updated. How would you like to proceed with the updated plan?

User: [Selects option 1 again]

User: Also add TypeScript generics for better type safety

Agent: Analyzing feedback and updating plan...

[Updates plan to add TypeScript generics]

Plan updated. How would you like to proceed with the updated plan?

User: [Selects option 2]

User: How will this affect bundle size?

Agent: The compound pattern and generics are compile-time features, so they have zero runtime cost. Bundle size impact is negligible (estimated +0.5KB gzipped for the additional type definitions).

Does this answer your questions, or would you like to proceed differently?

Options:
1. Approve plan
2. More questions
3. Request changes

User: [Selects option 1]

Agent: Plan approved after 3 iterations! Ready to proceed with /branch and /code

Review Log Output:

## Review Session 1 - 2026-02-19T15:30:00Z

### Feedback Provided
1. Use compound pattern instead of prop drilling

### User Selection
Option: Provide review comments

### Changes Made
| Section | Update | Impact |
|---------|--------|--------|
| Component architecture | Changed to compound component pattern | Major refactor |
| Props interface | Simplified by removing drilled props | Reduced complexity |

### Status
Plan revised → pending approval (iteration 2)

---

## Review Session 2 - 2026-02-19T15:33:00Z

### Feedback Provided
1. Add TypeScript generics for better type safety

### User Selection
Option: Provide review comments

### Changes Made
| Section | Update | Impact |
|---------|--------|--------|
| Type definitions | Added generic type parameters | Enhanced type safety |
| Component interface | Updated to use generics | Modified |

### Status
Plan revised → pending approval (iteration 3)

---

## Review Session 3 - 2026-02-19T15:36:00Z

### Question Asked
How will this affect bundle size?

### Answer Provided
The compound pattern and generics are compile-time features, so they have zero runtime cost. Bundle size impact is negligible (estimated +0.5KB gzipped for the additional type definitions).

### User Selection
Option: Approve plan

### Status
✓ Plan approved after 3 iterations

### Next Steps
- `/branch` - create development branch
- `/code` - implement the plan

Re-Implementation Workflow

When /review is used after /code has already been executed:

1. User Updates Plan: Provide feedback via /review to revise the implementation plan
2. Plan Gets Updated: The implementation-plan.md file is updated with new requirements
3. Re-run Code: Execute /code again to implement the updated plan
4. Incremental Changes: The /code skill detects previous implementation and applies only the changes from the updated plan
5. Revision Log: The implementation-log.md is appended with a revision section documenting the changes

Benefits:

• Supports iterative development and plan refinement
• Maintains audit trail of all plan revisions
• Allows fixing implementation approach without starting over
• Enables incremental updates to codebase

Example Workflow:

# Initial implementation
/pull DRT-17270 → /plan → /review (approve) → /branch → /code

# Realize plan needs changes
/review "Add validation for edge cases"

# Re-implement with updated plan
/code  # Reads updated plan, applies incremental changes