github-issue-reporter

name	github-issue-reporter
description	A methodology for researching, drafting, and posting high-quality technical reports to GitHub repositories.

GitHub Issue Reporting Methodology

This skill provides a disciplined workflow for moving from a successful local fix or discovery to a formal GitHub issue. It prioritizes research and "legwork" to ensure reports are welcome and actionable by maintainers.

Core Principle: High-Signal, Zero-Noise

The objective is to provide developers with the exact technical context they need to replicate your success or understand your failure, while explicitly demonstrating that you have avoided duplication.

---

Phased Workflow

Phase 1: Pre-Reporting Research (Diligence)

Before drafting, you must confirm that the report is necessary and correctly formatted.

1. Search for Duplicates: Use targeted searches in the repository for specific error strings, symbols, or environment keywords (e.g., "Termux", "Bionic", "Python 3.13").
2. Verify Contribution Norms: Read CONTRIBUTING.md or doc/sphinxdoc/contribute.rst.
   • Self-Correction: If maintainers express wariness of AI noise, the report should be framed as a peer-technical document from a verified tool environment.
3. Identity Check: Confirm your current tool capabilities.
   • Check gh auth status to see who you are.
   • Verify if the GitHub MCP tool has write permissions; if not, use the gh CLI via run_shell_command.

Phase 2: Content Consolidation

A report must contain searchable "signal."

1. Extract Sample Errors: Include the exact, raw traceback or build failure. This allows other users to find your issue via search engines.
2. Map the Environment: List OS versions, compiler versions (Clang/GCC), and exact dependency versions.
3. The "Recipe" (Success) or "Repro" (Failure): Provide clear, numbered steps to replicate the successful build or the specific crash.

Phase 3: Drafting the Issue

Structure the issue for maximum readability.

1. Title: Prefix with context tags (e.g., [Android/Termux], [Build Fix]).
2. Summary: One-paragraph explanation of the accomplishment or bug.
3. The Evidence: Use Markdown code blocks for all logs and commands.
4. Proposed Fix: Suggest specific code changes (e.g., "Add logic to wscript to handle Android linkage").
5. Diligence Statement: Explicitly state: "I have reviewed the contribution guidelines and recent issue history and have not found related ones yet."

Phase 4: Execution (Posting)

1. Tool Selection: Prefer gh issue create with --body-file for large reports to avoid shell-escaping issues.
2. Verification: Immediately read back the created issue URL to confirm success.

---

Summary Command Sequence

# 1. Research
gh issue list --search "keyword" 
# 2. Identity
gh auth status
# 3. Post
gh issue create --repo org/repo --title "..." --body-file issue.md