study-github-repo

Clone a GitHub repository locally, study it systematically across 14 dimensions, and produce a comprehensive report in the configured output language (defaulting to English).

Prerequisite: gh CLI installed and authenticated. Verify with gh auth status.

Procedure

Step 1 — Parse Input

Extract {owner} and {repo} from the GitHub URL. Accept any of these formats:

• https://github.com/{owner}/{repo}
• github.com/{owner}/{repo}
• {owner}/{repo}

Step 2 — Gather Repo Metadata

Fetch metadata via gh api before cloning (lightweight, fast):

# Repo overview
gh api 'repos/{owner}/{repo}' --jq '{
  description, stargazers_count, forks_count,
  language, license: .license.spdx_id,
  topics, created_at, updated_at, open_issues_count,
  default_branch, archived, size
}'

# Language breakdown
gh api 'repos/{owner}/{repo}/languages'

# Recent releases (last 5)
gh api 'repos/{owner}/{repo}/releases?per_page=5' --jq '.[].tag_name'

# Contributors (top 10)
gh api 'repos/{owner}/{repo}/contributors?per_page=10' --jq '.[] | {login, contributions}'

# Recent commits (last 30)
gh api 'repos/{owner}/{repo}/commits?per_page=30' --jq '.[] | {date: .commit.author.date, message: .commit.message | split("\n")[0]}'

# Recent issues (last 10, all states)
gh api 'repos/{owner}/{repo}/issues?state=all&per_page=10' --jq '.[] | {number, title, state, labels: [.labels[].name]}'

# Recent PRs (last 10, all states)
gh api 'repos/{owner}/{repo}/pulls?state=all&per_page=10' --jq '.[] | {number, title, state, merged_at}'

Step 3 — Clone Locally

mkdir -p .tmp/github_study
gh repo clone {owner}/{repo} .tmp/github_study/{owner}_{repo} -- --depth=1 \
  -c url.https://github.com/[email protected]:

Use --depth=1 for a shallow clone (faster, smaller). The -c url...insteadOf flag forces HTTPS to avoid SSH key issues. Full history is not needed — commit metadata is already fetched via API.

Step 4 — Phase 1: Orientation

Build a rough mental map of the repo. Read these in order:

1. README — Extract the problem statement, claimed solution, and target audience
2. Directory tree — Run find .tmp/github_study/{owner}_{repo} -not -path '*/.git/*' -not -path '*/node_modules/*' -not -path '*/__pycache__/*' -not -path '*/dist/*' -not -path '*/build/*' -not -path '*/.venv/*' | head -200 to see the structure (or use tree -L 3 -I '...' if available)
3. Config files — Read package.json / pyproject.toml / Cargo.toml / go.mod / Makefile / docker-compose.yml (whichever exist) to understand dependencies, scripts, and build setup
4. Docs directory — If docs/ or similar exists, scan for architecture docs, guides, or design documents
5. Examples — If examples/ exists, read a representative example to understand typical usage

Step 5 — Phase 2: Trace Execution Flow

Follow one real execution path from input to output:

1. Find entry points — Look for main.py, index.ts, server.js, app.ts, src/index.*, cmd/, bin/, CLI entry files, API routers
2. Trace the critical path — Starting from the primary entry point, follow the code through orchestration → business logic → infrastructure layer. Read every file along this path.
3. Identify the data flow — Map: Input → Processing → Output. What transformations happen? What side effects occur?

There is no artificial file cap. Use engineering judgment to determine when you have enough understanding to explain how the repo delivers on its README promise. For large repos, focus on the core module rather than peripheral utilities.

Step 6 — Phase 3: Deep Analysis

Using your understanding from Phases 1-2, now systematically investigate each dimension:

1. Core Abstractions — Find interfaces, base classes, schemas, protocols, type definitions. What primitives is the system built on?
2. State Management — Where does state live? Who owns it? How is it updated? Is there persistence/checkpointing?
3. Decision Logic — Find planners, routers, evaluators, scoring systems, retry policies, fallback mechanisms
4. Feedback Loops — Look for logging, telemetry, metrics, evaluation pipelines, retry/correction loops
5. Tests — Read test files. What types exist (unit, integration, e2e)? What do they reveal about intended behavior and edge cases?
6. DX signals — Evaluate setup instructions, documentation quality, naming conventions, type safety, scripts
7. Hidden Architectural Flaws — Identify exactly 5 architectural flaws hidden in plain sight. Pinpoint the exact file paths and line numbers, and evaluate their impact on future maintainability.

Use grep_search / ripgrep to search for patterns across the codebase without reading full files. Examples:

• grep -r "class.*Base\|class.*Abstract\|interface " --include="*.py" --include="*.ts"
• grep -r "log\.\|logger\.\|console\.log\|logging\." --include="*.py" --include="*.ts" -l
• grep -r "test\|describe\|it(" --include="*test*" --include="*spec*" -l

Step 7 — Write Report

Check data/user_preferences.md for the Preferred Output Language configuration, and write the report in that language (defaulting to English if not configured).

📄 Read assets/output_template.md for the full report template.

Write the report to reports/GitHub/{owner}_{repo}.md. Every section must contain substantive content — no empty sections. If a dimension is not applicable (e.g., "State Management" for a pure utility library), explain why it's not relevant rather than leaving it blank.

The four executive summary questions must be answered:

1. What problem does this repo solve?
2. How is it designed?
3. Can I trust/use/extend it?
4. What can I learn from it?

For private/internal repos with sparse community metrics (0 stars, no releases), note this factually in Repo Health: "This appears to be a private/internal repository; community health metrics are not applicable."

Step 8 — Cleanup

rm -rf .tmp/github_study/{owner}_{repo}

Confirm to the user: "✅ Report saved to reports/GitHub/{owner}_{repo}.md. Clone cleaned up."

Error Handling

• `gh` not authenticated: Stop with "⚠️ GitHub CLI is not authenticated. Run 'gh auth login' first."
• Repo not found / no access: Stop with "⚠️ Repository {owner}/{repo} not found or you don't have access."
• Clone fails: Report the error and suggest the user check network/permissions.