
dev-lifecycle
Development lifecycle commands for GitHub issues and testing workflows
- version
- 1.0.0
Install
/plugin install dev-lifecycle@my-claude-marketplaceRun it inside Claude Code after adding the marketplace with /plugin marketplace add rmakowiak/my-claude-marketplace.
Contents
Discovered from sourceCommands 13
Commit and Manage Pull Request (GitHub)
Create a commit on a GitHub issue branch and manage the associated pull request. Follow the Instructions to commit changes, then create or update the PR.
Variables
files: $1 (optional - if not provided, stages all changes)
Instructions
1. Validate Branch
- IMPORTANT: Check current branch with
git branch --show-current - Verify the branch follows the pattern:
<issue_number>/<issue_type>-<slug> - If branch is
mainor doesn't match the pattern, ERROR and stop:- "Cannot run issue:commit on branch '<branch_name>'. Must be on an issue branch with format: <issue_number>/<issue_type>-"
- Extract the issue number from the branch name (the part before the
/)
2. Create Commit
- Generate commit message elements:
changes_class: Extract from branch (feat/fix/chore from the<issue_type>part)changes_description: Brief description of changes (present tense, 50 chars max, no period)
- Commit message format:
<changes_class>: <commit_message>- IMPORTANT: Do NOT include issue number in commit message
- Examples:
feat: add conversation history endpointfix: resolve chat validation errorchore: update API documentation
- Stage changes:
- IF
filesis provided:git add <files> - ELSE:
git add -A
- IF
- Run
git diff HEADto understand changes - Run
git commit -m "<generated_commit_message>"to create commit
3. Check for Existing PR
- Use
gh pr list --head <current_branch_name>to check if PR exists - If PR exists:
- Push the commit:
git push origin <branch_name> - Fetch the issue details:
gh issue view <issue_number> - Update PR description to include a summary of all work done so far
- Use
gh pr edit <pr_number> --body "<updated_description>"
- Push the commit:
- If NO PR exists:
- Push the branch:
git push -u origin <branch_name> - Fetch the issue details:
gh issue view <issue_number> - Create PR with:
- Title format:
#<issue_number>: <issue_title> - Body should include:
- Brief summary of changes (1-2 paragraphs)
- Link to issue:
Resolves #<issue_number>
- Use
gh pr create --title "<title>" --body "<body>"
- Title format:
- Push the branch:
4. PR Description Format
When creating or updating PR description, use this format:
## Summary
<1-2 paragraph summary of what was implemented and why>
## Changes
<bulleted list of key changes made>
- Change 1
- Change 2
- Change 3
## Testing
<brief note on how to test the changes>
---
Resolves #<issue_number>
Report
After committing and managing PR, report:
- The commit message used
- Whether a new PR was created or an existing PR was updated
- The PR number and URL
- The issue number linked
Example for new PR:
ā
Committed: feat: add conversation history endpoint
š Created PR #45: #123: Add conversation history
š https://github.com/<owner>/<repo>/pull/45
š Resolves: #123
Example for existing PR:
ā
Committed: feat: update conversation list UI
š¤ Pushed to existing PR #45: #123: Add conversation history
š https://github.com/<owner>/<repo>/pull/45
š Updated PR description with latest changes
Create GitHub Issue (GitHub)
Create a new GitHub issue using the exact specified markdown Issue Format. Follow the Instructions to create the issue and use the Relevant Files to focus on the right files.
Variables
issue_description: $1
Instructions
- IMPORTANT: Read
CLAUDE.mdfor project context, architecture patterns, and conventions. - IMPORTANT: You're creating a GitHub issue to track work based on the
Issue Requestthat will add value to the application. - IMPORTANT: The
Issue Requestdescribes the work that will be done but remember we're not implementing it yet, we're creating the GitHub issue that will be used to track and implement the work based on theIssue Formatbelow. - Research the codebase to understand existing patterns, architecture, and conventions before planning the issue:
- Explore similar features already implemented
- Understand the file structure and module organization
- Identify existing patterns to follow
- Find relevant test files and patterns
- IMPORTANT: Replace every in the
Issue Formatwith the requested value. Add as much detail as needed to implement the work successfully. - Use your reasoning model: THINK HARD about the requirements, design, technical approach, and implementation details.
- Follow existing patterns and conventions in the codebase. Don't reinvent the wheel.
- Design for extensibility and maintainability.
- If you need a new library, mention it in the
Technical Taskssection with installation command. - Don't use decorators. Keep it simple.
- Respect requested files in the
Relevant Filessection. - Start your research by reading the
CLAUDE.mdandREADME.mdfiles. - After creating the issue body, use the GitHub CLI to create the issue:
- Use
gh issue createwith the formatted body - Add appropriate labels based on the issue type (e.g., "feature", "bug", "chore", "frontend", "backend", "fullstack")
- Add any relevant feature area labels, try to choose from existing first, if does not work, create new label
- Use
- After creation, report the issue number and URL
Relevant Files
Focus on the following files:
CLAUDE.md- Contains project context, architecture, patterns, and conventions.README.md- Contains the project overview and setup instructions.apps/api/src/**- Contains the backend codebase.apps/ui/src/**- Contains the frontend codebase.apps/api/*.http- Contains HTTP request examples for manual testing.test/**- Contains tests
Ignore all other files in the codebase.
Issue Format
The GitHub issue body should be formatted as follows:
# <Issue Title>
**Type:** <Feature|Bug|Chore>
**Dependencies:** <list of issue numbers this depends on, or "None">
---
## User Story
**As a** <type of user>
**I want to** <action/goal>
**So that** <benefit/value>
---
## Scope
<describe the scope of work in 2-3 sentences, what will be done>
### What's Included
<bulleted list of specific features/functionality that will be implemented>
- Item 1
- Item 2
- Item 3
### What's NOT Included
<bulleted list of related features that are explicitly out of scope for this issue>
- Item 1
- Item 2
- Item 3
---
## Technical Tasks
<organize tasks by area/phase with clear h3 headers. Be specific and detailed. Include code examples where helpful. Break down into logical sections like "Backend - API Changes", "Frontend - Components", "Database Changes", "Testing", etc.>
### <Task Area 1>
- [ ] Task 1
<optional: include code snippet or technical details>
- [ ] Task 2
- [ ] Task 3
### <Task Area 2>
- [ ] Task 1
- [ ] Task 2
### Update .http File
- [ ] Add relevant HTTP examples to test the changes manually
```http
### Example Request
GET http://localhost:3001/api/...
Acceptance Criteria
<list specific, testable criteria that must be met for the issue to be considered complete. Be precise and measurable.>
<Category 1>
- Criterion 1
- Criterion 2
<Category 2>
- Criterion 1
- Criterion 2
Testing Checklist
<Test Category 1>
-
Test Name
- Step 1
- Step 2
- Expected result
-
Test Name
- Step 1
- Step 2
- Expected result
<Test Category 2>
- Test Name
- Step 1
- Step 2
- Expected result
E2E Test Cases
<Feature Area 1>
-
Test Case Name
- Setup: Initial state/preconditions (e.g., user logged in, specific data exists)
- Steps:
- User action (e.g., Navigate to /dashboard)
- System response (e.g., Dashboard loads with data)
- User action (e.g., Click "Add Meal" button)
- System response (e.g., Modal opens)
- Expected Result: What should happen at the end of the flow
- Assertions: Specific checks to make (e.g., meal appears in list, API called with correct data, UI updates)
-
Test Case Name
- Setup: ...
- Steps: ...
- Expected Result: ...
- Assertions: ...
<Feature Area 2>
- Test Case Name
- Setup, Steps, Expected Result, Assertions...
Error Scenarios
- Error Case Name
- Setup: Preconditions that trigger the error
- Steps: Actions that cause the error
- Expected Result: How the error should be handled
- Assertions: Error messages, UI state, etc.
Definition of Done
- All technical tasks completed
- All acceptance criteria met
- Manual testing completed
- Code follows existing patterns
- No regressions introduced
- .http file updated (if applicable)
- Error handling implemented
- Loading states implemented (if UI changes)
Notes
Design Decisions
Decision 1
- Rationale
Decision 2
- Rationale
Alternative Approaches Considered
Approach 1
- Pros: ...
- Cons: ...
- Decision: ...
User Experience Flow
<if applicable, document the user flow in a step-by-step manner>
1. User action
2. System response
3. User action
4. System response
Future Enhancements (Out of Scope)
- Enhancement 1
- Enhancement 2
- Enhancement 3
<add any additional sections relevant to this issue, such as:>
- Accessibility Considerations
- Performance Considerations
- Security Considerations
- Data Migration Notes
- API Contract Changes
- etc.
Review Points
When reviewing this issue, check:
- <Question 1>
- <Question 2>
- <Question 3> <list key questions/checkpoints for code review>
## Issue Request
$1
## Report
After creating the GitHub issue, report:
1. The GitHub issue number
2. The GitHub issue URL
3. The labels applied
4. Any related issues it was linked to
Example:
ā
Created GitHub Issue #123: Add conversation history
š URL: https://github.com/<owner>/<repo>/issues/123
š·ļø Labels: feature, backend, chat
š Related: #456, #789
Implement GitHub Issue (GitHub)
Fetch a GitHub issue and implement it. Follow the Instructions to implement the issue then Report the completed work.
Variables
issue_number: $1
Instructions
- IMPORTANT: First, fetch the GitHub issue using
gh issue view {issue_number}to get the full issue details. - IMPORTANT: Before starting implementation, create and switch to a new branch:
- Branch naming format:
<issue_number>/<issue_type>-<slug>issue_number: The GitHub issue number from $1 (e.g., "123")issue_type: One of: feat, fix, chore (use "feat" for Feature issues, "fix" for Bug issues, "chore" for Chore issues)slug: 2-4 words from the issue title, kebab-case, max 40 chars total for slug- Example: "123/feat-conversation-history" or "45/fix-chat-validation"
- Use
git checkout -b <branch_name>to create and switch to the branch - Confirm the branch was created successfully with
git branch --show-current
- Branch naming format:
- IMPORTANT: Read
CLAUDE.mdfor project context, architecture patterns, and conventions. - Read the issue carefully, understand all requirements, technical tasks, and acceptance criteria.
- Think hard about the implementation approach and follow existing patterns in the codebase.
- Implement all technical tasks listed in the issue.
- Ensure all acceptance criteria are met.
- Follow the testing checklist if provided.
- Update the .http file if the issue involves API changes (per CLAUDE.md guidelines).
- Use the TodoWrite tool to track progress through the implementation.
- Mark tasks as complete in the GitHub issue as you finish them (use
gh issue commentto add progress updates). - IMPORTANT: Run E2E tests as guardrails throughout implementation:
- After each significant implementation milestone, run relevant E2E tests:
pnpm test:e2e - If tests fail, fix the implementation before proceeding to the next task
- Use E2E tests to validate the implementation matches requirements
- Before marking the issue as complete, run the full E2E test suite
- Ensure all relevant E2E tests pass
- If E2E tests need to be updated due to intentional behavior changes, update them and document why
- If new E2E tests are specified in the issue, implement them as part of the work
- After each significant implementation milestone, run relevant E2E tests:
- IMPORTANT: After implementation, update
CLAUDE.mdif any project-relevant changes were made:- New features added to "Current Features" section
- New architectural patterns or conventions introduced
- New key file locations or module structures
- Changes to tech stack or dependencies
- New development guidelines or best practices
- Do NOT update if changes are purely bug fixes or minor refactors
Report
After implementation, provide:
- Branch name used for implementation
- Summary of the work completed in a concise bullet point list
- Files and total lines changed with
git diff --stat - Status of all acceptance criteria (which ones are met)
- E2E test results (pass/fail, any tests updated or added)
- Any notes or decisions made during implementation
- Changes made to
CLAUDE.md(if any) and why - Suggest next steps or related issues to tackle
GitHub Issue Review
Follow the Instructions below to review work done against a GitHub issue to ensure implemented features match requirements. Use the issue to understand the requirements and then use the git diff if available to understand the changes made. Capture screenshots of critical functionality paths as documented in the Instructions section. If there are issues, report them if not then report success.
Variables
issue_number: $1 (optional - if not provided, extract from current branch)
run_id: generate a random 8 character hex string
review_image_dir: <absolute path to codebase>/agents/<run_id>/review_img/
Instructions
1. Determine Issue Number
- Check current branch with
git branch --show-current - IF
issue_numberparameter is provided:- Use the provided issue number
- ELSE:
- Verify branch follows pattern:
<issue_number>/<issue_type>-<slug> - If branch is
mainor doesn't match pattern, ERROR and stop:- "Cannot run issue:review on branch '<branch_name>'. Must provide issue number or be on an issue branch with format: <issue_number>/<issue_type>-"
- Extract issue number from branch name (the part before the
/)
- Verify branch follows pattern:
2. Analyze Changes
- Run
git diff origin/mainto see all changes made in current branch. Continue even if there are no changes related to the issue. - Fetch the GitHub issue using
gh issue view {issue_number}to get the full issue details. - Read the issue to understand requirements
3. Setup Review Environment
- IMPORTANT: Execute
.claude/commands/issue/review/prepare_review_env.mdto start the review environment - This will start both API and UI on review-specific ports using Docker Compose
4. Validate Implementation
- IMPORTANT: If the work can be validated by UI validation then (if not skip the section):
- Look for corresponding e2e test files in
teststhat mirror the feature name. - IF tests are found:
- Use e2e test files only as navigation guides for screenshot locations, not for other purposes
- ELSE:
- Try to navigate yourself around the app
- IMPORTANT: To be clear, we're not testing. We know the functionality works. We're reviewing the implementation against the issue to make sure it matches what was requested.
- IMPORTANT: Take screen shots along the way to showcase the new functionality and any issues you find
- Capture visual proof of working features through targeted screenshots
- Navigate to the application and capture screenshots of only the critical paths based on the isue
- Compare implemented changes with isue requirements to verify correctness
- Do not take screenshots of the entire process, only the critical points.
- IMPORTANT: Aim for
1-5screenshots to showcase that the new functionality works as specified. - If there is a review issue, take a screenshot of the issue and add it to the
review_issuesarray. Describe the issue, resolution, and severity. - Number your screenshots in the order they are taken like
01_<descriptive name>.png,02_<descriptive name>.png, etc. - IMPORTANT: Be absolutely sure to take a screen shot of the critical point of the new functionality
- IMPORTANT: Copy all screenshots to the provided
review_image_dir - IMPORTANT: Store the screenshots in the
review_image_dirand be sure to use full absolute paths. - Focus only on critical functionality paths - avoid unnecessary screenshots
- Ensure screenshots clearly demonstrate that features work as specified
- Use descriptive filenames that indicate what part of the change is being verified
- Look for corresponding e2e test files in
5. Issue Severity Guidelines
- Think hard about the impact of the issue on the feature and the user
- Guidelines:
skippable- the issue is non-blocker for the work to be released but is still a problemtech_debt- the issue is non-blocker for the work to be released but will create technical debt that should be addressed in the futureblocker- the issue is a blocker for the work to be released and should be addressed immediately. It will harm the user experience or will not function as expected.
6. Output Results
- IMPORTANT: Return ONLY the JSON array with test results
- IMPORTANT: Output your result in JSON format based on the
Reportsection below. - IMPORTANT: Do not include any additional text, explanations, or markdown formatting
- We'll immediately run JSON.parse() on the output, so make sure it's valid JSON
- Ultra think as you work through the review process. Focus on the critical functionality paths and the user experience. Don't report issues if they are not critical to the feature.
7. Cleanup
- After review is complete, execute
.claude/commands/issue/review/cleanup_review_env.mdto shutdown the review environment
Report
- IMPORTANT: Return results exclusively as a JSON array based on the
Output Structuresection below. successshould betrueif there are NO BLOCKING issues (implementation matches isue for critical functionality)successshould befalseONLY if there are BLOCKING issues that prevent the work from being releasedreview_issuescan contain issues of any severity (skippable, tech_debt, or blocker)screenshotsshould ALWAYS contain paths to screenshots showcasing the new functionality, regardless of success status. Use full absolute paths.- This allows subsequent agents to quickly identify and resolve blocking errors while documenting all issues
Output Structure
{
success: "boolean - true if there are NO BLOCKING issues (can have skippable/tech_debt issues), false if there are BLOCKING issues",
review_summary: "string - 2-4 sentences describing what was built and whether it matches the isue. Written as if reporting during a standup meeting. Example: 'The natural language query feature has been implemented with drag-and-drop file upload and interactive table display. The implementation matches the spec requirements for SQL injection protection and supports both CSV and JSON formats. Minor UI improvements could be made but all core functionality is working as isueified.'",
review_issues: [
{
"review_issue_number": "number - the issue number based on the index of this issue",
"screenshot_path": "string - /absolute/path/to/screenshot_that_shows_review_issue.png",
"issue_description": "string - description of the issue",
"issue_resolution": "string - description of the resolution",
"issue_severity": "string - severity of the issue between 'skippable', 'tech_debt', 'blocker'"
},
...
],
screenshots: [
"string - /absolute/path/to/screenshot_showcasing_functionality.png",
"string - /absolute/path/to/screenshot_showcasing_functionality.png",
"...",
]
}
Review Environment Quick Start
TL;DR
# Run automated review
/issue:review 79 # With issue number
/issue:review # Auto-extract from branch
# Manual control
docker compose -f docker-compose.yml up -d --build # Start
docker compose -f docker-compose.yml ps # Status
docker compose -f docker-compose.yml logs -f # Logs
docker compose -f docker-compose.yml down # Stop
Ports
| Service | Dev | Review |
|---|---|---|
| API | 3001 | 3501 |
| UI | 3000 | 3500 |
URLs
- Review UI: http://localhost:3500
- Review API: http://localhost:3501
- Health Check: http://localhost:3501/health
Branch Format
<issue_number>/<issue_type>-<slug>
Examples:
79/feat-conversation-history
123/fix-auth-bug
456/chore-update-deps
Common Commands
Check if review env is running:
docker compose -f docker-compose.yml ps
View API logs:
docker compose -f docker-compose.yml logs -f api-review
View UI logs:
docker compose -f docker-compose.yml logs -f ui-review
Restart a service:
docker compose -f docker-compose.yml restart api-review
Rebuild after dependency changes:
docker compose -f docker-compose.yml up -d --build
Clean everything:
docker compose -f docker-compose.yml down -v
docker builder prune -f
Troubleshooting
Port in use:
lsof -ti:3500 3501 | xargs kill -9
Service not starting:
docker compose -f docker-compose.yml logs api-review
Changes not reflecting:
docker compose -f docker-compose.yml restart api-review ui-review
Start fresh:
docker compose -f docker-compose.yml down -v
docker compose -f docker-compose.yml up -d --build
Environment
Make sure .env exists with:
LLM_API_KEY=your-key
LLM_PROVIDER=openai
Output
Review creates directory:
agents/<run_id>/review_img/
āāā 01_description.png
āāā 02_description.png
āāā ...
And outputs JSON:
{
"success": true/false,
"review_summary": "...",
"review_issues": [...],
"screenshots": [...]
}
See Also
README.md- Comprehensive documentationprepare_review_env.md- Setup script detailscleanup_review_env.md- Teardown script details/REVIEW_SETUP.md- Full migration guide
Issue Review Environment
This directory contains scripts for setting up and managing an isolated review environment using Docker Compose.
Overview
The review environment runs the application on separate ports from development:
- API Review Port: 3501 (vs dev port 3001)
- UI Review Port: 3500 (vs dev port 3000)
This allows you to:
- Review changes in isolation without affecting your dev environment
- Run automated reviews with screenshots
- Test features on specific branches
Architecture
Docker Compose Setup
docker-compose.review.yml- Orchestrates both API and UI servicesDockerfile.review.api- API container configurationDockerfile.review.ui- UI container configuration
Package Scripts
Both API and UI have dev:review scripts that run on review ports:
apps/api/package.json-dev:reviewruns on port 3501apps/ui/package.json-dev:reviewruns on port 3500
Usage
Manual Control
Start review environment:
docker compose -f docker-compose.yml up -d --build
Check status:
docker compose -f docker-compose.yml ps
View logs:
docker compose -f docker-compose.yml logs -f
Stop environment:
docker compose -f docker-compose.yml down
Stop and remove volumes:
docker compose -f docker-compose.yml down -v
Automated Review
The issue:review command automatically manages the environment:
With issue number:
/issue:review 79
Auto-extract from branch:
# On branch 79/feat-conversation-history
/issue:review
Scripts
prepare_review_env.md
- Checks for running containers
- Builds and starts Docker Compose services
- Waits for services to be healthy
- Verifies API and UI are accessible
cleanup_review_env.md
- Stops and removes containers
- Verifies ports are freed
- Optional: Clean build cache
Environment Variables
API (Port 3501)
NODE_ENV=development
PORT=3501
API_URL=http://localhost:3501
UI_URL=http://localhost:3500
UI (Port 3500)
NODE_ENV=development
PORT=3500
NEXT_PUBLIC_API_URL=http://localhost:3501
Volume Mounts
Both services mount source code for hot-reload:
./apps/apiā/app/apps/api./apps/uiā/app/apps/ui./packagesā/app/packages
Node modules are kept in the container for performance.
Troubleshooting
Port already in use:
# Check what's using the port
lsof -ti:3500
lsof -ti:3501
# Kill the process
kill -9 $(lsof -ti:3500)
kill -9 $(lsof -ti:3501)
Containers won't start:
# Check logs
docker compose -f docker-compose.yml logs
# Rebuild from scratch
docker compose -f docker-compose.yml down -v
docker compose -f docker-compose.yml up -d --build
Changes not reflected:
# Restart specific service
docker compose -f docker-compose.yml restart api-review
docker compose -f docker-compose.yml restart ui-review
Development Notes
- Hot reload is enabled for both services
- Containers persist until explicitly stopped
- Separate from dev environment (ports 3000/3001)
- Build cache is preserved between runs
- Use
.dockerignoreto optimize build context
File Structure
.
āāā docker-compose.review.yml # Main orchestration
āāā Dockerfile.review.api # API container
āāā Dockerfile.review.ui # UI container
āāā .dockerignore # Build context optimization
āāā .claude/commands/issue/review/
āāā README.md # This file
āāā prepare_review_env.md # Startup script
āāā cleanup_review_env.md # Shutdown script
Cleanup Review Environment
Shutdown and cleanup the review environment Docker containers.
Instructions
1. Stop Review Containers
- Stop and remove containers:
pnpm docker-compose:down - OPTIONAL: Remove volumes if needed:
pnpm docker-compose:down -- -v
2. Verify Cleanup
- Check that containers are stopped:
pnpm docker-compose:ps - Confirm ports are freed:
- Port 3501 (API):
lsof -ti:3501should return nothing - Port 3500 (UI):
lsof -ti:3500should return nothing
- Port 3501 (API):
3. Optional: Clean Build Cache
- If you want to clean up Docker build cache (saves space):
docker builder prune -f
Notes
- Use
pnpm docker-compose:downinstead of docker compose commands directly - Available commands: docker-compose:up, docker-compose:down, docker-compose:logs, docker-compose:restart, docker-compose:ps
- This stops both API and UI review containers
- Does not affect the main development environment (ports 3000/3001)
- Volumes are preserved by default (use
-- -vflag to remove) - Build cache is preserved by default (use builder prune to clean)
GitHub Issue Review Fix
Follow the Instructions below to fix issues identified during GitHub issue review. This command takes the JSON output from /github-issue:review and systematically fixes the identified issues based on their severity.
Variables
review_json: $1 (required - JSON string containing review results)
Instructions
1. Parse Review Input
- Parse the provided
review_jsoninput - Validate it matches the expected structure:
success: booleanreview_summary: stringreview_issues: array of issue objectsscreenshots: array of screenshot paths
- If parsing fails, ERROR and stop: "Invalid review JSON provided. Expected JSON matching review output structure."
2. Analyze Issues
- Extract all issues from
review_issuesarray - Group issues by severity:
blocker- Must be fixed immediatelytech_debt- Should be fixed but not blockingskippable- Optional improvements
- If there are no issues, output: "No issues found in review. All functionality matches requirements." and STOP.
3. Prioritize and Plan Fixes
- Create a fix plan prioritizing in this order:
- All
blockerissues first - Then
tech_debtissues - Finally
skippableissues if time permits
- All
- For each issue to fix:
- Read the
issue_descriptionto understand the problem - Read the
issue_resolutionto understand the expected fix - View the
screenshot_pathif provided to see visual evidence of the issue - IMPORTANT: Use the TodoWrite tool to track each issue fix as a separate task
- Read the
4. Fix Issues Systematically
For each issue in priority order:
- Mark the todo as
in_progress - Display to user:
Fixing review issue #{review_issue_number} [{issue_severity}] Description: {issue_description} Resolution: {issue_resolution} - View the screenshot at
screenshot_pathto understand the visual context (if provided) - Locate the relevant code files based on the issue description
- Implement the fix according to the
issue_resolution - If the fix requires changes across multiple files, make all necessary changes
- Mark the todo as
completedwhen done
5. Verify Fixes
- After fixing all
blockerissues, inform the user:- "Fixed {count} blocker issue(s)"
- List each fixed issue with its number and description
- After fixing
tech_debtissues, inform the user:- "Fixed {count} tech debt issue(s)"
- List each fixed issue with its number and description
- If
skippableissues were addressed, inform the user similarly
6. Summary and Next Steps
- Output a summary:
Issue Review Fix Complete Fixed {total} issue(s): - {blocker_count} blocker(s) - {tech_debt_count} tech debt issue(s) - {skippable_count} skippable issue(s) Original Review Summary: {review_summary} Next Steps: - Run /issue:review again to verify all fixes - If successful, proceed with /issue:commit
7. Error Handling
- If unable to fix an issue:
- Document the reason in a comment
- Inform the user which issue could not be fixed and why
- Continue with remaining issues
- If critical errors occur that prevent fixes:
- Report the error clearly
- Suggest manual intervention if needed
Guidelines
- Fix issues incrementally and verify each fix works
- Do not introduce new issues while fixing existing ones
- Maintain code style and patterns consistent with the codebase
- If an issue resolution is unclear, ask the user for clarification before proceeding
- Use the screenshots as visual reference to understand the problem context
- Focus on high-quality fixes rather than quick patches
- Update tests if needed to cover the fixes
Prepare Review Environment
Set up the review environment using Docker Compose to run API and UI on review-specific ports.
Variables
API_PORT: 3501 UI_PORT: 3500
Instructions
1. Check for Running Containers
- Check if review containers are already running:
docker compose -f docker-compose.review.yml ps - If containers are running, skip to step 3
2. Start Review Environment
- Build and start containers:
pnpm docker-compose:up - Wait for services to be ready:
- Check API health: Wait until
curl -f http://localhost:3501/healthsucceeds (retry up to 30 seconds) - Check UI availability: Wait until
curl -f http://localhost:3500succeeds (retry up to 30 seconds)
- Check API health: Wait until
3. Verify Environment
- Confirm API is running:
curl http://localhost:3501/health - Confirm UI is running:
curl http://localhost:3500 - Display container status:
pnpm docker-compose:ps
Notes
- API runs on port 3501 externally (3001 internally in Docker)
- UI runs on port 3500 externally (3000 internally in Docker)
- Services communicate via Docker private network (app-network)
- UI connects to API at http://api:3001 (Docker hostname)
- Both services run with hot-reload enabled via volume mounts
- Use
pnpm docker-compose:logsto view logs - Use
pnpm docker-compose:downto shutdown when done
Update GitHub Issue (GitHub)
Update an existing GitHub issue to match the standard Issue Format. This command fetches the current issue content, incorporates your update request, and brings it to the standards defined in github-issue:create.
Variables
issue_number: $1
Instructions
- IMPORTANT: Read
CLAUDE.mdfor project context, architecture patterns, and conventions. - IMPORTANT: You're updating an existing GitHub issue to improve its structure, add missing details, or incorporate new requirements.
- Fetch the existing issue using
gh issue view $1 --json title,body,labels,state - Parse the existing issue content to understand:
- Current title and description
- What sections already exist
- What details are already documented
- What's missing or incomplete
- Ask the user what updates they want to make to the issue (if not already provided in context)
- Research the codebase to understand existing patterns, architecture, and conventions:
- Explore similar features already implemented
- Understand the file structure and module organization
- Identify existing patterns to follow
- Find relevant test files and patterns
- IMPORTANT: Merge the existing content with your updates and ensure ALL sections from the
Issue Formatare present and complete. - IMPORTANT: Replace every in the
Issue Formatwith concrete values. Add as much detail as needed to implement the work successfully. - Use your reasoning model: THINK HARD about the requirements, design, technical approach, and implementation details.
- Follow existing patterns and conventions in the codebase. Don't reinvent the wheel.
- Design for extensibility and maintainability.
- If you need a new library, mention it in the
Technical Taskssection with installation command. - Don't use decorators. Keep it simple.
- Respect requested files in the
Relevant Filessection. - Start your research by reading the
CLAUDE.mdandREADME.mdfiles. - After creating the updated issue body, use the GitHub CLI to update the issue:
- Use
gh issue edit $1 --body "<updated_body>"or use a temp file:gh issue edit $1 --body-file <temp_file> - Update labels if needed using
gh issue edit $1 --add-label "label1,label2" - Update title if needed using
gh issue edit $1 --title "new title"
- Use
- After updating, report what changed and show the issue URL
Relevant Files
Focus on the following files:
CLAUDE.md- Contains project context, architecture, patterns, and conventions.README.md- Contains the project overview and setup instructions.apps/api/src/**- Contains the backend codebase.apps/ui/src/**- Contains the frontend codebase.apps/api/*.http- Contains HTTP request examples for manual testing.test/**- Contains tests
Ignore all other files in the codebase.
Issue Format
The GitHub issue body should be formatted as follows (same as issue:create):
# <Issue Title>
**Type:** <Feature|Bug|Chore>
**Dependencies:** <list of issue numbers this depends on, or "None">
---
## User Story
**As a** <type of user>
**I want to** <action/goal>
**So that** <benefit/value>
---
## Scope
<describe the scope of work in 2-3 sentences, what will be done>
### What's Included
<bulleted list of specific features/functionality that will be implemented>
- Item 1
- Item 2
- Item 3
### What's NOT Included
<bulleted list of related features that are explicitly out of scope for this issue>
- Item 1
- Item 2
- Item 3
---
## Technical Tasks
<organize tasks by area/phase with clear h3 headers. Be specific and detailed. Include code examples where helpful. Break down into logical sections like "Backend - API Changes", "Frontend - Components", "Database Changes", "Testing", etc.>
### <Task Area 1>
- [ ] Task 1
<optional: include code snippet or technical details>
- [ ] Task 2
- [ ] Task 3
### <Task Area 2>
- [ ] Task 1
- [ ] Task 2
### Update .http File
- [ ] Add relevant HTTP examples to test the changes manually
```http
### Example Request
GET http://localhost:3001/api/...
Acceptance Criteria
<list specific, testable criteria that must be met for the issue to be considered complete. Be precise and measurable.>
<Category 1>
- Criterion 1
- Criterion 2
<Category 2>
- Criterion 1
- Criterion 2
Testing Checklist
<Test Category 1>
-
Test Name
- Step 1
- Step 2
- Expected result
-
Test Name
- Step 1
- Step 2
- Expected result
<Test Category 2>
- Test Name
- Step 1
- Step 2
- Expected result
E2E Test Cases
<Feature Area 1>
-
Test Case Name
- Setup: Initial state/preconditions (e.g., user logged in, specific data exists)
- Steps:
- User action (e.g., Navigate to /dashboard)
- System response (e.g., Dashboard loads with data)
- User action (e.g., Click "Add Meal" button)
- System response (e.g., Modal opens)
- Expected Result: What should happen at the end of the flow
- Assertions: Specific checks to make (e.g., meal appears in list, API called with correct data, UI updates)
-
Test Case Name
- Setup: ...
- Steps: ...
- Expected Result: ...
- Assertions: ...
<Feature Area 2>
- Test Case Name
- Setup, Steps, Expected Result, Assertions...
Error Scenarios
- Error Case Name
- Setup: Preconditions that trigger the error
- Steps: Actions that cause the error
- Expected Result: How the error should be handled
- Assertions: Error messages, UI state, etc.
Definition of Done
- All technical tasks completed
- All acceptance criteria met
- Manual testing completed
- Code follows existing patterns
- No regressions introduced
- .http file updated (if applicable)
- Error handling implemented
- Loading states implemented (if UI changes)
Notes
Design Decisions
Decision 1
- Rationale
Decision 2
- Rationale
Alternative Approaches Considered
Approach 1
- Pros: ...
- Cons: ...
- Decision: ...
User Experience Flow
<if applicable, document the user flow in a step-by-step manner>
1. User action
2. System response
3. User action
4. System response
Future Enhancements (Out of Scope)
- Enhancement 1
- Enhancement 2
- Enhancement 3
<add any additional sections relevant to this issue, such as:>
- Accessibility Considerations
- Performance Considerations
- Security Considerations
- Data Migration Notes
- API Contract Changes
- etc.
Review Points
When reviewing this issue, check:
- <Question 1>
- <Question 2>
- <Question 3> <list key questions/checkpoints for code review>
## Update Strategy
When updating the issue:
1. **Preserve Existing Content**: Keep all valuable information from the original issue
2. **Fill Gaps**: Add missing sections from the standard format
3. **Enhance Details**: Add more specificity to vague sections
4. **Maintain Consistency**: Ensure the updated issue follows the standard format exactly
5. **Update Labels**: Add or update labels to match the issue type and scope
6. **Preserve Checkboxes**: Keep checkbox states (checked/unchecked) from the original
## Report
After updating the GitHub issue, report:
1. The GitHub issue number
2. The GitHub issue URL
3. What sections were added/updated
4. What labels were changed (if any)
5. A summary of the key changes made
Example:
ā
Updated GitHub Issue #123: Add conversation history
š URL: https://github.com/<owner>/<repo>/issues/123
š Changes:
- Added complete User Story section
- Enhanced Technical Tasks with code examples
- Added missing E2E Test Cases section
- Updated scope to clarify included/excluded features
š·ļø Labels: Added "frontend", kept existing "feature", "chat"
Resolve Failed E2E Test
Fix a specific failing E2E test using the provided failure details.
Variables
test_failure_json: $1
Instructions
-
Analyze the E2E Test Failure
- Review the JSON data in the
Test Failure Input, paying attention to:test_name: The name of the failing testtest_path: The path to the test file (you will need this for re-execution)error: The specific error that occurredscreenshots: Any captured screenshots showing the failure state
- Understand what the test is trying to validate from a user interaction perspective
- Review the JSON data in the
-
Understand Test Execution
- Read
.claude/commands/test/test_e2e.mdto understand how E2E tests are executed - Read the test file specified in the
test_pathfield from the JSON - Note the test steps, user story, and success criteria
- Read
-
Reproduce the Failure
- IMPORTANT: Use the
test_pathfrom the JSON to re-execute the specific E2E test - Follow the execution pattern from
.claude/commands/test/test_e2e.md - Observe the browser behavior and confirm you can reproduce the exact failure
- Compare the error you see with the error reported in the JSON
- IMPORTANT: Use the
-
Fix the Issue
- Based on your reproduction, identify the root cause
- Make minimal, targeted changes to resolve only this E2E test failure
- Consider common E2E issues:
- Element selector changes
- Timing issues (elements not ready)
- UI layout changes
- Application logic modifications
- Ensure the fix aligns with the user story and test purpose
-
Validate the Fix
- Re-run the same E2E test step by step using the
test_pathto confirm it now passes - IMPORTANT: The test must complete successfully before considering it resolved
- Do NOT run other tests or the full test suite
- Focus only on fixing this specific E2E test
- Re-run the same E2E test step by step using the
Test Failure Input
$1
Report
Provide a concise summary of:
- Root cause identified (e.g., missing element, timing issue, incorrect selector)
- Specific fix applied
- Confirmation that the E2E test now passes after your fix
Resolve Failed Test
Fix a specific failing test using the provided failure details.
Variables
test_failure_json: $1
Instructions
-
Analyze the Test Failure
- Review the test name, purpose, and error message from the
Test Failure Input - Understand what the test is trying to validate
- Identify the root cause from the error details
- Review the test name, purpose, and error message from the
-
Context Discovery
- Check recent changes:
git diff origin/main --stat --name-only - If a relevant spec exists in
specs/*.md, read it to understand requirements - Focus only on files that could impact this specific test
- Check recent changes:
-
Reproduce the Failure
- IMPORTANT: Use the
execution_commandprovided in the test data - Run it to see the full error output and stack trace
- Confirm you can reproduce the exact failure
- IMPORTANT: Use the
-
Fix the Issue
- Make minimal, targeted changes to resolve only this test failure
- Ensure the fix aligns with the test purpose and any spec requirements
- Do not modify unrelated code or tests
-
Validate the Fix
- Re-run the same
execution_commandto confirm the test now passes - Do NOT run other tests or the full test suite
- Focus only on fixing this specific test
- Re-run the same
Test Failure Input
$1
Report
Provide a concise summary of:
- Root cause identified
- Specific fix applied
- Confirmation that the test now passes
Application Validation Test Suite
Execute comprehensive validation tests for both frontend and backend components, returning results in a standardized JSON format for automated processing.
Purpose
Proactively identify and fix issues in the application before they impact users or developers. By running this comprehensive test suite, you can:
- Detect syntax errors, type mismatches, and import failures
- Identify broken tests or security vulnerabilities
- Verify build processes and dependencies
- Ensure the application is in a healthy state
Variables
TEST_COMMAND_TIMEOUT: 5 minutes
Instructions
- Execute each test in the sequence provided below
- Capture the result (passed/failed) and any error messages
- IMPORTANT: Return ONLY the JSON array with test results
- IMPORTANT: Do not include any additional text, explanations, or markdown formatting
- We'll immediately run JSON.parse() on the output, so make sure it's valid JSON
- If a test passes, omit the error field
- If a test fails, include the error message in the error field
- Execute all tests even if some fail
- Error Handling:
- If a command returns non-zero exit code, mark as failed and immediately stop processing tests
- Capture stderr output for error field
- Timeout commands after
TEST_COMMAND_TIMEOUT - IMPORTANT: If a test fails, stop processing tests and return the results thus far
- Some tests may have dependencies (e.g., server must be stopped for port availability)
- API health check is required
- Test execution order is important - dependencies should be validated first
- All file paths are relative to the project root
- Always run
pwdandcdbefore each test to ensure you're operating in the correct directory for the given test
Test Execution Sequence
Backend Tests
-
TS Syntax Check
- Preparation Command: None
- Command:
pnpm run typechec - test_name: "typecheck"
- test_purpose: "Validates TS syntax by compiling source files to bytecode, catching syntax errors like missing colons, invalid indentation, or malformed statements"
-
TS Quality Check
- Preparation Command: None
- Command:
pnpm run lint - test_name: "linting"`
- test_purpose: "Validates TS code quality, identifies unused imports, style violations, and potential bugs"`
-
All Tests
- Preparation Command: None
- Command:
pnpm run test - test_name: "tests"
- test_purpose: "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
-
All Builds
- Preparation Command: None
- Command:
pnpm run build - test_name: "build"
- test_purpose: "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
Report
- IMPORTANT: Return results exclusively as a JSON array based on the
Output Structuresection below. - Sort the JSON array with failed tests (passed: false) at the top
- Include all tests in the output, both passed and failed
- The execution_command field should contain the exact command that can be run to reproduce the test
- This allows subsequent agents to quickly identify and resolve errors
Output Structure
[
{
"test_name": "string",
"passed": boolean,
"execution_command": "string",
"test_purpose": "string",
"error": "optional string"
},
...
]
Example Output
[
{
"test_name": "all_backend_tests",
"passed": true,
"execution_command": "cd app/server && uv run pytest tests/ -v --tb=short",
"test_purpose": "Validates all backend functionality including file processing, SQL security, LLM integration, and API endpoints"
}
]
Sponsors
Details
- Marketplace
- rmakowiak/my-claude-marketplace
- Source
- plugins/dev-lifecycle
- Category
- Development
- Keywords
- github, issues, testing, workflow, development