# Review > Purpose - Skill: `valasubramanian-kr/review` (Agent Skill) - Install (CLI): `npx skillmds@latest add valasubramanian-kr/review` - Raw SKILL.md: https://api.skillmd.com/api/skills/valasubramanian-kr/review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: valasubramanian-kr (https://skillmd.com/u/valasubramanian-kr) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/valasubramanian-kr/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//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//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: - Current plan: - Review feedback: Generate updated implementation-plan.md incorporating the feedback ``` 4. Save updated plan to `workflow/jira-to-github//implementation-plan.md` 5. Create review log entry in `workflow/jira-to-github//review-log.md`: ```markdown ## Review Session - ### Feedback Provided ### User Selection Option: [Provide review comments | Ask questions | Approve and continue] ### Changes Made | Section | Update | Impact | |---------|--------|--------| |
| | | ### Status Plan revised → pending approval (proceeding to iteration ) ``` 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: ```diff - old code + new code ``` - **Use bullet points** for benefits (not paragraphs): ```markdown **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//review-log.md` **For Approval**: 1. Mark the plan as approved 2. Create concise approval entry in `workflow/jira-to-github//review-log.md`: ```markdown ## Review Session - ### 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: ```markdown ## Review Session - ### 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 ) ``` ## 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**: ```diff - old code + new code ``` Instead of separate "Before" and "After" sections 2. **Bullet Points for Benefits**: ```markdown **Benefits**: - Benefit 1 - Benefit 2 ``` Instead of paragraph explanations 3. **Tables for Structured Data**: ```markdown | 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 first. Suggested next step: /pull ``` - 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): ```markdown ## 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): ```markdown ## 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): ```markdown ## 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 | File | Update | |------|--------| | AddCardForm.tsx | Added cardType prop, removed useFlyoutState() | | PaymentMethodManager.tsx | Passes cardType prop to AddCardForm | ### 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: ```bash /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**: ```markdown ## 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**: ```bash # 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 ```