Pre-PR Checklist Skill

Validates that all required documentation and artifacts exist before creating a pull request. Prevents PRs from being created with missing documentation, tests, or planning artifacts.

When This Skill Activates

• Before creating a pull request
• When user runs /pre-pr-checklist
• When user asks to validate PR readiness
• After completing work, before committing

Documentation Requirements Matrix

Complexity Indicators

A change is "complex" if any of these apply:

• Touches 5+ files
• Modifies database models or migrations
• Changes core business logic (scheduling, ACGME, constraints)
• Requires coordination across frontend/backend
• Has non-obvious implementation details
• Required debugging or multiple iterations

Pre-Flight Verification Steps

Step 1: Classify the Change

# Get list of changed files
git diff --cached --name-only
git diff origin/main...HEAD --name-only

# Count files changed
git diff origin/main...HEAD --stat | tail -1

# Check for database changes
git diff origin/main...HEAD --name-only | grep -E "(alembic|models)"

# Check for frontend/backend span
git diff origin/main...HEAD --name-only | grep -c "^frontend/"
git diff origin/main...HEAD --name-only | grep -c "^backend/"

Determine change type:

• New feature
• Bug fix
• Code change (enhancement)
• Documentation only
• Refactoring
• Dependency update

Step 2: Check Scratchpad Entry

Location: docs/development/scratchpad/ or docs/planning/

For complex work, verify a scratchpad or planning document exists:

# Check for recent scratchpad entries
find docs/development -name "*.md" -mtime -1 | head -10

# Check for session handoffs
find docs/development -name "SESSION_*.md" -mtime -1

# Check for planning docs
find docs/planning -name "*.md" -mtime -1 | head -10

Scratchpad must contain:

• Problem statement / motivation
• Approach taken
• Key decisions and rationale
• Files modified
• Testing approach

Step 3: Check CHANGELOG Update

Location: CHANGELOG.md (project root)

# Check if CHANGELOG was modified
git diff origin/main...HEAD --name-only | grep "CHANGELOG.md"

# View CHANGELOG additions
git diff origin/main...HEAD -- CHANGELOG.md | grep "^+" | head -20

CHANGELOG entry must:

• Be under ## [Unreleased] section
• Use correct category (Added, Changed, Fixed, Removed, Security)
• Describe what changed from user perspective
• Include date if significant

Step 4: Check Test Coverage

Backend tests: backend/tests/ Frontend tests: frontend/__tests__/ or *.test.ts(x)

# Check for new/modified tests
git diff origin/main...HEAD --name-only | grep -E "test_.*\.py$|\.test\.(ts|tsx)$|\.spec\.(ts|tsx)$"

# Run backend tests
cd backend && pytest --tb=short -q

# Run frontend tests
cd frontend && npm test -- --watchAll=false

Test requirements:

• Tests exist for new code
• Tests pass locally
• Coverage maintained or improved
• Edge cases covered

Step 5: Check Plan File (If Complex)

Location: docs/planning/ or docs/development/

For complex work, verify a plan document exists:

