chore: add create-plan-from-issue CC command (#4531)

add a claude code command to analyze a jira issue and create a plan from it. This should be used in plan mode! Signed-off-by: Brady Pratt <bpratt@redhat.com>
2026-01-26 06:21:37 +03:00 · 2025-11-17 10:44:34 -06:00
parent 1863c05213
commit 92eddf2dbc
3 changed files with 525 additions and 0 deletions
--- a/.claude/commands/create-plan-from-issue.md
+++ b/.claude/commands/create-plan-from-issue.md
@@ -0,0 +1,440 @@
+---
+allowed-tools: Bash(jira:*), Bash(.claude/scripts/download-jira-attachments.sh:*), mcp__playwright__browser_navigate, mcp__playwright__browser_snapshot, mcp__playwright__browser_click, mcp__playwright__browser_type, mcp__playwright__browser_fill_form, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_wait_for, mcp__playwright__browser_press_key, mcp__playwright__browser_console_messages, Read, Glob, Grep, TodoWrite
+argument-hint: <issue-key>
+description: Systematically plan a bug or feature based on a JIRA issue
+---
+
+# Create Plan from Issue
+
+Systematically analyze a JIRA issue and create an actionable implementation plan. This command uses a **modular phase-based approach** that branches based on issue type (UI vs Backend).
+
+## Issue Key
+
+The JIRA issue to plan: `$ARGUMENTS`
+
+---
+
+## Phase 1: Discovery (All Issues)
+
+### Step 1: Fetch Issue Details
+
+Retrieve the full issue information from JIRA:
+
+```bash
+jira issue view $ARGUMENTS
+```
+
+**Extract key information:**
+- Issue type (Bug, Story, Task, etc.)
+- Summary and description
+- Component (ui, api, data, etc.)
+- Priority
+- Labels
+- Comments with additional context
+
+### Step 2: Download Attachments
+
+Download any attachments from the issue:
+
+```bash
+.claude/scripts/download-jira-attachments.sh $ARGUMENTS
+```
+
+This script will:
+- Check if the issue has attachments
+- Download them to `.claude/attachments/$ARGUMENTS/`
+- Display file types to help identify their purpose
+
+**Common attachment types:**
+- Screenshots/Images: Visual bugs or mockups
+- Architecture diagrams: Design documentation
+- Log files: Error traces or debugging information
+- Test files: Reproduction cases or examples
+
+### Step 3: Classify the Issue
+
+Analyze the issue to determine if it's **UI** or **Backend**, considering both description and attachments:
+
+**UI Issue Indicators:**
+- Component: `ui` or `web`
+- Keywords: rendering, display, UI, interface, button, form, modal, table, layout, styling, visual, PatternFly, React, Angular
+- Issue describes visual or interaction problems
+- Has screenshot/mockup attachments
+
+**Backend Issue Indicators:**
+- Component: `api`, `data`, `auth`, `endpoints`, `workers`, `buildman`, `storage`
+- Keywords: API, endpoint, database, authentication, background job, storage, worker, migration, ORM, SQL
+- Has log files or stack traces attached
+- Describes data processing, API behavior, or system operations
+
+**Decision Point:** Based on classification, proceed to either **Phase 2-UI** or **Phase 2-Backend**.
+
+---
+
+## Phase 2: Type-Specific Preparation
+
+### Phase 2-UI: UI Issue Preparation
+
+**If the issue is UI-related**, prepare the UI development environment:
+
+1. **Set Playwright Context:**
+   - App URL: `http://localhost:9000`
+   - Test credentials: `user1` / `password`
+   - Be prepared to navigate UI, take screenshots, and check console
+
+2. **Identify UI Scope:**
+   - Which pages/routes are affected?
+   - Which PatternFly components are involved?
+   - Is this an Angular port or new feature?
+
+**Proceed to Phase 3: UI Workflows**
+
+### Phase 2-Backend: Backend Issue Preparation
+
+**If the issue is backend-related**, prepare the backend investigation:
+
+1. **Identify Affected Subsystems:**
+   - **API Endpoints** (`endpoints/`): REST API routes
+   - **Data Layer** (`data/`): Database models and queries
+   - **Workers** (`workers/`): Background job processors
+   - **Authentication** (`auth/`): Auth mechanisms
+   - **Storage** (`storage/`): Storage backend operations
+   - **Build System** (`buildman/`): Container build orchestration
+
+2. **Prepare for Analysis:**
+   - Review attached log files for stack traces
+   - Identify error patterns or exceptions
+   - Note database tables or models mentioned
+   - Check if workers or background jobs are involved
+
+3. **Locate Entry Points:**
+   - API endpoint paths (e.g., `/api/v1/repository/`)
+   - Worker class names
+   - Database model classes
+   - Configuration keys
+
+**Proceed to Phase 3: Backend Workflows**
+
+---
+
+## Phase 3: Deep Planning (Type-Specific Workflows)
+
+### Phase 3-UI: UI Workflows
+
+Choose the appropriate UI workflow based on issue type:
+
+#### 3A-UI: UI Bug Planning
+
+**When to use:** Issue type is Bug and classified as UI
+
+1. **Understand the Bug:**
+   - What is the expected behavior?
+   - What is the actual behavior?
+   - Steps to reproduce (if provided)
+   - Affected UI components or pages
+   - Review attached screenshots to visualize the issue
+
+2. **Create Reproduction Plan with Playwright:**
+   - Navigate to `http://localhost:9000`
+   - Login with `user1` / `password` if needed
+   - Navigate to the affected page/component
+   - Perform actions to reproduce the bug
+   - Take screenshots and snapshots to document the issue
+   - Check browser console for errors using `browser_console_messages`
+
+3. **Locate Relevant Code:**
+   - Search for related components in `web/src/`
+   - Identify the route or component files
+   - Look for related test files in `web/cypress/e2e/`
+   - Check for API hooks in `web/src/hooks/`
+
+4. **Create TodoList:**
+   ```
+   - Reproduce bug with Playwright
+   - Locate source code for affected component
+   - Identify root cause (state management, props, rendering, etc.)
+   - Implement fix
+   - Add or update Cypress tests
+   - Verify fix with Playwright
+   ```
+
+**Proceed to Phase 4**
+
+#### 3B-UI: Angular to React Port
+
+**When to use:** Issue mentions Angular, port, migrate, or "new UI"
+
+1. **Confirm Angular Port:**
+   - Look for references to Angular UI in description/comments
+   - Search for keywords: "port", "migrate", "current UI", "new UI", "Angular"
+   - Locate the Angular component for reference (legacy codebase)
+   - Review attached mockups or design screenshots if available
+
+2. **Research PatternFly Components:**
+   - Identify which PatternFly components are needed
+   - Review existing usage in codebase for patterns
+   - Check PatternFly documentation for component props and patterns
+
+3. **Locate Similar React Components:**
+   - Search for similar patterns in `web/src/routes/`
+   - Identify reusable components in `web/src/components/`
+   - Check existing tests for similar features in `web/cypress/e2e/`
+   - Review API integration patterns in `web/src/hooks/`
+
+4. **Create TodoList:**
+   ```
+   - Research Angular implementation (locate source code)
+   - Identify PatternFly components needed
+   - Design React component structure (pages, components, hooks)
+   - Implement React components following frontend patterns
+   - Add routing with TanStack Router (if new page)
+   - Implement API integration with useSuspenseQuery
+   - Write Cypress e2e tests
+   - Verify with Playwright manual testing
+   ```
+
+**Proceed to Phase 4**
+
+#### 3C-UI: New UI Feature
+
+**When to use:** Issue is Story/Task for new UI functionality (not an Angular port)
+
+1. **Design the Feature:**
+   - Review attached mockups or design documents
+   - What UI components are needed?
+   - What user interactions are required?
+   - What API endpoints are needed (if any)?
+   - What state management is required?
+   - Accessibility considerations?
+
+2. **Locate Integration Points:**
+   - Where does this fit in navigation/routing?
+   - What existing components can be reused?
+   - What API calls are needed?
+   - What data transformations are required?
+
+3. **Create TodoList:**
+   ```
+   - Identify PatternFly components needed
+   - Design component architecture (pages, components, hooks)
+   - Implement React components with TypeScript
+   - Add routing/navigation with TanStack Router
+   - Implement API integration with useSuspenseQuery
+   - Add proper error boundaries and loading states
+   - Write Cypress e2e tests
+   - Manual testing with Playwright
+   ```
+
+**Proceed to Phase 4**
+
+---
+
+### Phase 3-Backend: Backend Workflows
+
+Choose the appropriate backend workflow based on issue type:
+
+#### 3A-Backend: Backend Bug Planning
+
+**When to use:** Issue type is Bug and classified as Backend
+
+1. **Analyze the Error:**
+   - Review attached log files or stack traces
+   - Identify error type (exception, timeout, data corruption, etc.)
+   - Note affected endpoints, models, or workers
+   - Check error frequency and conditions
+
+2. **Locate Affected Code:**
+
+   **For API bugs:**
+   - Search for endpoint definitions in `endpoints/` (e.g., `endpoints/api/repository.py`)
+   - Find blueprint registration in `endpoints/api/__init__.py`
+   - Check authentication decorators and permissions
+
+   **For data layer bugs:**
+   - Locate database models in `data/database.py`
+   - Find business logic in `data/model/`
+   - Check query performance and indexes
+   - Review caching layer in `data/cache/`
+
+   **For worker bugs:**
+   - Find worker class in `workers/` (e.g., `workers/repositorygcworker.py`)
+   - Check queue operations and job handling
+   - Review worker-specific configuration
+   - Trace worker initialization in `workers/worker.py`
+
+3. **Reproduce the Issue:**
+   - Create minimal reproduction case
+   - Check test coverage for affected code
+   - Identify missing validation or edge cases
+   - Review related configuration in `config.py`
+
+4. **Create TodoList:**
+   ```
+   - Analyze error logs and stack traces
+   - Locate affected code (endpoint/model/worker)
+   - Create reproduction test case
+   - Identify root cause (SQL query, auth logic, race condition, etc.)
+   - Implement fix with proper error handling
+   - Add unit tests for the fix
+   - Add integration tests if multiple components involved
+   - Test manually with local development environment
+   - Verify no performance regression
+   ```
+
+**Proceed to Phase 4**
+
+#### 3B-Backend: Backend Feature Planning
+
+**When to use:** Issue is Story/Task for new backend functionality
+
+1. **Design API/Data Changes:**
+
+   **For new endpoints:**
+   - Define API route and HTTP methods
+   - Design request/response schemas
+   - Plan authentication and authorization
+   - Consider rate limiting and pagination
+
+   **For data model changes:**
+   - Design database schema changes
+   - Plan migration strategy (Alembic)
+   - Consider backward compatibility
+   - Plan indexes for query performance
+
+   **For new workers:**
+   - Define worker responsibilities
+   - Design job queue structure
+   - Plan failure handling and retries
+   - Consider worker scaling
+
+2. **Locate Integration Points:**
+   - Which existing endpoints interact with this feature?
+   - What database tables/models are involved?
+   - What storage operations are needed?
+   - What authentication mechanisms apply?
+   - What configuration is needed?
+   - Does the config-tool schema need updates for validation?
+
+3. **Plan Database Migrations:**
+   - Identify schema changes needed
+   - Plan migration steps (add columns, tables, indexes)
+   - Consider data backfill requirements
+   - Plan rollback strategy
+
+4. **Create TodoList:**
+   ```
+   - Design API endpoints and request/response schemas
+   - Design database schema changes
+   - Update config-tool schema if new configuration options needed
+   - Create Alembic migration for schema changes
+   - Implement data models in data/database.py
+   - Implement business logic in data/model/
+   - Implement API endpoints in endpoints/
+   - Add authentication and authorization checks
+   - Implement worker if background processing needed
+   - Add caching layer if needed
+   - Write unit tests for models and business logic
+   - Write API integration tests
+   - Write worker tests if applicable
+   - Test migration on clean database
+   - Test config-tool validation with new configuration
+   - Test manually with local development environment
+   ```
+
+**Proceed to Phase 4**
+
+---
+
+## Phase 4: Final Steps (All Issues)
+
+### Step 4: Execute Research Phase
+
+Based on your TodoList, gather context:
+
+**For UI issues:**
+- Read existing component implementations
+- Check similar test patterns in Cypress
+- Review routing structure
+- Check existing PatternFly component usage
+
+**For backend issues:**
+- Read existing endpoint implementations
+- Check database schema in `data/database.py`
+- Review existing tests for patterns
+- Check related configuration in `config.py`
+- Review worker base class if applicable
+
+### Step 5: Refine TodoList
+
+After research, update your TodoList with:
+- Specific file paths discovered during research
+- Additional tasks uncovered
+- Proper task ordering
+- Dependencies between tasks
+
+Ensure each task has both `content` and `activeForm`.
+
+---
+
+## Key Locations
+
+### Frontend (UI Issues)
+- **React UI source**: `web/src/`
+- **Routes**: `web/src/routes/`
+- **Reusable components**: `web/src/components/`
+- **API hooks**: `web/src/hooks/`
+- **Cypress tests**: `web/cypress/e2e/`
+- **App URL**: `http://localhost:9000`
+- **Test credentials**: `user1` / `password`
+
+### Backend (API/Data Issues)
+- **API endpoints**: `endpoints/` (versioned in `v1/`, `v2/`, etc.)
+- **Data models**: `data/database.py`
+- **Business logic**: `data/model/`
+- **Workers**: `workers/`
+- **Authentication**: `auth/`
+- **Storage**: `storage/`
+- **Build system**: `buildman/`
+- **Configuration**: `config.py`
+- **Config-tool schema**: `config-tool/` (validates configuration files)
+- **Migrations**: `data/migrations/versions/`
+
+---
+
+## Tips
+
+### General
+- Always create a TodoList to track planning and implementation
+- Update TodoList as you discover new information
+- Mark tasks in_progress and completed promptly
+- Include both unit tests and integration/e2e tests
+
+### UI-Specific
+- Use Playwright to verify UI bugs and test fixes
+- Check existing similar features for patterns
+- Consider accessibility (ARIA labels, keyboard nav)
+- For Angular ports, find the Angular component first
+
+### Backend-Specific
+- Review log files carefully for stack traces
+- Check database indexes for query performance
+- Consider migration rollback strategy
+- Test with both PostgreSQL and MySQL if applicable
+- Review worker queue behavior for background jobs
+- Check configuration in both code and deployment configs
+
+---
+
+## Example Usage
+
+```
+/create-plan-from-issue PROJQUAY-1234
+```
+
+This will:
+1. Fetch PROJQUAY-1234 from JIRA
+2. Download any attachments
+3. Classify as UI or Backend issue
+4. Follow the appropriate workflow branch
+5. Create a systematic implementation plan
+6. Set up a TodoList to track progress
--- a/.claude/scripts/download-jira-attachments.sh
+++ b/.claude/scripts/download-jira-attachments.sh
@@ -0,0 +1,73 @@
+#!/bin/bash
+# Download attachments from a JIRA issue
+# Usage: download-jira-attachments.sh <ISSUE-KEY>
+
+set -e
+
+ISSUE_KEY="$1"
+
+if [ -z "$ISSUE_KEY" ]; then
+  echo "Usage: $0 <ISSUE-KEY>"
+  exit 1
+fi
+
+# Check if jira CLI is installed
+if ! command -v jira &> /dev/null; then
+  echo "Error: jira CLI is not installed or not in PATH"
+  echo "Install from: https://github.com/ankitpokhrel/jira-cli"
+  exit 1
+fi
+
+# Get raw issue JSON
+TEMP_JSON="/tmp/issue-${ISSUE_KEY}.json"
+jira issue view "$ISSUE_KEY" --raw > "$TEMP_JSON"
+
+# Check if attachments exist
+ATTACHMENT_COUNT=$(jq -r '.fields.attachment | length' "$TEMP_JSON")
+
+if [ "$ATTACHMENT_COUNT" -gt 0 ]; then
+  # Create directory for attachments
+  ATTACH_DIR=".claude/attachments/${ISSUE_KEY}"
+  mkdir -p "$ATTACH_DIR"
+
+  echo "Found $ATTACHMENT_COUNT attachment(s) for $ISSUE_KEY"
+
+  # Get bearer token from environment or jira config
+  if [ -n "$JIRA_API_TOKEN" ]; then
+    JIRA_TOKEN="$JIRA_API_TOKEN"
+  else
+    JIRA_TOKEN=$(grep -A2 'auth_type: bearer' ~/.config/.jira/.config.yml | grep -v 'auth_type' | grep -v '^--$' | awk '{print $2}')
+  fi
+
+  if [ -z "$JIRA_TOKEN" ]; then
+    echo "Error: Could not find JIRA bearer token. Set JIRA_API_TOKEN env var or configure in ~/.config/.jira/.config.yml"
+    exit 1
+  fi
+
+  # Extract and download each attachment
+  jq -r '.fields.attachment[] | "\(.filename)|\(.content)"' "$TEMP_JSON" | while IFS='|' read -r filename url; do
+    echo "  Downloading: $filename"
+
+    curl -s -H "Authorization: Bearer $JIRA_TOKEN" \
+      -o "$ATTACH_DIR/$filename" \
+      "$url"
+  done
+
+  echo "Downloaded to: $ATTACH_DIR/"
+
+  # List downloaded files with their types
+  echo ""
+  echo "Attachments:"
+  for file in "$ATTACH_DIR"/*; do
+    if [ -f "$file" ]; then
+      basename "$file"
+      file -b "$file" | head -c 80
+      echo ""
+    fi
+  done
+else
+  echo "No attachments found for $ISSUE_KEY"
+fi
+
+# Clean up temp file
+rm -f "$TEMP_JSON"
--- a/.mcp.json
+++ b/.mcp.json
@@ -0,0 +1,12 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": [
+        "@playwright/mcp@latest"
+      ],
+      "env": {}
+    }
+  }
+}