github

Indexed Reference Map

• @[SKILL.md#L1-L81] Frontmatter + unified operations/research model
• @[references/INDEX.md#L1-L12] Reading order
• @[references/QUICK_REFERENCE.md#L1-L16] Decision map + permission gates
• @[references/CORE_API.md#L1-L40] Inputs/outputs, research rounds, and auth contract
• @[references/PATTERNS.md#L1-L30] Execution patterns
• @[references/EXAMPLES.md#L1-L17] Sample flows
• @[references/AI_WORKFLOW.md#L1-L9] AI execution sequence
• @[references/RESEARCH_REPORT_TEMPLATE.md#L1-L89] Structured cited report shape

Scope

• In-scope:
  • Read GitHub data: issue/PR/discussion/release/repository metadata.
  • Prepare write payload (comment/create/update) with approval checkpoint.
  • Conduct deep repo research: timeline, architecture, maintenance, adoption, competitor/context scan, and cited report synthesis.
  • Rate-limit aware workflows and evidence-based reporting.
• Out-of-scope:
  • Perform a write action without explicit user approval.
  • Expose token or log secrets.
  • Claim comprehensive coverage when the scope was actually narrow.

Reading Order

1. references/QUICK_REFERENCE.md
2. references/CORE_API.md
3. references/PATTERNS.md
4. references/EXAMPLES.md
5. references/AI_WORKFLOW.md

Coverage Matrix

• Read operations: default enabled
• Write operations: gated
• Auth/token hygiene: mandatory
• Rate-limit handling: mandatory

Trigger Rules

• Positive:
  • Used when users need to look up or manipulate issues/PR/releases on GitHub.
  • Used when users ask for deep research, timeline reconstruction, architecture review, maintenance/adoption analysis, or evidence-backed investigation of a GitHub repository/project.
• Negative: Not used for repo operations outside GitHub scope.
• Escalation: All action write (comment/create/edit/merge/close) must ask for approval before running.

SOP

1. Determine the lane:
   • operations lane (read / prepare-write / write)
   • research lane (deep repo investigation / cited report)
2. Resolve auth path first: use authenticated GitHub API with GITHUB_TOKEN (fallback GH_TOKEN) as the default path for all GitHub work.
3. Run GitHub-native read phase via token-auth GitHub API, collect evidence links/IDs.
4. Only if token-auth is unavailable or fails, classify the failure cause explicitly and then choose the narrowest fallback (gh CLI, then public web if still needed).
5. If operations lane:
   • for read, return the evidence-backed result directly;
   • for prepare-write, draft payload + preview;
   • for write, request approval before executing, then verify artifacts.
6. If research lane:
   • expand from GitHub-native evidence into broader web_search/web_fetch only where it adds value;
   • reconstruct timeline / architecture / maintenance / adoption / risks;
   • synthesize into a structured cited report.
7. Returns summary + artifacts (URL/ID/status), including which auth path was used and whether the output is ops-mode or research-mode.

Error Handling

• Missing token/permission: clearly indicates missing scope (repo, issues:write, ...).
• 403/404: check repo visibility and token role.
• 429/rate-limit: comply with Retry-After, reduce burst.
• Research evidence conflict: cite both claims, lower confidence, and do not compress into a decisive conclusion.
• README/docs fetch blocked but GitHub API works: continue with GitHub-native evidence first and mark missing documentation fetch as a confidence limiter, not as proof the repo is broken.

Output Contract

• Operations lane artifact: github_result includes action, target, status, urls, and auth_path.
• Research lane artifact: a structured cited markdown report with executive summary, timeline, analysis sections, sources, confidence assessment, and auth_path/source-path notes when relevant.
• Validation: has evidence URL/ID for every substantive claim; research claims should distinguish GitHub-native evidence from broader web corroboration.
• Compliance Verdict: PASS when complying with token-first, read-first, and write-gated policy while staying explicit about uncertainty.