ask-github 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 61e0c09960d2b923d6209cc171870ccc4517b594fb4764ae7c5ffb611fe09e78
-  data.tar.gz: 456ca8833ac0e354809e09d2cf1b84ea7b1354a26589aa74533981ebe63b5c4b
+  metadata.gz: f64d61d784bb31f0281d5aabedd9abe2937b335b25a85dee0d8246dbe7e6745b
+  data.tar.gz: d81bfb900b6d5c3f9cdfd7b5b6f6553ab9b5a93ecacbef219d5fda968dd3eb29
 SHA512:
-  metadata.gz: db1fd215ba903feca7ba4c09fded2c10d7c306b54906224ee3a373f3ef3f0f85708535845d0a7abd46ed09aef82f9c4dfb1943f2b116682a1c085b056ef3dc49
-  data.tar.gz: 591f2708a9538d55114a9c6add830b7409f030ab8313dd1a36c68b1cae38900e50c4dd7285a3e84725ccf8c33a38c348f90ed0ec73400bd470f3cc71c607c76f
+  metadata.gz: 9a8b8fe7c51f63e6a78e92f302010e10d3e7da2ad990b2f6b967d0624be0ab224c448a042dd8925459777710c370bbe787a7cd1596153623998907427c2a032a
+  data.tar.gz: 29b96dd81509ba2323990ebfd8742e580058840ac29e41e089cdcc918611932ae6338b3ef954b96b14f8dd6ad795d4f0faebc6d4d6cf2bcdfad42616a6f37c06

data/lib/ask/github/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module GitHub
-    VERSION = "0.1.1"
+    VERSION = "0.1.2"
   end
 end

data/lib/ask/skills/github.use_github/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: github.use_github
+description: How to navigate the GitHub API with Octokit — discover endpoints, handle auth, pagination, and errors
+---
+
+Use this skill when you need to interact with GitHub — reading issues, pull
+requests, repository contents, search, or managing projects using code tools.
+
+## Step 1: Get the Client
+
+```ruby
+client = Ask::GitHub.client
+```
+
+This returns an authenticated Octokit client. It expects a valid GitHub personal
+access token resolved via `Ask::Auth.resolve(:github_token)`.
+
+If you get an auth error, read `Ask::GitHub::Context::AUTH_HOW` for token setup.
+
+## Step 2: Explore the Context
+
+The gem ships with structured context you should reference:
+
+```ruby
+Ask::GitHub::Context::DOCS_URL    # GitHub REST API docs
+Ask::GitHub::Context::GEM_DOCS    # Octokit Ruby docs
+Ask::GitHub::Context::QUICK_START # Copy-paste examples
+Ask::GitHub::Context::GEM_NAME    # "octokit"
+```
+
+The `QUICK_START` constant has basic usage examples for common operations
+(issues, pull requests, contents, search).
+
+## Step 3: Discover Available Methods
+
+Rather than assuming which methods exist, use code tools to explore the client:
+
+```ruby
+# List all public methods (filter out Object basics)
+Code.new.call(code: "
+  client = Ask::GitHub.client
+  puts (client.methods - Object.methods).sort.join(\"\\n\")
+")
+```
+
+Octokit methods follow REST API patterns:
+- `client.issues("owner/repo")` — list issues
+- `client.pull_requests("owner/repo")` — list PRs
+- `client.contents("owner/repo", path: "README.md")` — read file
+- `client.search_issues("query")` — search across repos
+- `client.create_issue("owner/repo", "Title", "body")` — create issue
+
+For method specifics, read the Octokit source:
+```ruby
+Grep.new.call(pattern: "def issues", path: "$GEM_PATH/octokit-*/lib")
+```
+
+## Step 4: Authentication Errors
+
+Auth failures are converted to `Ask::Auth::InvalidCredential`. For detailed
+error guidance, use:
+
+```ruby
+Ask::GitHub::Errors.for("Octokit::NotFound")
+Ask::GitHub::Errors.status_code_description(404)
+Ask::GitHub::Errors::RATE_LIMIT
+```
+
+Common scenarios:
+- **401/403**: Token invalid or missing scopes → check token at GitHub settings
+- **404**: Resource doesn't exist or is private → verify owner/repo and access
+- **429**: Rate limited → wait and retry (5,000 req/hr with token)
+
+## Step 5: Pagination
+
+Octokit auto-paginates by default (`auto_paginate: true`, `per_page: 100`).
+For very large result sets, you can iterate manually using the response's
+`rels` (relations) links.
+
+## Step 6: Fallback Strategy
+
+If Octokit doesn't have a convenience method for what you need:
+1. Check `Ask::GitHub::Context::DOCS_URL` for the REST API endpoint
+2. Use `client.get("/endpoint")` for custom REST requests
+3. Use the GraphQL API via `client.post("/graphql", { query: "..." })` for complex queries
+4. For search, use `client.search_issues("...")` which supports GitHub's query syntax

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-github
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Kaka Ruto
@@ -137,8 +137,7 @@ files:
 - lib/ask/github/context.rb
 - lib/ask/github/error_guide.rb
 - lib/ask/github/version.rb
