Roo-Code/.roo/rules-issue-writer/5_github_cli_usage.xml

<github_cli_usage>
  <overview>
    The GitHub CLI (gh) provides comprehensive tools for interacting with GitHub.
    Here's when and how to use each command in the issue creation workflow.
    
    Note: This mode prioritizes using repository-specific issue templates over
    hardcoded ones. Templates are detected and used dynamically from the repository.
  </overview>

  <pre_creation_commands>
    <command name="gh issue list">
      <when_to_use>
        ALWAYS use this FIRST before creating any issue to check for duplicates.
        Search for keywords from the user's problem description.
      </when_to_use>
      <example>
        <execute_command>
        <command>gh issue list --repo $REPO_FULL_NAME --search "dark theme button visibility" --state all --limit 20</command>
        </execute_command>
      </example>
      <options>
        --search: Search query for issue titles and bodies
        --state: all, open, or closed
        --label: Filter by specific labels
        --limit: Number of results to show
        --json: Get structured JSON output
      </options>
    </command>

    <command name="gh search issues">
      <when_to_use>
        Use for more advanced searches across issues and pull requests.
        Supports GitHub's advanced search syntax.
      </when_to_use>
      <example>
        <execute_command>
        <command>gh search issues --repo $REPO_FULL_NAME "dark theme button" --limit 10</command>
        </execute_command>
      </example>
    </command>

    <command name="gh issue view">
      <when_to_use>
        Use when you find a potentially related issue and need full details.
        Check if the user's issue is already reported or related.
      </when_to_use>
      <example>
        <execute_command>
        <command>gh issue view 123 --repo $REPO_FULL_NAME --comments</command>
        </execute_command>
      </example>
      <options>
        --comments: Include issue comments
        --json: Get structured data
        --web: Open in browser
      </options>
    </command>
  </pre_creation_commands>

  <template_detection_commands>
    <command name="list_files">
      <when_to_use>
        Use to check for issue templates in the repository before creating issues.
        This is not a gh command but necessary for template detection.
      </when_to_use>
      <examples>
        Check for templates in standard location:
        <list_files>
        <path>.github/ISSUE_TEMPLATE</path>
        <recursive>true</recursive>
        </list_files>
        
        Check for single template file:
        <list_files>
        <path>.github</path>
        <recursive>false</recursive>
        </list_files>
      </examples>
    </command>

    <command name="read_file">
      <when_to_use>
        Read template files to parse their structure and content.
        Used after detecting template files.
      </when_to_use>
      <examples>
        Read YAML template:
        <read_file>
        <path>.github/ISSUE_TEMPLATE/bug_report.yml</path>
        </read_file>
        
        Read Markdown template:
        <read_file>
        <path>.github/ISSUE_TEMPLATE/feature_request.md</path>
        </read_file>
      </examples>
    </command>
  </template_detection_commands>

  <contributor_only_commands>
    <note>
      These commands should ONLY be used if the user has indicated they want to
      contribute the implementation. Skip these for problem reporters.
    </note>
    
    <command name="gh repo view">
      <when_to_use>
        Get repository information and recent activity.
      </when_to_use>
      <example>
        <execute_command>
        <command>gh repo view $REPO_FULL_NAME --json defaultBranchRef,description,updatedAt</command>
        </execute_command>
      </example>
    </command>

    <command name="gh search prs">
      <when_to_use>
        Check recent PRs that might be related to the issue.
        Look for PRs that modified relevant code.
      </when_to_use>
      <example>
        <execute_command>
        <command>gh search prs --repo $REPO_FULL_NAME "dark theme" --limit 10 --state all</command>
        </execute_command>
      </example>
    </command>

    <command name="git log">
      <when_to_use>
        For bug reports from contributors, check recent commits that might have introduced the issue.
        Use after cloning the repository locally.
      </when_to_use>
      <example>
        <execute_command>
        <command>git log --oneline --grep="theme" -n 20</command>
        </execute_command>
      </example>
    </command>
  </contributor_only_commands>

  <issue_creation_command>
    <command name="gh issue create">
      <when_to_use>
        Only use after:
        1. Confirming no duplicates exist
        2. Checking for and using repository templates
        3. Gathering all required information
        4. Determining if user is contributing or just reporting
        5. Getting user confirmation
      </when_to_use>
      <bug_report_example>
        <execute_command>
        <command>gh issue create --repo $REPO_FULL_NAME --title "[Descriptive title of the bug]" --body-file /tmp/issue_body.md --label "bug"</command>
        </execute_command>
      </bug_report_example>
      <feature_request_example>
        <execute_command>
        <command>gh issue create --repo $REPO_FULL_NAME --title "[Problem-focused title]" --body-file /tmp/issue_body.md --label "proposal" --label "enhancement"</command>
        </execute_command>
      </feature_request_example>
      <options>
        --title: Issue title (required)
        --body: Issue body text
        --body-file: Read body from file
        --label: Add labels (can use multiple times)
        --assignee: Assign to user
        --project: Add to project
        --web: Open in browser to create
      </options>
    </command>
  </issue_creation_command>

  <post_creation_commands>
    <command name="gh issue comment">
      <when_to_use>
        ONLY use if user wants to add additional information after creation.
      </when_to_use>
      <example>
        <execute_command>
        <command>gh issue comment 456 --repo $REPO_FULL_NAME --body "Additional context or comments."</command>
        </execute_command>
      </example>
    </command>

    <command name="gh issue edit">
      <when_to_use>
        Use if user realizes they need to update the issue after creation.
        Can update title, body, or labels.
      </when_to_use>
      <example>
        <execute_command>
        <command>gh issue edit 456 --repo $REPO_FULL_NAME --title "[Updated title]" --body "[Updated body]"</command>
        </execute_command>
      </example>
    </command>
  </post_creation_commands>

  <workflow_integration>
    <step_1_integration>
      After user selects issue type, immediately search for related issues:
      1. Use `gh issue list --search` with keywords from their description
      2. Show any similar issues found
      3. Ask if they want to continue or comment on existing issue
    </step_1_integration>

    <step_2_integration>
      Template detection (NEW):
      1. Use list_files to check .github/ISSUE_TEMPLATE/ directory
      2. Read any template files found (YAML or Markdown)
      3. Parse template structure and metadata
      4. If multiple templates, let user choose
      5. If no templates, prepare to create generic one
    </step_2_integration>

    <step_3_integration>
      Decision point for contribution:
      1. Ask user if they want to contribute implementation
      2. If yes: Use contributor commands for codebase investigation
      3. If no: Skip directly to creating a problem-focused issue
      4. This saves time for problem reporters
    </step_3_integration>

    <step_4_integration>
      During codebase exploration (CONTRIBUTORS ONLY):
      1. Clone repo locally if needed: `gh repo clone $REPO_FULL_NAME`
      2. Use `git log` to find recent changes to affected files
      3. Use `gh search prs` for related pull requests
      4. Include findings in the technical context section
    </step_4_integration>

    <step_5_integration>
      When creating the issue:
      1. Use repository template if found, or generic template if not
      2. Fill template with gathered information
      3. Format differently based on contributor vs problem reporter
      4. Save formatted body to temporary file
      5. Use `gh issue create` with appropriate labels from template
      6. Capture the returned issue URL
      7. Show user the created issue URL
    </step_5_integration>
  </workflow_integration>

  <best_practices>
    <practice name="file_handling">
      When creating issues with long bodies:
      1. Save to temporary file: `cat > /tmp/issue_body.md << 'EOF'`
      2. Use --body-file flag with gh issue create
      3. Clean up after: `rm /tmp/issue_body.md`
    </practice>

    <practice name="search_efficiency">
      Use specific search terms:
      - Include error messages in quotes
      - Use label filters when appropriate
      - Limit results to avoid overwhelming output
    </practice>

    <practice name="json_output">
      Use --json flag for structured data when needed:
      - Easier to parse programmatically
      - Consistent format across commands
      - Example: `gh issue list --json number,title,state`
    </practice>
  </best_practices>

  <error_handling>
    <duplicate_found>
      If search finds exact duplicate:
      - Show the existing issue to user using `gh issue view`
      - Ask if they want to add a comment instead
      - Use `gh issue comment` if they agree
    </duplicate_found>

    <creation_failed>
      If `gh issue create` fails:
      - Check error message (auth, permissions, network)
      - Ensure gh is authenticated: `gh auth status`
      - Save the drafted issue content for user
      - Suggest using --web flag to create in browser
    </creation_failed>

    <authentication>
      Ensure GitHub CLI is authenticated:
      - Check status: `gh auth status`
      - Login if needed: `gh auth login`
      - Select appropriate scopes for issue creation
    </authentication>
  </error_handling>

  <command_reference>
    <issues>
      gh issue create    - Create new issue
      gh issue list      - List and search issues
      gh issue view      - View issue details
      gh issue comment   - Add comment to issue
      gh issue edit      - Edit existing issue
      gh issue close     - Close an issue
      gh issue reopen    - Reopen closed issue
    </issues>

    <search>
      gh search issues   - Search issues and PRs
      gh search prs      - Search pull requests
      gh search repos    - Search repositories
    </search>

    <repository>
      gh repo view       - View repository info
      gh repo clone      - Clone repository
    </repository>
  </command_reference>

  <template_handling_reference>
    <yaml_template_parsing>
      When parsing YAML templates:
      - Extract 'name' for template identification
      - Get 'labels' array for automatic labeling
      - Parse 'body' array for form elements
      - Convert form elements to markdown sections
      - Preserve 'required' field indicators
    </yaml_template_parsing>
    
    <markdown_template_parsing>
      When parsing Markdown templates:
      - Check for YAML front matter
      - Extract metadata (labels, assignees)
      - Identify section headers
      - Replace placeholder text
      - Maintain formatting structure
    </markdown_template_parsing>
    
    <template_usage_flow>
      1. Detect templates with list_files
      2. Read templates with read_file
      3. Parse structure and metadata
      4. Let user choose if multiple exist
      5. Fill template with information
      6. Create issue with template content
    </template_usage_flow>
  </template_handling_reference>
</github_cli_usage>