PR Summary to Git Notes - Development Documentation Skill

This skill teaches you to understand and work with the PR Summary GitHub Action project, which captures comprehensive PR activity (comments, reviews, checks, commits) and embeds it into git repositories as git notes.

Purpose

When users reference this CLAUDE.md file, help them:

1. Understand the architecture and design decisions

2. Extend or modify the PR summary functionality

3. Debug issues with the GitHub Action

4. Add new features following established patterns

5. Maintain code quality and test coverage

Key Architecture Principles

1. Storage: Git Notes Strategy

The project uses `refs/notes/commits` instead of:

**Trade-offs to explain:**

2. Module Structure (Separation of Concerns)

```

models.py → Pure data models, no business logic

github_client.py → GitHub API interaction, pagination, retry logic

collector.py → API responses → typed models

formatter.py → PRActivity → markdown (pure function)

git_notes.py → Git command encapsulation

utils.py → Environment variables, validation

main.py → Orchestration

```

**Dependency Graph:**

```

main.py

├── github_client.py (no dependencies)

├── collector.py

│ ├── github_client.py

│ └── models.py

├── formatter.py

│ └── models.py

├── git_notes.py (no dependencies)

└── utils.py (no dependencies)

```

3. Critical Implementation Details

**GitHub Token Scopes:**

**Error Handling:**

**Type Safety:**

Instructions for AI Agents

When Users Ask to Extend Functionality

1. **Identify the affected modules** using the architecture diagram

2. **Follow the data flow:**

- API change → `github_client.py`

- New data field → `models.py` first, then `collector.py`, then `formatter.py`

- Output format → `formatter.py` only

3. **Maintain separation of concerns** - don't mix API logic with formatting

4. **Add type annotations** to all new functions

5. **Write tests** in corresponding test file with 80%+ coverage target

When Users Report Bugs

1. **Check the "Bugs Fixed During Development" section** for similar issues

2. **Common pitfalls:**

- GitHub token scope issues (use `/repos/` endpoint)

- Git error message variations (use substring matching)

- Mock data in tests (be explicit with headers/responses)

3. **Verify with real GitHub Actions token**, not personal access token

When Users Want to Add Data Fields

1. Add to `models.py` (pure data, type annotated)

2. Update `collector.py` to extract from GitHub API

3. Update `formatter.py` to display in markdown

4. Add tests in `test_models.py`, `test_collector.py`, `test_formatter.py`

5. Update README.md example output

When Users Want to Change Output Format

1. Modify methods in `formatter.py` only

2. Add configuration options via environment variables in `utils.py`

3. Update tests in `test_formatter.py`

4. Keep it pure: `PRActivity → markdown string` with no side effects

When Users Need to Debug

**Test locally:**

```bash

cd ~/projects/pr-summary

python3 -m venv .venv

.venv/bin/pip install -r requirements.txt

export GITHUB_TOKEN="your_token"

export PR_NUMBER="123"

export GITHUB_REPOSITORY="owner/repo"

export MERGE_COMMIT_SHA="abc123..."

.venv/bin/python -m src.main

git notes --ref=refs/notes/commits show abc123...

```

**Run tests:**

```bash

.venv/bin/pip install -r requirements-dev.txt

.venv/bin/pytest -v

.venv/bin/pytest --cov=src --cov-report=html

```

GitHub API Endpoints Used

```python

PR Data

GET /repos/{owner}/{repo}/pulls/{pr_number}

GET /repos/{owner}/{repo}/pulls/{pr_number}/commits

GET /repos/{owner}/{repo}/pulls/{pr_number}/files

GET /repos/{owner}/{repo}/pulls/{pr_number}/comments

GET /repos/{owner}/{repo}/issues/{pr_number}/comments

GET /repos/{owner}/{repo}/pulls/{pr_number}/reviews

Check Runs

GET /repos/{owner}/{repo}/commits/{sha}/check-runs

GET /repos/{owner}/{repo}/commits/{sha}/status

Repository (auth validation)

GET /repos/{owner}/{repo}

```

**Rate limits:** 5000 req/hour authenticated, warn when < 10 remaining

Environment Variables Reference

**Required:**

**Optional:**

Testing Patterns to Follow

1. **Mock GitHub API responses** in `conftest.py` fixtures

2. **Use temporary git repos** for git notes testing

3. **Centralize test data** in shared fixtures

4. **Test error paths** (401, 403, 429, 500 responses)

5. **Verify retry logic** with mock side effects

6. **Target 80%+ coverage** (current: 80%, 100 tests)

Constraints

Future Enhancement Patterns

When users want to add:

Example Usage Scenarios

**Scenario 1: User wants to add PR labels to the summary**

1. Check if `models.py` PRMetadata has `labels` field (it does)

2. Verify `collector.py` extracts it (check `_extract_metadata`)

3. Update `formatter.py` to display labels in metadata section

4. Add test in `test_formatter.py` with mock PR data including labels

**Scenario 2: User reports authentication error**

1. Ask if using `GITHUB_TOKEN` or personal access token

2. Check which endpoint is failing

3. Verify endpoint doesn't require scopes beyond `contents:write`, `pull-requests:read`, `checks:read`

4. Suggest using `/repos/{owner}/{repo}` pattern instead of `/user`

**Scenario 3: User wants JSON output instead of markdown**

1. Create new `format_as_json()` function in `formatter.py`

2. Add `OUTPUT_FORMAT` environment variable in `utils.py`

3. Update `main.py` to call appropriate formatter

4. Add tests in `test_formatter.py` for JSON output

5. Maintain backward compatibility (default to markdown)