agentleFS
jarosser06jarosser06/drift/.claude/skills/pr-writing/SKILL.md

pr-writing

Skill1 starsChanged 11 months agoMITView on GitHub

Expert in creating well-structured pull requests with clear summaries. Use when writing or structuring PRs.

  • Deletes or force-pushes
  • Commits and pushes

6 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

4 rules. 0 are common, 3 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use draft=True for work-in-progress PRs:

    line 134
  2. Distinctive:

    If your PR has 20+ files or 1000+ lines changed, consider breaking it up:

    line 261
  3. Distinctive:

    Add caching to detector calls

    line 270
  4. Distinctive:

    If your PR has many files, call out the key ones:

    line 304

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

PR Writing Skill

Learn how to create well-structured, reviewable pull requests using the GitHub MCP server.

How to Write PR Descriptions

How to Structure Your PR

A well-structured PR includes:

  1. Summary - What changed and why
  2. Changes - What files were affected
  3. Related Issues - Links to relevant issues

Example structure:

## Summary
- Added multi-drift-type analysis support
- Implemented sequential processing for each type
- Combined results in unified output format

## Changes
### Added
- `drift/multi_analyzer.py` - Multi-pass analysis logic
- Tests in `tests/integration/test_multi_pass.py`

### Modified
- `drift/cli.py:45-67` - CLI multi-type support
- `README.md` - Usage examples updated

## Related Issues
Closes #42

How to Write Effective Summaries

Use bullet points (3-5 bullets):

## Summary
- Added multi-drift-type analysis support to CLI
- Implemented sequential processing for each drift type
- Combined results in unified output format

Focus on WHAT changed and WHY, not HOW:

Good:

- Added caching to reduce API calls
- Improved error messages for config validation
- Fixed race condition in parallel processing

Avoid:

- Changed line 45 in cli.py to add a new variable called cache_dict
- Updated the error handling function to print better messages
- Added a lock object to the ProcessPool initialization

How to Document Changes

Organize by category (Added/Modified/Removed):

Good example:

## Changes

### Added
- `drift/multi_analyzer.py` - Multi-pass analysis engine
- `tests/integration/test_multi_pass.py` - Integration tests
- `.drift.yaml` example with multi-type config

### Modified
- `drift/cli.py:45-67` - CLI argument parsing for multi-type
- `drift/detector.py:120-145` - Detection logic refactoring
- `README.md` - Usage examples and configuration docs

### Removed
- `drift/legacy_analyzer.py` - Deprecated single-pass analyzer

Avoid unorganized lists:

## Changes
- cli.py
- detector.py
- multi_analyzer.py
- README.md

How to Create PRs with MCP

Basic PR Creation

mcp__github__create_pull_request(
    owner="jarosser06",
    repo="drift",
    title="Issue #42: Add multi-drift-type support",
    head="issue-42-add-multi-type",
    base="main",
    body="""## Summary

- Added multi-drift-type analysis support to CLI
- Implemented sequential processing for each drift type
- Combined results in unified output format

## Changes

### Added
- `drift/multi_analyzer.py` - Multi-pass analysis
- Tests in `tests/integration/test_multi_pass.py`

### Modified
- `drift/cli.py:45-67` - Multi-type support
- `README.md` - Usage examples

## Related Issues

Closes #42

""",
    draft=False
)

How to Create Draft PRs

Use draft=True for work-in-progress PRs:

mcp__github__create_pull_request(
    owner="jarosser06",
    repo="drift",
    title="WIP: Issue #42: Add multi-drift-type support",
    head="issue-42-add-multi-type",
    base="main",
    body="## Summary\n\nWork in progress...",
    draft=True
)

Convert to ready when done via GitHub UI or update the PR.

How to Write Good PR Titles

Format: Issue #<number>: <Descriptive title>

Good examples:

  • Issue #42: Add multi-drift-type analysis support
  • Issue #15: Fix config parser KeyError on missing sections
  • Issue #8: Improve CLI output formatting
  • Issue #23: Refactor detector to use plugin architecture

What makes these good:

  • References the issue number
  • Describes what changed, not how
  • Clear and specific
  • Concise (under 72 characters)

Bad examples:

  • Update cli.py - No context about what or why
  • Fix bug - Which bug? What was fixed?
  • Add feature - Which feature?
  • Issue #42 - Missing description
  • Implemented a new multi-pass analysis system with sequential processing - Too long and detailed

