comet-ml--opik/.agents/commands/comet/work-on-github-issue.md

Work on GitHub Issue

Command: cursor work-on-github-issue

Overview

Fetch a GitHub issue by link, build full context (title, description, comments, labels, assignees, milestone), and generate an actionable implementation plan.
This workflow will:

• Verify GitHub MCP availability (or instruct how to install it).
• Fetch and parse the issue details.
• If not found, list your assigned open issues.
• Check local git status in the Opik repository and propose a branch if on main.
• Suggest moving the issue to In Progress if it's currently open.
• Validate all operations and provide clear success/failure feedback.

---

Inputs

• GitHub issue link (required): e.g., https://github.com/comet-ml/opik/issues/1234

---

Steps

1. Preflight & Environment Check

• Check GitHub MCP: If unavailable, respond with:

  "This command needs GitHub MCP configured. Set MCP config/env, run make cursor (Cursor) or make claude (Claude CLI), then retry."
  Stop here.

• Check development environment: Verify project dependencies, build tools, and project structure are ready.
• Check local git branch in the Opik repository:
  • If on main, propose a new branch following Opik naming convention:

    {USERNAME}/issue-{ISSUE-NUMBER}-{ISSUE-SUMMARY}
    

    Example:
    • Issue: https://github.com/comet-ml/opik/issues/1234
    • Title: "Add cursor git workflow rule"
    • Branch: andrescrz/issue-1234-add-cursor-git-workflow-rule

---

2. Fetch Issue

• Extract issue number from link.
• Fetch with GitHub MCP: title, body, state, labels, assignees, milestone, comments, created_at, updated_at.
• If fetch fails: Show error message and suggest troubleshooting steps.
• If not found: Search for open issues assigned to current user: is:open assignee:@me (max 10).
• Show list: #1234 — Title (State) and stop if issue not found.

---

3. Build GitHub Context

• Number, Title, State, Labels, Assignees, Milestone
• Description: verbatim if short, otherwise concise summary + key quotes.
• If no description: Note this and suggest adding context for better implementation planning.
• Comments: newest → oldest, [author @ date] summary with important snippets.
• Linked PRs: Include any linked pull requests if available.
• Project context: Include project board information if available.

---

4. Determine Implementation Scope

• Analyze issue scope: Determine which Opik components are affected:
  • Backend only: Java API changes, database migrations, services
  • Frontend only: React components, UI changes, state management
  • SDK only: Python or TypeScript SDK changes
  • Cross-component: Changes affecting multiple layers
  • Infrastructure: Docker, deployment, configuration changes
• Identify affected areas: Map issue requirements to specific Opik modules and files
• Estimate complexity: Consider if changes require database migrations, API versioning, or breaking changes

---

5. Task Plan

