github-issue-refine

GitHub Issue Refinement Workflow

This workflow guides you through refining an existing GitHub issue to improve its clarity, technical implementation details, and alignment with project rules.

Trigger

Use this workflow when the user asks to "refine an issue," "improve a ticket," "groom a task," or "update the issue description."

---

Phase 1: Research & Validation

1. Fetch Issue Details:
   • Retrieve the issue details: gh issue view $ISSUE_NUMBER
2. Analyze Current State:
   • Identify the core goal and success criteria.
   • Assess if the current implementation plan is specific enough.
   • Check for missing contexts (UI constraints, etc.).
3. Cross-Reference docs/rules:
   • Verify that the proposed solution aligns with:
     • next.md: Are Server Actions and Client/Server component rules followed?
     • ui.md & icons.md: Is the component and icon usage correct?
     • testing.md: Is there a clear strategy for Vitest?
     • figma.md: Explicitly read this file to ensure Figma implementations adhere to the parsing rules, cleanup requirements, and master component references.

---

Phase 2: Technical Refinement

1. Improve Implementation Steps:
   • Refine generic steps into specific actions tied to concrete files and functions.
   • Ensure every step has a "Reason" explaining WHY it's necessary.
2. Add Additional Context:
   • Examples: Provide snippets of expected data structures or code patterns.
   • Diagrams: Use Mermaid syntax for complex state transitions or data flows.
   • Documentation: Reference specific documentation paths (e.g., from nextjs_docs) relevant to the implementation.
3. Deep File Investigation:
   • Use list_code_definition_names or search_files to find related logic that might be affected but wasn't mentioned in the original issue.
4. Visual Context & Attachments:
   • Current State: If possible, use browser automation tools to take a screenshot of the current state of the application (the "before" state). Ensure you clean up your browser session afterward by closing the opened pages using mcp_chrome-devtools_list_pages and mcp_chrome-devtools_close_page.
   • Figma Design: If a Figma layout link is provided in the issue, use the Figma MCP tool to download an image of the Figma frame to visually demonstrate what the design should be (the "after" state).
   • Issue Update & Image Hosting: Because gh CLI cannot directly upload images to issues, create a new branch named assets/issue-$ISSUE_NUMBER. Push the downloaded images to .github/assets/issue-$ISSUE_NUMBER/ on that branch. Then, update the issue description with standard Markdown image links using the GitHub blob URL with ?raw=true (e.g., ![alt](https://github.com/OWNER/REPO/blob/assets/issue-$ISSUE_NUMBER/.github/assets/issue-$ISSUE_NUMBER/image.png?raw=true)). This ensures the images render correctly even in private repositories.