# Check for plan files
ls -la docs/planning/*PLAN*.md 2>/dev/null
ls -la docs/planning/*IMPLEMENTATION*.md 2>/dev/null

Plan must contain:

• Scope and objectives
• Implementation approach
• Success criteria
• Risk considerations

Quick Validation Script

Run this before creating a PR:

#!/bin/bash
# Pre-PR Checklist Validation

echo "============================================================"
echo "PRE-PR CHECKLIST VALIDATION"
echo "============================================================"

# Get changed files
CHANGED_FILES=$(git diff origin/main...HEAD --name-only)
FILE_COUNT=$(echo "$CHANGED_FILES" | wc -l)

echo ""
echo "Changed files: $FILE_COUNT"
echo "$CHANGED_FILES" | head -10
echo ""

# Complexity check
echo "============================================================"
echo "COMPLEXITY ANALYSIS"
echo "============================================================"

COMPLEX=0

if [ "$FILE_COUNT" -gt 5 ]; then
    echo "[!] 5+ files changed - marked as COMPLEX"
    COMPLEX=1
fi

if echo "$CHANGED_FILES" | grep -q "alembic\|models"; then
    echo "[!] Database changes detected - marked as COMPLEX"
    COMPLEX=1
fi

if echo "$CHANGED_FILES" | grep -q "scheduling\|constraints\|acgme"; then
    echo "[!] Core business logic changed - marked as COMPLEX"
    COMPLEX=1
fi

FE_COUNT=$(echo "$CHANGED_FILES" | grep -c "^frontend/" || true)
BE_COUNT=$(echo "$CHANGED_FILES" | grep -c "^backend/" || true)
if [ "$FE_COUNT" -gt 0 ] && [ "$BE_COUNT" -gt 0 ]; then
    echo "[!] Frontend + Backend changes - marked as COMPLEX"
    COMPLEX=1
fi

if [ "$COMPLEX" -eq 0 ]; then
    echo "[OK] Change appears straightforward"
fi

echo ""

# CHANGELOG check
echo "============================================================"
echo "CHANGELOG CHECK"
echo "============================================================"

if echo "$CHANGED_FILES" | grep -q "CHANGELOG.md"; then
    echo "[OK] CHANGELOG.md modified"
else
    echo "[?] CHANGELOG.md not modified - required if user-facing change"
fi

echo ""

# Test check
echo "============================================================"
echo "TEST CHECK"
echo "============================================================"

TEST_FILES=$(echo "$CHANGED_FILES" | grep -E "test_.*\.py$|\.test\.(ts|tsx)$|\.spec\.(ts|tsx)$" || true)
if [ -n "$TEST_FILES" ]; then
    echo "[OK] Test files modified:"
    echo "$TEST_FILES" | head -5
else
    echo "[?] No test files modified - required for code changes"
fi

echo ""

# Scratchpad/Plan check (if complex)
echo "============================================================"
echo "DOCUMENTATION CHECK"
echo "============================================================"

if [ "$COMPLEX" -eq 1 ]; then
    echo "[!] Complex change - checking for documentation..."

    RECENT_DOCS=$(find docs/development docs/planning -name "*.md" -mtime -1 2>/dev/null | head -5)
    if [ -n "$RECENT_DOCS" ]; then
        echo "[OK] Recent documentation found:"
        echo "$RECENT_DOCS"
    else
        echo "[?] No recent documentation found - consider adding scratchpad/plan"
    fi
else
    echo "[OK] Simple change - detailed documentation optional"
fi

echo ""
echo "============================================================"
echo "SUMMARY"
echo "============================================================"

echo ""
echo "Before creating PR, ensure:"
if [ "$COMPLEX" -eq 1 ]; then
    echo "  [ ] Scratchpad entry exists (complex change)"
    echo "  [ ] Plan file exists (complex change)"
fi
echo "  [ ] CHANGELOG updated (if user-facing)"
echo "  [ ] Tests added/updated (if code change)"
echo "  [ ] All tests pass"
echo ""

Checklist by Change Type

New Feature Checklist

• Scratchpad entry - Document motivation, approach, decisions
• CHANGELOG entry - Under ### Added with user-friendly description
• Unit tests - Cover happy path and edge cases
• Integration tests - If applicable
• Plan file - docs/planning/FEATURE_NAME_PLAN.md
• API docs - If new endpoints (docstrings + OpenAPI)
• User guide update - If user-facing

Bug Fix Checklist

• Scratchpad entry - If debugging was complex
• CHANGELOG entry - Under ### Fixed with what was broken
• Regression test - Test that reproduces the bug
• Root cause documented - In commit message or scratchpad

Code Change (Enhancement) Checklist

• Scratchpad entry - If complex
• CHANGELOG entry - Under ### Changed if user-facing
• Tests updated - Reflect new behavior
• Existing tests pass - No regressions

Documentation Only Checklist

• CHANGELOG entry - Under ### Changed if significant
• Links verified - All internal links work
• Spelling/grammar - Proofread

Output Format

After running validation, report:

## Pre-PR Checklist Results

### Change Classification
- **Type:** [New Feature / Bug Fix / Code Change / Documentation / Refactoring]
- **Complexity:** [Simple / Complex]
- **Files Changed:** [count]

### Required Documentation Status

| Requirement | Status | Notes |
|-------------|--------|-------|
| Scratchpad Entry | [OK/MISSING/N/A] | [path or reason] |
| CHANGELOG Update | [OK/MISSING/N/A] | [path or reason] |
| Tests | [OK/MISSING/N/A] | [path or reason] |
| Plan File | [OK/MISSING/N/A] | [path or reason] |

### Blockers
[List any missing requirements that must be addressed]

### Recommendations
[List optional improvements]

### Verdict
[READY TO CREATE PR / BLOCKED - address items above]

Integration with Other Skills

Escalation Rules

Block PR creation when:

1. Code changes have no tests
2. User-facing changes have no CHANGELOG entry
3. Complex changes have no documentation
4. Tests are failing

Allow with warning when:

1. Documentation is minimal but present
2. CHANGELOG entry is generic
3. Only dependency updates

References

• Session Documentation skill for scratchpad requirements
• CHANGELOG.md format: Keep a Changelog
• Test requirements: CLAUDE.md Testing Requirements section