Pre-PR Workflow

Step-by-Step Checklist

Step 1: Run quality checks

# Ensure all linters pass
./lint.sh

# Ensure all tests pass with coverage
./test.sh --coverage

Step 2: Review your own changes

# See full diff against main
git diff main...HEAD

# Or use GitHub's compare view

Look for:

  • Debug code or print statements
  • Commented-out code blocks
  • Unrelated changes
  • Missing docstrings
  • TODO comments

Step 3: Update branch with main

# Fetch latest main
git fetch origin

# Rebase on main
git rebase origin/main

# Or merge if you prefer
git merge origin/main

Step 4: Push branch to remote

git push -u origin issue-42-add-feature

# If you rebased and already pushed
git push --force-with-lease origin issue-42-add-feature

Step 5: Create PR via MCP

mcp__github__create_pull_request(
    owner="jarosser06",
    repo="drift",
    title="Issue #42: Add multi-drift-type support",
    head="issue-42-add-feature",
    base="main",
    body="<PR description>"
)

How to Make PRs Reviewable

Keep PRs Focused

Good - focused PR:

## Summary
- Add caching support to reduce API calls
- Implements LRU cache with configurable size
- Add cache stats to debug output

Single feature, related changes.

Bad - unfocused PR:

## Summary
- Add caching support
- Fix typo in README
- Refactor config loading
- Update CI workflow
- Add new validator

Multiple unrelated changes make review difficult.

Break Up Large Changes

If your PR has 20+ files or 1000+ lines changed, consider breaking it up:

Example breakdown:

  1. PR 1: "Add caching infrastructure"
    • Cache interface and base implementation
    • Configuration schema updates
    • Tests for cache module
  2. PR 2: "Integrate caching in detector"
    • Add caching to detector calls
    • Update existing tests
    • Performance benchmarks
  3. PR 3: "Add cache configuration"
    • CLI flags for cache control
    • Config file support
    • Documentation updates

Provide Context in PR Description

Good context:

## Summary
- Fixed race condition in parallel processing

## Background
Previously, multiple workers could access the shared result dict
simultaneously without synchronization, causing occasional data loss.
This happened about 1 in 50 runs when using --parallel flag.

## Solution
- Added threading.Lock around result updates
- Verified fix with 1000 test runs

Bad - no context:

## Summary
- Fixed bug in parallel processing

Highlight Important Files

If your PR has many files, call out the key ones:

## Changes

### Key Files to Review
1. `drift/multi_analyzer.py` - Core logic for multi-pass analysis
2. `tests/integration/test_multi_pass.py` - Integration test coverage

### Supporting Changes
- `drift/cli.py:45-67` - CLI integration
- `README.md` - Documentation updates

Resources

📖 PR Template

Complete pull request templates for features, bug fixes, and refactoring.

Use when: Creating a new pull request and need structure.

📖 Good PR Examples

Real examples of excellent pull requests with annotations.

Use when: Learning what makes a good PR or validating your PR before creating it.

Common PR Workflows

Creating PR After Feature Work

# 1. Ensure quality
# Run ./lint.sh and ./test.sh --coverage

# 2. Update branch
# git fetch && git rebase origin/main

# 3. Push
# git push -u origin issue-42-add-feature

# 4. Create PR
pr = mcp__github__create_pull_request(
    owner="jarosser06",
    repo="drift",
    title="Issue #42: Add custom validator support",
    head="issue-42-add-feature",
    base="main",
    body="""## Summary
- Added CustomValidator base class
- Implemented plugin loading system
- Updated config schema

## Changes

### Added
- `drift/validators/custom.py` - CustomValidator class
- `tests/unit/test_custom_validator.py` - Tests

### Modified
- `drift/config.py:120-145` - Schema updates
- `README.md` - Plugin documentation

## Related Issues
Closes #42
"""
)

print(f"PR created: {pr['html_url']}")

Updating PR Description

# Get current PR
pr = mcp__github__get_pull_request(owner, repo, pull_number=50)

# Update with new description
mcp__github__create_or_update_file(
    owner=owner,
    repo=repo,
    path=".github/pull_request_template.md",
    content="Updated PR description...",
    message="Update PR description",
    branch=pr["head"]["ref"]
)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.