github-codebase-briefing

This skill performs a "deep read" of a repository. It avoids superficial listings by first understanding the project's architecture and then evaluating open items against that context.

• Tooling: The agent must have access to the gh CLI.
• Auth: The user must be authenticated (gh auth status).

Before looking at tasks, understand the environment. Run these commands in sequence:

1. Metadata: gh repo view <owner/repo> --json name,description,stargazerCount,forkCount
2. Structure: gh api repos/<owner/repo>/contents/
3. Identity: Read the project manifest (e.g., package.json, go.mod, pyproject.toml) and README.md.
4. Entry Point: Read the primary entry file (e.g., index.ts, main.go) to identify the Public API surface.

Fetch current items and recent changes:

1. Issues: gh issue list --repo <owner/repo> --state open --json number,title,body,author,createdAt,updatedAt,labels,comments
2. PRs: gh pr list --repo <owner/repo> --state open --json number,title,body,author,createdAt,updatedAt,labels,additions,deletions,changedFiles,headRefName
3. 24h Delta: gh issue list --state closed --since 24h and gh pr list --state merged --since 24h.

For every issue and PR, do not just summarize the text. Perform a logic check:

• Issues: Use gh api repos/<owner/repo>/contents/<path> to inspect the code mentioned in the report.
• PRs: Use gh pr diff <number> to review actual implementation. Evaluate if the code follows the patterns found in Step 1.
• Flags:
  • 🚨 SECURITY: Scan for credentials, auth bypass, or injection keywords.
  • 🤝 EXTERNAL: Prioritize PRs from non-maintainers.
  • ✅ READY: Verify mergeability with gh pr view <number> --json mergeable,statusCheckRollup.

Group items into high-level insights:

• Bug Clusters: Identify if 3+ issues share a root cause in a specific module.
• Hot Modules: Flag files that appear in multiple open items.
• Client Patterns: Group issues by consumer (e.g., "VS Code users are reporting X").

Snapshot: {N} Issues ({+X} since yesterday) | {M} PRs ({+Y} since yesterday)

1. [Priority] #{Num}: {One-line reason}
2. [Priority] #{Num}: {One-line reason}

• Context: Plain-English explanation of the "why" and "where" in the codebase.
• Key Evidence: > {Blockquote of critical user text}
• Resolution Path: {Quick fix/Design decision/Blocked}

• Impact: Summary of files changed and architectural fit.
• Quality Note: Honest assessment of implementation and CI status.

• Hot Modules: {list/of/files}
• Release Cadence: Last release was {days} ago.