• Bugfix: repro steps, root cause hypothesis, affected files, fix approach, risks, tests, verification.
• Feature: user story recap, acceptance criteria, implementation plan, tests, rollout notes.
• Always reference shared and domain guidance in the right place:
  • Global policy: .agents/rules/* (git workflow, security, code style, routing)
  • Backend guidance: .agents/skills/opik-backend/*
  • Frontend guidance: .agents/skills/opik-frontend/*
  • SDK guidance: .agents/skills/python-sdk/* and .agents/skills/typescript-sdk/*
• Component-specific guidance: Use the appropriate rule set based on the implementation scope identified in step 4

---

6. Git & Branch Setup

• Repo: Opik repository (current workspace)
• CRITICAL: Handle working directory state BEFORE branching:
  • If working directory has changes:
    • Option 1: Stash changes: git stash push -m "WIP: before issue-{ISSUE-NUMBER}"
    • Option 2: Ask user what to do with uncommitted changes
  • NEVER commit directly to main (following Opik git workflow)
• If on main, create branch following Opik conventions:

  # Ensure you're on main and pull latest
  git checkout main
  git pull origin main
  
  # Create task-specific branch
  git checkout -b {USERNAME}/issue-{ISSUE-NUMBER}-{ISSUE-SUMMARY}
  

• After branch creation: Apply stashed changes if any: git stash pop
• Verify branch creation: Confirm new branch is active and clean.

---

7. Status Management (Optional)

• Move issue to "In Progress" if currently open:
  • Use GitHub MCP to add appropriate labels (e.g., "in-progress")
  • Verify label addition: Confirm labels were added successfully
  • Handle label failures: Provide error details and retry options

---

8. Implementation Suggestion

• Based on GitHub context and Opik agent guidance, suggest implementing the feature/bugfix:

  • Reference global policy in .agents/rules/* and domain guidance in .agents/skills/*
  • Provide specific implementation steps based on the task plan
  • Include code examples or file paths where appropriate
  • Suggest testing approaches and quality checks
  • Follow Opik architecture patterns (Resources → Services → DAOs → Models for backend)

• Commit Message Format: Follow shared conventions from .agents/rules/git-workflow.mdc.

  First Commit (PR-title source, required):

  [<TICKET-KEY>] [BE/FE/SDK/DOCS] <type>: <description>
  

  where <TICKET-KEY> is OPIK-####, issue-####, or NA.

  Follow-up Commits (preferred):

  <type>(<scope>): <description>
  

  where <type> is one of: feat, fix, refactor, test, docs, chore.

  Last-resort fallback (discouraged):

  Revision N: <description>
  

  Component Types:

  • [BE] - Backend changes (Java, API endpoints, services)
  • [FE] - Frontend changes (React, TypeScript, UI components)
  • [SDK] - SDK changes (Python, TypeScript SDKs)
  • [DOCS] - Documentation updates, README changes, comments, swagger/OpenAPI documentation

  Examples:

  [OPIK-1234] [BE] feat: add create trace endpoint
  [issue-1234] [FE] fix: guard project custom metrics empty state
  [OPIK-1234] [DOCS] docs: update API documentation
  [NA] [SDK] chore: align SDK lint configuration
  feat(experiments): add run-level metadata capture
  

9. User Confirmation

• Ask for user approval before proceeding with implementation:
  • Present the implementation plan clearly
  • Ask: "Would you like me to proceed with implementing this feature/fix now?"
  • Wait for explicit user confirmation before making any code changes
  • If user declines: Stop here and provide guidance for manual implementation
  • If user confirms: Proceed to implementation phase

10. Implementation Phase (Optional)

• Only proceed if user confirmed in previous step
• Execute the implementation plan:
  • Create/modify necessary files following Opik patterns
  • Apply code changes according to the plan
  • Run quality checks and tests
  • Commit changes with proper issue number prefix
• If user declined: Provide manual implementation guidance and stop

---

11. Completion Summary & Validation

• Confirm all steps completed:
  • ✅ GitHub MCP available and working
  • ✅ Issue fetched and analyzed successfully
  • ✅ Labels updated (if applicable)
  • ✅ Feature branch created and active following Opik naming convention
  • ✅ Development environment ready
  • ✅ Implementation suggestion provided
• Next steps: Provide clear guidance on what to do next
• Error summary: If any steps failed, provide troubleshooting guidance

---

Error Handling

GitHub MCP Failures

• Connection issues: Check network and authentication
• Permission errors: Verify user access to the repository
• Rate limiting: Wait and retry
• API errors: Check GitHub API status and retry

Git Operation Failures

• Branch creation fails: Check for conflicts, verify permissions
• Pull fails: Resolve merge conflicts, check remote status
• Working directory dirty: NEVER commit to main - stash changes first
• CRITICAL SAFETY: Always verify current branch before any commits
• Uncommitted changes: Stash before branching, pop after branch creation

Label Management Failures

• Invalid label: Check available labels in the repository
• Permission denied: Verify user can modify issue labels
• Label doesn't exist: Create the label or use existing ones

---

Success Criteria

The command is successful when:

1. ✅ GitHub issue is successfully fetched and analyzed
2. ✅ Feature branch is created and active following Opik naming convention
3. ✅ Issue labels are updated (if requested)
4. ✅ Implementation suggestion provided based on context and Opik rules
5. ✅ User confirmation received (proceed or decline)
6. ✅ Implementation executed (if confirmed) or manual guidance provided (if declined)
7. ✅ All operations complete without errors
8. ✅ Clear next steps are provided to the user

---

Troubleshooting

Common Issues

• GitHub MCP not available: Configure MCP and run make cursor (Cursor) or make claude (Claude CLI)
• Git branch conflicts: Resolve conflicts before proceeding
• Permission errors: Check user access and repository settings
• Network issues: Verify connectivity to GitHub services

Fallback Options

• If issue fetch fails: List user's assigned open issues
• If branch creation fails: Provide manual git commands
• If label update fails: Continue with development setup

---

End Command