kb-github-scanning

## GitHub Scanning ## Search Query Patterns by Intent ### Issues Each intent, with its query pattern and scope. | Intent | Query Pattern | Scope | |--------|--------------|-------| | Assigned to you | `is:open assignee:USERNAME` | All repos | | You were @mentioned | `is:open mentions:USERNAME` | All repos | | Authored by you | `is:open author:USERNAME` | All repos | | Specific repo | `repo:owner/repo is:open` | Single repo | | By keyword | `{keyword} is:open` | All repos | | Org-wide | `org:ORGNAME is:open` | Org repos | | Closed (for recap) | `is:closed author:USERNAME` | All repos | ### Pull Requests Each intent, with its query pattern and scope. | Intent | Query Pattern | Scope | |--------|--------------|-------| | Awaiting your review | `review-requested:USERNAME state:open` | All repos | | Your open PRs | `author:USERNAME state:open` | All repos | | Assigned to you | `assignee:USERNAME state:open` | All repos | | You reviewed, check for updates | `reviewed-by:USERNAME state:open` | All repos | | Specific PR | Fetch directly with owner, repo, number | Single repo | | Org-wide | `org:ORGNAME state:open` | Org repos | ### Discussions Each intent, with its action. | Intent | Action | |--------|--------| | You're mentioned | Search with `mentions:USERNAME` | | You're participating | Search discussions you've commented on | | High activity | Filter for 10+ comments in last 24h | | Linked to your issues | Scan description/comments for issue references | ### Releases - Use `github_list_releases` per repo - check for recent, draft, and pre-releases. - Cross-reference merged PRs against release notes to identify unreleased work. - Compare issue milestones against release schedules to flag upcoming deadline items. ### Security - Dependabot alerts: critical and high severity across monitored repos. - Security advisories affecting dependencies. - Pending dependency update PRs from `dependabot[bot]` or `renovate[bot]`. ### CI/CD - Fetch recent workflow runs - identify failing workflows, long jobs, and flaky tests. - For failing workflows: note repo, workflow name, branch, failure reason, and link to run. - Cross-reference user's open PRs against CI results. --- ## Date Range Handling Convert natural language to GitHub query qualifiers: | User Says | GitHub Qualifier | |-----------|-----------------| | "last week" | `created:>YYYY-MM-DD` (7 days ago) | | "this month" | `created:>YYYY-MM-01` | | "today" | `closed:YYYY-MM-DD` | | "this week" | `closed:>YYYY-MM-DD` (7 days ago) | | "between X and Y" | `created:X..Y` | | Not specified | Use `search.default_window` from preferences (default: `updated:>YYYY-MM-DD` 30 days) - mention this assumption | | "for current month" (a11y tracker) | `milestone:"{Month} {Year}"` | --- ## Scope Narrowing Add qualifiers to narrow by scope when the user specifies one: | Scope | Qualifier | |-------|-----------| | Single repo | `repo:owner/name` | | All org repos | `org:orgname` | | All repos by user | `user:username` | | Everything (default) | No qualifier - searches all accessible repos | --- ## Preferences File Integration Read `.github/agents/preferences.md` and apply these filters before and after searching: 1. **`repos.discovery`** - determines the default search scope (all / starred / owned / configured / workspace). 2. **`repos.include`** - always include these repos even in restricted modes. 3. **`repos.exclude`** - skip these repos in all searches. 4. **`repos.overrides`** - per-repo settings: - `track.issues: false` -> skip issue searches for this repo - `track.pull_requests: false` -> skip PR searches for this repo - `track.discussions: false` -> skip discussions for this repo - `track.releases: false` -> skip release checks for this repo - `track.security: false` -> skip security alerts for this repo - `track.ci: false` -> skip CI status for this repo - `labels.include` / `labels.exclude` -> filter results by label - `paths` -> only trigger for changes touching these file paths (for PRs/CI) - `assignees` -> filter to specific assignees (empty = all) 5. **`search.default_window`** - default time range if the user doesn't specify one. 6. **`briefing.sections`** - which sections to include in the daily briefing. 7. **`accessibility_tracking`** - config for the a11y tracker (repos, labels, channels). --- ## Cross-Repo Intelligence When results arrive from different repos, look for and surface these patterns: | Pattern | Action | |---------|--------| | Cross-repo references | When issue A contains `owner/repo#N`, fetch and surface item N | | Shared label patterns | Group items in different repos tagged `P0` together in triage | | Related PRs in different repos | Flag: _"This issue depends on PR #N in repo-B which is still open"_ | | Merged PR not yet released | Note: _"Your PR #N is merged but not in any release yet"_ | | Issue with merged fix PR | Flag: _"This may be resolved - PR #N that closes it was merged on {date}"_ | | Branch naming patterns | Group PRs in different repos using the same branch naming convention | --- ## Parallel Stream Collection Model For agents that collect from multiple data streams, run independent streams simultaneously. Don't serialize operations with no dependencies. ### Example: Daily Briefing - 3 Parallel Batches **Batch 1 - fully independent, run simultaneously:** - Issues (assigned, mentioned, authored) - Pull requests (review-requested, authored) - Releases & deployments - Accessibility updates **Batch 2 - run after Batch 1 (CI needs PR list from Batch 1):** - GitHub Discussions - CI/CD health (cross-references PR list) - Security alerts **Batch 3 - can overlap with Batch 2:** - Project board status - Recently closed/merged work ### Example: Analytics - 2 Parallel Batches **Batch 1 - collection (all independent):** - Closed/merged PRs in period - Opened issues in period - CI workflow runs in period - Security alerts in period **Batch 2 - analysis (depends on Batch 1 data):** - Health score computation - Velocity metrics calculation - Bottleneck detection ### Announcement Template for Parallel Work ```text Running {N} searches in parallel... ({scope}) Batch 1 complete - {X} items found Running {N} additional searches... Batch 2 complete - {Y} items found Scoring and prioritizing... Done - {Z} items need action, {W} to monitor ``` --- ## Auto-Recovery for Empty Results If a search returns 0 results: 1. Automatically broaden: remove date filter, expand scope to `all`, or remove label filters. 2. Tell the user exactly what changed: _"No results in last 7 days - broadened to last 30 days and found 3 items."_ 3. Never return 0 results without trying at least one broader query first. Recovery cascade: 1. First try: Remove date qualifier 2. Second try: Expand scope (add org: or remove repo: qualifier) 3. Third try: Remove label filters 4. Report 0 results only if all three attempts return nothing --- ## Pagination - Paginate large result sets in batches of 10. - Ask before loading more: _"Showing 10 of 47. Load more?"_ - Never silently truncate results - always disclose the total count. --- ## Result Deduplication When the same item appears in multiple searches (e.g., an issue you're both assigned to AND mentioned in): - Show it once, with all context combined. - In the Signal column, combine signals: _"Assigned, @mentioned"_. - In priority calculations, apply the highest-scoring signal, not additive. --- ## Rate Limiting - If rate-limited (403/429), tell the user the reset time in one sentence. - Do not retry the same query - wait if reset is <60 seconds; otherwise report and move on. - For multi-stream collection, skip rate-limited streams and complete them in a follow-up.