-- lib/ask/skills/github.issue_triage/SKILL.md
-- lib/ask/skills/github.pr_review/SKILL.md
+- lib/ask/skills/github.use_github/SKILL.md
 homepage: https://github.com/ask-rb/ask-github
 licenses:
 - MIT

data/lib/ask/skills/github.issue_triage/SKILL.md

@@ -1,144 +0,0 @@
----
-name: github.issue_triage
-description: Systematic approach for triaging GitHub issues — reproduce, classify, check duplicates, label, prioritize
----
-
-Use this skill when asked to handle a new GitHub issue, classify bug reports,
-or organize a queue of unprocessed issues.
-
-## Step 1: Reproduce the Issue
-
-If the issue describes a bug, the first step is reproduction:
-
-```ruby
-client = Ask::GitHub.client
-issue = client.issue("owner/repo", ISSUE_NUMBER)
-puts issue.title
-puts issue.body
-```
-
-Extract from the issue body:
-1. **Steps to reproduce** — are they complete and accurate?
-2. **Expected behavior** — what should happen
-3. **Actual behavior** — what happens instead
-4. **Environment** — OS, version, browser, dependencies
-5. **Error messages** — exact text, stack traces, screenshots
-
-If steps are missing, ask for them. Never triage a bug that can't be reproduced.
-
-## Step 2: Classify the Issue
-
-Determine what type of issue it is:
-
-**Bug** — Unexpected behavior, crash, error
-- Severity: Critical (production outage) / Major (broken feature) / Minor (cosmetic)
-
-**Feature Request** — New capability or enhancement
-- Scope: Small (add param) / Medium (new endpoint) / Large (new subsystem)
-
-**Question** — How-to, clarification,usage help
-- Answerable from docs? Redirect to docs first.
-
-**Task** — Chore, tech debt, CI fix, dependency update
-- Effort: Small / Medium / Large
-
-## Step 3: Check for Duplicates
-
-Search for similar existing issues:
-
-```ruby
-# Search for keywords from the issue title
-similar = client.search_issues("keyword repo:owner/repo is:issue")
-similar.items.each { |i| puts "##{i.number}: #{i.title} (#{i.state})" }
-```
-
-Check both open AND closed issues — a previously closed issue might have been
-reopened in a new form.
-
-Mark as duplicate if:
-- Same root cause (different symptom? still a duplicate)
-- Same feature request (even different proposed API shape)
-- References the same error message or stack trace
-
-If duplicate found, add a comment:
-```ruby
-client.add_comment("owner/repo", ISSUE_NUMBER, "Duplicate of #123. Closing.")
-client.update_issue("owner/repo", ISSUE_NUMBER, state: "closed")
-```
-
-## Step 4: Add Labels
-
-Apply appropriate labels based on classification:
-
-```ruby
-labels = []
-labels << "bug" if bug
-labels << "enhancement" if feature
-labels << "question" if question
-labels << priority_label(severity) # "critical", "high", "medium", "low"
-labels << "needs-reproduction" if steps_to_repro_missing
-labels << "good-first-issue" if simple and well-scoped
-
-client.add_labels_to_an_issue("owner/repo", ISSUE_NUMBER, labels)
-```
-
-If the issue needs more information to be actionable:
-```ruby
-labels << "needs-info"
-client.update_issue("owner/repo", ISSUE_NUMBER, labels: labels)
-```
-
-## Step 5: Prioritize
-
-Priority matrix based on:
-
-```
-              | Critical | Major | Minor
-User Impact   | High     | High  | Low
-Workaround    | None     | Some  | Has
-Frequency     | Always   | Often | Rare
-Scope         | All      | Some  | Edge
-```
-
-**Critical** — Fix immediately, patch release: P0
-- Production outage, data loss, security vulnerability
-
-**High** — Fix this sprint: P1
-- Feature broken for most users, no workaround
-
-**Medium** — Schedule next sprint: P2
-- Feature broken for some users, has workaround
-
-**Low** — Backlog, community PR welcome: P3
-- Enhancement, nice-to-have, rare edge case
-
-## Step 6: Add Context
-
-If the issue references code, trace through the codebase to add helpful context:
-
-```ruby
-# Search for related code
-search_paths = ["app/", "lib/"]  # adjust for repo structure
-Glob.new.call(pattern: "app/**/*.rb") # check the repo structure
-```
-
-Add a triage comment summarizing:
-1. Brief reproduction status
-2. Classification
-3. Priority with reasoning
-4. Suggested approach (if bug: fix direction; if feature: implementation sketch)
-5. @mention relevant maintainer if needed
-
-```ruby
-client.add_comment("owner/repo", ISSUE_NUMBER, "Triage summary: ...")
-```
-
-## Failure Mode Guide
-
-| Situation | Action |
-|-----------|--------|
-| Can't reproduce | Label `needs-info`, ask for more details |
-| Incomplete report | Request specific missing information |
-| Security issue | Do NOT file publicly — create private advisory |
-| Controversial feature request | Label `needs-discussion`, ping maintainers |
-| Issue spam | Label `invalid`, close immediately |

data/lib/ask/skills/github.pr_review/SKILL.md

@@ -1,143 +0,0 @@
----
-name: github.pr_review
-description: Systematic methodology for reviewing GitHub pull requests
----
-
-Use this skill when asked to review a GitHub pull request. Follow the steps
-in order — each provides context needed for the next.
-
-## Step 1: Understand the Change
-
-First, get the big picture:
-
-```ruby
-client = Ask::GitHub.client
-files = client.pull_request_files("owner/repo", PR_NUMBER)
-```
-
-Review the file list:
-- **Total files changed** — is this a reasonable scope?
-- **File types** — config, app code, tests, migrations, docs?
-- **Lines added vs deleted** — is it mostly new code or refactoring?
-
-Then get the full diff for each file:
-
-```ruby
-files.each do |f|
-  puts "#{f.filename}: +#{f.additions}/-#{f.deletions}"
-end
-```
-
-For large PRs, focus on the core logic files and skip generated/config changes
-unless they're the purpose of the PR.
-
-## Step 2: Read the PR Description and Related Issues
-
-```ruby
-pr = client.pull_request("owner/repo", PR_NUMBER)
-puts pr.title
-puts pr.body
-```
-
-Check for:
-- **Motivation** — is the WHY clear?
-- **Related issues** — does `pr.body` reference #123 or "Closes #123"?
-- **Testing strategy** — does it mention how it was tested?
-- **Deployment considerations** — migrations, config changes, feature flags?
-
-If issues are referenced, review them for context:
-
-```ruby
-client.issue("owner/repo", ISSUE_NUMBER)
-```
-
-## Step 3: Review Tests First
-
-Look at the test files changed:
-
-```ruby
-test_files = files.select { |f| f.filename.match?(/_test\.rb|_spec\.rb$/) }
-test_files.each do |f|
-  # Read the test content
-  client.contents("owner/repo", path: f.filename)
-end
-```
-
-Check:
-- **Coverage** — does every new method/logic path have a test?
-- **Edge cases** — empty state, error handling, boundary conditions?
-- **Test quality** — are they testing the behavior or the implementation?
-- **Setup/teardown** — are shared states properly isolated?
-
-## Step 4: Review Core Logic
-
-Review the main implementation files:
-
-```ruby
-app_files = files.reject { |f| f.filename.match?(/_test\.rb|_spec\.rb$/) }
-app_files.each do |f|
-  content = client.contents("owner/repo", path: f.filename)
-  # Review the content
-end
-```
-
-What to look for:
-- **Security**: SQL injection (raw SQL, string interpolation), mass assignment,
-  authentication bypass, exposed credentials
-- **Correctness**: Off-by-one errors, nil checks, edge case handling
-- **Performance**: N+1 queries, missing eager loading, unnecessary allocations
-- **Pattern consistency**: Follows existing code conventions?
-- **Error handling**: What happens when external services fail?
-
-## Step 5: Check for Common Anti-Patterns
-
-Scan for these common issues:
-
-1. **Hard-coded values** — should be config or environment variables
-2. **TODO/FIXME/HACK comments** — left-behind development artifacts
-3. **Commented-out code** — should be removed before merge
-4. **Overly complex methods** — more than 10-15 lines suggests refactoring needed
-5. **Duplicate logic** — extract to shared method or concern
-6. **Missing validations** — user input not validated before database insert
-
-## Step 6: Assess Test Results and CI
-
-If available, check CI status:
-
-```ruby
-# Check commit status
-client.commit_status("owner/repo", pr.head.sha)
-```
-
-If tests are failing or CI is red, DO NOT approve the PR until that's addressed.
-
-## Step 7: Write the Review
-
-Structure your review feedback:
-
-1. **Summary** — 2-3 sentences about what the PR does
-2. **Positive feedback** — what's done well (specific examples)
-3. **Required changes** — bugs, security issues, breaking tests
-4. **Suggestions** — improvements that are optional (performance, style)
-5. **Questions** — anything unclear that the author should clarify
-
-Use GitHub's review API:
-
-```ruby
-client.create_pull_request_review(
-  "owner/repo",
-  PR_NUMBER,
-  body: "Summary...",
-  event: "COMMENT" # or "APPROVE" or "REQUEST_CHANGES"
-)
-```
-
-## Failure Mode Guide
-
-| Situation | Action |
-|-----------|--------|
-| No test coverage | Request tests before approval |
-| Security vulnerability | Block with clear explanation, suggest fix |
-| PR has merge conflicts | Note that it needs rebase before review |
-| Large PR (>500 lines) | Focus on core logic, note scoping concerns |
-| Missing description | Ask for context before detailed review |