Tarun Moorjani

Posted on Mar 6

TypeScript PR Templates and Checklists: Copy-Paste and Go

#react #webdev #javascript #typescript

I've reviewed over a lot TypeScript PRs. The best teams use templates and checklists. The struggling teams don't.

Without templates:

Developers forget to mention breaking changes
Type safety issues slip through
Performance regressions go unnoticed
Accessibility gets overlooked
PRs sit for days because reviewers need more context

With templates:

Every PR has consistent structure
Critical checks are never forgotten
Reviewers know exactly what to look for
Approval happens faster
Quality stays high

Here are the exact templates and checklists I use. Copy them. Customize them. Ship better code.

Quick Start: GitHub PR Template

Create .github/PULL_REQUEST_TEMPLATE.md in your repo:

## Changes

<!-- Brief description of what changed -->

## Type of Change

- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
- [ ] ✨ New feature (non-breaking change which adds functionality)
- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
- [ ] 📝 Documentation update
- [ ] 🎨 Style/UI update (no functional changes)
- [ ] ♻️ Code refactor (no functional changes)
- [ ] ⚡ Performance improvement
- [ ] ✅ Test update
- [ ] 🔧 Configuration change
- [ ] 📦 Dependency update

## Checklist

- [ ] My code follows the project's style guidelines
- [ ] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have made corresponding changes to the documentation
- [ ] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my feature works
- [ ] New and existing unit tests pass locally with my changes
- [ ] Any dependent changes have been merged and published

## Related Issues

Fixes #
Related to #

This is the minimal viable template. Let's make it better.

The Complete TypeScript PR Template

## Summary

<!-- 1-2 sentence summary of changes -->

## Problem

<!-- What bug are you fixing? What feature are you adding? Why? -->

**Impact:**
<!-- How many users? How severe? Business context? -->

## Solution

<!-- High-level approach. Key decisions made and why. -->

**Type Safety:**
<!-- Any changes to types? New interfaces? Breaking type changes? -->

**Alternatives Considered:**
<!-- What else did you try? Why did you choose this approach? -->

## Type of Change

- [ ] 🐛 Bug fix (non-breaking)
- [ ] ✨ New feature (non-breaking)
- [ ] 💥 Breaking change
- [ ] 📝 Documentation
- [ ] ♻️ Refactor
- [ ] ⚡ Performance
- [ ] ✅ Tests
- [ ] 🔒 Security fix
- [ ] ♿ Accessibility improvement

## TypeScript Checklist

- [ ] No new `any` types (or justified with comments)
- [ ] No `@ts-ignore` without explanation
- [ ] All new interfaces/types are exported from appropriate files
- [ ] Type imports use `import type` syntax
- [ ] No type assertions without runtime validation
- [ ] Discriminated unions used for state machines
- [ ] Generic types have proper constraints
- [ ] Return types are explicit for public APIs

## Testing

**Manual Testing:**
- [ ] Tested happy path
- [ ] Tested error cases
- [ ] Tested edge cases
- [ ] Verified in dev environment
- [ ] Verified in staging (if applicable)

**Automated Testing:**
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] E2E tests added/updated (if applicable)
- [ ] All tests passing locally
- [ ] Coverage maintained or improved

**Test Cases:**
<!-- List specific scenarios tested -->

## Performance

- [ ] No performance regressions
- [ ] Expensive operations are memoized
- [ ] No unnecessary re-renders
- [ ] Bundle size impact checked (if applicable)
- [ ] Large imports are code-split
- [ ] Images are optimized (if applicable)

## Security

- [ ] No sensitive data in logs
- [ ] No hardcoded secrets
- [ ] User input is validated/sanitized
- [ ] No XSS vulnerabilities
- [ ] Authentication/authorization checked
- [ ] CSRF protection in place (if applicable)

## Accessibility

- [ ] Semantic HTML used
- [ ] ARIA labels added where needed
- [ ] Keyboard navigation works
- [ ] Focus management is correct
- [ ] Color contrast is sufficient
- [ ] Screen reader tested (if UI change)

## Breaking Changes

<!-- List any breaking changes and migration path -->

**Migration Guide:**
<!-- How do other developers/users adapt to this change? -->

## Screenshots/Videos

<!-- For UI changes: before/after screenshots or screen recording -->

## Deployment Notes

- [ ] No database migrations required
- [ ] No environment variable changes required
- [ ] No infrastructure changes required
- [ ] Feature flags configured (if applicable)
- [ ] Rollback plan documented

**Rollback Plan:**
<!-- How to rollback if issues occur -->

## Related

Fixes #
Closes #
Part of #
Depends on #
Blocks #

**Documentation:**
- [ ] README updated
- [ ] API docs updated
- [ ] Changelog updated
- [ ] Migration guide created (if breaking)

## Reviewer Notes

<!-- Anything specific reviewers should focus on? Questions for reviewers? -->

---

## Pre-Merge Checklist

- [ ] CI/CD pipeline passing
- [ ] Code reviewed and approved
- [ ] All comments addressed
- [ ] Conflicts resolved
- [ ] Branch is up to date with main/master
- [ ] Ready to merge

Template Variations by PR Type

1. Bug Fix Template

## Bug Fix: [Brief Description]

## Bug Details

**What's Broken:**
<!-- Exact error message, unexpected behavior -->

**Steps to Reproduce:**
1. 
2. 
3. 

**Expected Behavior:**
<!-- What should happen -->

**Actual Behavior:**
<!-- What actually happens -->

**Impact:**
- Severity: [ ] Critical [ ] High [ ] Medium [ ] Low
- Affected Users: 
- Frequency: 
- Support Tickets: 

## Root Cause

<!-- Technical explanation of why this bug exists -->

## Solution

<!-- How does your fix solve the problem? -->

**Code Changes:**
- File 1: [what changed]
- File 2: [what changed]

## Testing

**Reproduction:**
- [ ] Reproduced bug before fix
- [ ] Verified fix resolves issue
- [ ] Cannot reproduce bug after fix

**Regression Testing:**
- [ ] Related features still work
- [ ] Edge cases covered
- [ ] Added regression test

**Test Cases:**
1. Original bug scenario: ✅ Fixed
2. Edge case A: ✅ Handled
3. Edge case B: ✅ Handled

## Type Safety

- [ ] No new `any` types
- [ ] Null/undefined handling improved
- [ ] Type guards added where needed

## Risks

**Rollback Plan:**
<!-- How to rollback if this causes issues -->

**Monitoring:**
<!-- What metrics to watch after deployment -->

Fixes #[issue-number]

2. New Feature Template

## Feature: [Feature Name]

## User Story

**As a** [type of user]
**I want** [goal]
**So that** [benefit]

## Business Value

**Why This Feature:**
<!-- Business justification, user need, competitive advantage -->

**Success Metrics:**
- Metric 1: 
- Metric 2: 
- Metric 3: 

## Implementation

**User Flow:**
1. User does X
2. System does Y
3. User sees Z

**Technical Approach:**
<!-- High-level architecture, key components -->

**TypeScript Patterns Used:**
- [ ] Discriminated unions for state
- [ ] Generic components
- [ ] Type-safe API calls
- [ ] Proper error types

## API Changes

**New Endpoints:**
<!-- If backend changes -->

**New Types:**

typescript
// List new interfaces/types


**Breaking Changes:**
<!-- Any breaking changes in API or types -->

## UI/UX Changes

**Screenshots:**
<!-- Before/after if modifying existing feature -->
<!-- New UI screenshots -->

**Responsive Design:**
- [ ] Mobile tested
- [ ] Tablet tested
- [ ] Desktop tested

**Accessibility:**
- [ ] Keyboard navigation works
- [ ] Screen reader compatible
- [ ] ARIA labels added

## Testing

**Feature Testing:**
- [ ] Happy path works
- [ ] Error handling works
- [ ] Edge cases handled

**Integration Testing:**
- [ ] Works with existing features
- [ ] No regressions in related features

**Performance:**
- [ ] No performance degradation
- [ ] Optimized for large datasets (if applicable)

## Documentation

- [ ] User documentation added
- [ ] API documentation added
- [ ] Code comments added
- [ ] README updated

## Rollout Plan

**Feature Flag:**
<!-- Feature flag name and configuration -->

**Phased Rollout:**
- [ ] Internal testing
- [ ] Beta users
- [ ] 10% of users
- [ ] 50% of users
- [ ] 100% of users

Implements #[issue-number]

3. Refactoring Template

## Refactor: [What You're Refactoring]

## Motivation

**Problems with Current Code:**
1. 
2. 
3. 

**Why Refactor Now:**
<!-- Why is this worth doing right now? -->

## Changes

**Before:**

typescript
// Old pattern/code


**After:**

typescript
// New pattern/code


**Improvements:**
- [ ] Reduced complexity
- [ ] Improved type safety
- [ ] Better performance
- [ ] Easier to test
- [ ] More maintainable

## TypeScript Improvements

- [ ] Replaced `any` with proper types
- [ ] Added type guards
- [ ] Improved generic constraints
- [ ] Better error types
- [ ] Stricter null checks

## Impact Analysis

**Files Changed:** 
**Lines Added/Removed:** 
**Behavior Changes:** None (pure refactor)

## Testing

- [ ] All existing tests pass
- [ ] No new bugs introduced
- [ ] Performance is same or better
- [ ] Coverage maintained or improved

**Verification:**
- [ ] Ran full test suite
- [ ] Manual smoke testing
- [ ] Verified in staging

## Migration Path

**For Other Developers:**
<!-- How do teammates adapt their code? -->

**Deprecated Code:**
<!-- What's being removed? When? -->

**Examples:**

typescript
// Old way (still works, deprecated)
const data = oldFunction();

// New way (preferred)
const data = newFunction();


## Risks

**Risk Level:** [ ] Low [ ] Medium [ ] High

**Mitigation:**
<!-- How are you reducing risk? -->

**Rollback:**
<!-- How to rollback if needed -->

Related to #[issue-number]

4. TypeScript Upgrade Template

## TypeScript Upgrade: [Old Version] → [New Version]

## Motivation

**Why Upgrade:**
- [ ] Security fixes
- [ ] New features needed
- [ ] Better type inference
- [ ] Bug fixes
- [ ] EOL of current version

**Benefits:**
1. 
2. 
3. 

## Breaking Changes

**Compiler:**
<!-- New errors, changed behavior -->

**Type System:**
<!-- Type inference changes, new strictness -->

**List of Breaking Changes:**
1. Change 1: Impact and fix
2. Change 2: Impact and fix
3. Change 3: Impact and fix

## Migration Summary

**Files Modified:** 
**Type Errors Fixed:** 
**Deprecations Addressed:** 

**Categories of Changes:**
- [ ] Added null checks
- [ ] Fixed type assertions
- [ ] Updated type imports
- [ ] Fixed generic constraints
- [ ] Other: 

## Testing

- [ ] All tests passing
- [ ] No new type errors
- [ ] No runtime errors in dev
- [ ] No console warnings
- [ ] Verified in staging

**Compatibility:**
- [ ] No breaking changes for consumers
- [ ] Library types updated
- [ ] Type definitions published (if library)

## Rollback Plan

<!-- How to downgrade if issues arise -->

## Developer Impact

**Action Required:**
- [ ] None (fully backward compatible)
- [ ] Update local TypeScript: `npm install`
- [ ] Fix new type errors (list provided)
- [ ] Update IDE settings

**Communication:**
<!-- How will you notify the team? -->

Related to #[issue-number]

5. Dependency Update Template

## Dependency Update: [Package] [Old] → [New]

## Package Details

**Package:** 
**Current Version:** 
**New Version:** 
**Type:** [ ] Production [ ] Development

## Why Update

- [ ] Security vulnerability (CVE: )
- [ ] Bug fix
- [ ] New features needed
- [ ] Breaking changes in ecosystem
- [ ] Performance improvement
- [ ] Other: 

## Changes

**Breaking Changes:**
<!-- List breaking changes from changelog -->

**New Features:**
<!-- Relevant new features -->

**Bug Fixes:**
<!-- Relevant bug fixes -->

## TypeScript Impact

- [ ] Type definitions updated
- [ ] No new type errors
- [ ] API changes reflected in types
- [ ] Generic constraints updated (if applicable)

## Testing

- [ ] All tests passing
- [ ] Verified functionality unchanged
- [ ] Tested new features (if using them)
- [ ] No console warnings
- [ ] Bundle size checked

**Bundle Size:**
- Before: 
- After: 
- Delta: 

## Migration Notes

**Code Changes Required:**
<!-- None, or list changes -->

**Configuration Changes:**
<!-- None, or list changes -->

## Compatibility

- [ ] Node.js version compatible
- [ ] React version compatible
- [ ] Other dependencies compatible
- [ ] No peer dependency conflicts

## Rollback

**Rollback Command:**

bash
npm install [package]@[old-version]


**Risk:** [ ] Low [ ] Medium [ ] High

Fixes #[issue-number]

6. Performance Optimization Template

## Performance: [What You're Optimizing]

## Problem

**Current Performance:**
- Metric 1: 
- Metric 2: 
- Metric 3: 

**User Impact:**
<!-- How does slow performance affect users? -->

## Solution

**Optimization Strategy:**
1. 
2. 
3. 

**Changes:**
- [ ] Added memoization
- [ ] Implemented code splitting
- [ ] Optimized re-renders
- [ ] Reduced bundle size
- [ ] Improved algorithm complexity
- [ ] Other: 

## Performance Gains

**Before:**
- Load time: 
- Bundle size: 
- Memory usage: 
- Render time: 

**After:**
- Load time: 
- Bundle size: 
- Memory usage: 
- Render time: 

**Improvement:** 

## TypeScript Considerations

- [ ] No type safety sacrificed for performance
- [ ] Memoization properly typed
- [ ] Generic constraints maintained
- [ ] Type inference still works

## Testing

**Performance Testing:**
- [ ] Lighthouse score improved
- [ ] Bundle analyzer checked
- [ ] Profiler shows improvements
- [ ] Tested with large datasets

**Regression Testing:**
- [ ] All features still work
- [ ] No visual regressions
- [ ] Error handling unchanged

## Benchmarks

Scenario 1:

Before: XXms
After: XXms
Improvement: XX%

Scenario 2:

Before: XXms
After: XXms
Improvement: XX%


## Trade-offs

**What was sacrificed:**
<!-- Code complexity? Readability? -->

**Is it worth it:**
<!-- Justify the trade-offs -->

Fixes #[issue-number]

7. Security Fix Template

## Security Fix: [Brief Description]

## ⚠️ Security Issue

**Severity:** [ ] Critical [ ] High [ ] Medium [ ] Low

**Type:**
- [ ] XSS vulnerability
- [ ] SQL injection
- [ ] Authentication bypass
- [ ] Authorization issue
- [ ] Data exposure
- [ ] Dependency vulnerability
- [ ] Other: 

**Affected:**
<!-- What users/data/systems are affected? -->

## Vulnerability Details

<!-- Describe the vulnerability (avoid public disclosure of exploits) -->

**CVE:** (if applicable)
**CVSS Score:** (if applicable)

## Fix

**What Changed:**
<!-- High-level description -->

**Security Improvements:**
- [ ] Input validation added
- [ ] Output encoding added
- [ ] Authentication strengthened
- [ ] Authorization checks added
- [ ] Dependency updated
- [ ] Other: 

## TypeScript Safety

- [ ] Type guards prevent injection
- [ ] Branded types for validated data
- [ ] Type-safe validation schemas
- [ ] No `any` in security-critical code

## Testing

**Security Testing:**
- [ ] Attempted exploit before fix (fails)
- [ ] Attempted exploit after fix (blocked)
- [ ] Penetration testing performed
- [ ] Security scan passed

**Regression Testing:**
- [ ] All features still work
- [ ] No broken authentication
- [ ] No broken authorization

## Deployment

**Urgency:** [ ] Deploy Immediately [ ] Deploy Soon [ ] Regular Deployment

**Rollout:**
<!-- How will this be deployed? -->

**Monitoring:**
<!-- What to watch after deployment? -->

## Communication

- [ ] Security team notified
- [ ] Users notified (if needed)
- [ ] Security advisory published (if needed)

Fixes #[issue-number]

Specialized Checklists

Type Safety Checklist

## Type Safety Review

**Basic Type Safety:**
- [ ] No explicit `any` types (or justified)
- [ ] No implicit `any` from missing types
- [ ] No `@ts-ignore` comments (or explained)
- [ ] No `@ts-expect-error` without TODO
- [ ] Type assertions justified with comments

**Advanced Type Safety:**
- [ ] Discriminated unions for state machines
- [ ] Type guards for runtime validation
- [ ] Generic constraints properly defined
- [ ] Conditional types used correctly
- [ ] Template literal types where appropriate

**Import/Export:**
- [ ] Type imports use `import type`
- [ ] All public APIs have explicit types
- [ ] Types exported from appropriate files
- [ ] No circular type dependencies

**Null/Undefined:**
- [ ] Null checks before access
- [ ] Optional chaining used (`?.`)
- [ ] Nullish coalescing used (`??`)
- [ ] Non-null assertions justified (`!`)

**Functions:**
- [ ] Parameters properly typed
- [ ] Return types explicit for public APIs
- [ ] Async functions return Promise<T>
- [ ] Callbacks properly typed

**React Components:**
- [ ] Props interface defined
- [ ] Children typed correctly
- [ ] Event handlers typed
- [ ] Ref types correct
- [ ] Generic components properly constrained

**API/External Data:**
- [ ] API responses validated at runtime
- [ ] JSON parsing is type-safe
- [ ] External data has type guards
- [ ] Errors are properly typed

**Edge Cases:**
- [ ] Empty arrays handled
- [ ] undefined vs null distinguished
- [ ] Optional properties handled
- [ ] Union types narrowed correctly

Performance Checklist

## Performance Review

**React Performance:**
- [ ] No unnecessary re-renders
- [ ] useMemo for expensive calculations
- [ ] useCallback for callbacks
- [ ] React.memo for expensive components
- [ ] Virtualization for large lists
- [ ] Code splitting implemented

**Bundle Size:**
- [ ] Tree shaking enabled
- [ ] Dead code eliminated
- [ ] Large libraries code-split
- [ ] Import only what's needed
- [ ] Bundle analyzer reviewed

**Assets:**
- [ ] Images optimized
- [ ] SVGs minified
- [ ] Fonts subset (if applicable)
- [ ] Lazy loading for images
- [ ] WebP format used (if applicable)

**Network:**
- [ ] API calls debounced/throttled
- [ ] Requests cached appropriately
- [ ] Parallel requests where possible
- [ ] Request cancellation on unmount
- [ ] Prefetching implemented

**Runtime:**
- [ ] No synchronous expensive operations
- [ ] Web Workers for heavy computation
- [ ] RequestIdleCallback for non-critical
- [ ] Intersection Observer for lazy load
- [ ] No memory leaks (listeners cleaned up)

**Measurement:**
- [ ] Lighthouse score checked
- [ ] Bundle size measured
- [ ] Core Web Vitals acceptable
- [ ] Performance budget not exceeded

Accessibility Checklist

## Accessibility Review

**Semantic HTML:**
- [ ] Proper heading hierarchy (h1-h6)
- [ ] Lists use ul/ol/li
- [ ] Buttons are <button>
- [ ] Links are <a>
- [ ] Forms use <form>
- [ ] Tables use proper structure

**ARIA:**
- [ ] ARIA labels where needed
- [ ] ARIA roles appropriate
- [ ] ARIA states/properties correct
- [ ] No redundant ARIA
- [ ] Live regions for dynamic content

**Keyboard Navigation:**
- [ ] All interactive elements focusable
- [ ] Tab order logical
- [ ] Focus visible
- [ ] No keyboard traps
- [ ] Shortcuts don't conflict
- [ ] Enter/Space work on custom buttons

**Screen Reader:**
- [ ] Alt text for images
- [ ] Form labels associated
- [ ] Error messages announced
- [ ] Loading states announced
- [ ] Success messages announced

**Visual:**
- [ ] Color contrast meets WCAG AA
- [ ] Information not conveyed by color alone
- [ ] Focus indicators visible
- [ ] Text is resizable
- [ ] No flashing/blinking content

**Forms:**
- [ ] Labels properly associated
- [ ] Required fields marked
- [ ] Error messages clear
- [ ] Error messages linked to fields
- [ ] Field validation accessible

**Testing:**
- [ ] Keyboard-only navigation tested
- [ ] Screen reader tested (if major change)
- [ ] Axe DevTools passing
- [ ] Lighthouse accessibility > 90

Security Checklist

## Security Review

**Input Validation:**
- [ ] All user input validated
- [ ] Type validation with TypeScript
- [ ] Runtime validation (Zod/Yup)
- [ ] SQL injection prevented
- [ ] Command injection prevented

**Output Encoding:**
- [ ] XSS prevention (React does this, but check dangerouslySetInnerHTML)
- [ ] No unsanitized HTML rendering
- [ ] URLs validated before rendering
- [ ] JavaScript: URLs blocked

**Authentication:**
- [ ] Authentication required where needed
- [ ] Tokens stored securely
- [ ] Session management secure
- [ ] Logout clears all auth data
- [ ] Password fields use type="password"

**Authorization:**
- [ ] Authorization checks on sensitive operations
- [ ] RBAC implemented correctly
- [ ] No client-side only authorization
- [ ] API authorization verified

**Data Exposure:**
- [ ] No sensitive data in logs
- [ ] No sensitive data in URLs
- [ ] No sensitive data in error messages
- [ ] No API keys in frontend code
- [ ] Environment variables used correctly

**Dependencies:**
- [ ] No known vulnerabilities (npm audit)
- [ ] Dependencies up to date
- [ ] Only trusted packages used
- [ ] Package checksums verified

**HTTPS/Transport:**
- [ ] All requests use HTTPS
- [ ] Cookies are Secure and HttpOnly
- [ ] CORS configured correctly
- [ ] CSP headers configured

**File Uploads:**
- [ ] File type validation
- [ ] File size limits
- [ ] Virus scanning (if applicable)
- [ ] Files not executable on server

Pre-Submission Checklist

Use this before clicking "Create Pull Request":

## Pre-Submission Checklist

**Code Quality:**
- [ ] Code is formatted (Prettier)
- [ ] Code is linted (ESLint)
- [ ] No console.logs left in code
- [ ] No commented-out code
- [ ] No TODO comments (or issues created)
- [ ] No debug code left in

**Git:**
- [ ] Commits are logical
- [ ] Commit messages are clear
- [ ] No merge commits (rebased)
- [ ] No conflicts with base branch
- [ ] Branch is up to date

**Testing:**
- [ ] All tests passing locally
- [ ] New tests added for new code
- [ ] Coverage maintained or improved
- [ ] Manual testing performed
- [ ] Edge cases tested

**Documentation:**
- [ ] README updated (if needed)
- [ ] Code comments added
- [ ] Complex logic explained
- [ ] API documentation updated
- [ ] Migration guide written (if breaking)

**TypeScript:**
- [ ] No new type errors
- [ ] No new `any` types
- [ ] Type imports use `import type`
- [ ] Public APIs have explicit types

**Performance:**
- [ ] No performance regressions
- [ ] Bundle size checked
- [ ] Expensive operations optimized
- [ ] Images optimized (if added)

**Security:**
- [ ] No hardcoded secrets
- [ ] Input validation added
- [ ] No XSS vulnerabilities
- [ ] npm audit passing

**Accessibility:**
- [ ] Keyboard navigation works
- [ ] ARIA labels added
- [ ] Color contrast sufficient
- [ ] Screen reader tested (if major UI)

**CI/CD:**
- [ ] CI pipeline passing
- [ ] Build succeeds
- [ ] Deploy previewed (if available)

**PR Description:**
- [ ] Problem clearly described
- [ ] Solution explained
- [ ] Testing documented
- [ ] Screenshots added (if UI)
- [ ] Links to issues added
- [ ] Breaking changes noted

Reviewer Checklist

For the person reviewing the PR:

## Code Review Checklist

**First Pass (5 minutes):**
- [ ] PR description is clear
- [ ] Changes make sense at high level
- [ ] Tests are included
- [ ] CI is passing
- [ ] No obvious red flags

**Type Safety (10 minutes):**
- [ ] No liberal use of `any`
- [ ] Type assertions justified
- [ ] Null checks present
- [ ] Proper type narrowing
- [ ] Generic constraints correct

**Code Quality (15 minutes):**
- [ ] Code is readable
- [ ] Logic is sound
- [ ] No obvious bugs
- [ ] Error handling present
- [ ] Edge cases handled

**React Patterns (10 minutes):**
- [ ] Hooks rules followed
- [ ] Dependencies correct
- [ ] No unnecessary re-renders
- [ ] State management appropriate
- [ ] No prop drilling (or justified)

**Testing (5 minutes):**
- [ ] Tests are meaningful
- [ ] Coverage is adequate
- [ ] Edge cases tested
- [ ] Mocks are appropriate

**Performance (5 minutes):**
- [ ] No obvious performance issues
- [ ] Expensive operations optimized
- [ ] Bundle size impact acceptable
- [ ] Images optimized (if added)

**Security (5 minutes):**
- [ ] No security vulnerabilities
- [ ] Input validated
- [ ] No exposed secrets
- [ ] Authentication/authorization correct

**Accessibility (5 minutes):**
- [ ] Semantic HTML used
- [ ] Keyboard navigation works
- [ ] ARIA labels present
- [ ] Color contrast good

**Final Check:**
- [ ] Would I be comfortable shipping this?
- [ ] Is this better than it was?
- [ ] Are my concerns addressed?
- [ ] Ready to approve?

GitHub Setup

Install PR Template

# Create .github directory
mkdir -p .github

# Create PR template
touch .github/PULL_REQUEST_TEMPLATE.md

Paste your chosen template into PULL_REQUEST_TEMPLATE.md.

Multiple Templates

For different PR types:

.github/
  PULL_REQUEST_TEMPLATE/
    bug_fix.md
    feature.md
    refactor.md
    dependency.md

Users select template when creating PR.

Issue Templates

.github/
  ISSUE_TEMPLATE/
    bug_report.md
    feature_request.md

AI Tools: Automate Template Generation

Don't fill out templates manually. Let AI do the heavy lifting while you add context.

Claude Code Skills: The Secret to Consistency

Claude Code skills are game-changing for PR templates. They enforce consistency across your entire team automatically.

What are Claude Code skills?

Reusable prompts that execute consistently
Live in your .claude/ directory
Version controlled with your code
Shared across your team

The power: Same template, same quality, every time.

Setting Up PR Template Skills

Step 1: Create a skill file

mkdir -p .claude/skills
touch .claude/skills/pr-description.md

Step 2: Write the skill

# PR Description Generator

You are helping a developer write a TypeScript PR description.

## Your Task

Analyze the git diff and generate a complete PR description following our template.

## Template to Use

## Summary
[1-2 sentence overview]

## Problem
[What bug/feature? Why does it matter?]

**Impact:**
[Users affected, severity, business context]

## Solution
[High-level approach, key decisions]

**Type Safety:**
[Any type changes? Breaking changes?]

## Testing
**Manual Testing:**
- [ ] Happy path tested
- [ ] Error cases tested
- [ ] Edge cases tested

**Automated Testing:**
- [ ] Unit tests added
- [ ] Integration tests added
- [ ] All tests passing

## TypeScript Checklist
- [ ] No new `any` types (or justified)
- [ ] No `@ts-ignore` without explanation
- [ ] Type imports use `import type`
- [ ] Proper null handling

## Performance
- [ ] No performance regressions
- [ ] Expensive operations memoized
- [ ] Bundle size checked

## Security
- [ ] No sensitive data in logs
- [ ] Input validated
- [ ] No XSS vulnerabilities

## Screenshots
[If UI change]

Fixes #

## Instructions

1. Read the git diff carefully
2. Identify what changed and why
3. Fill out each section of the template
4. Be specific - no vague statements
5. Check all relevant checklist items based on the changes
6. Leave unchecked items that don't apply
7. If you don't have enough context for a section, put [NEEDS AUTHOR INPUT]

## Important

- Focus on WHY, not just WHAT changed
- Identify type safety implications
- Flag potential performance impacts
- Note breaking changes
- Suggest test cases based on code changes

Step 3: Use the skill

# In your terminal
git diff main > /tmp/diff.txt
claude code --skill pr-description --input /tmp/diff.txt

Or even better:

# Create an alias
alias pr-gen="git diff main | claude code --skill pr-description"

# Now just run:
pr-gen

Result: Consistent, high-quality PR descriptions every time.

Creating Team-Specific Skills

Bug Fix Skill:

# .claude/skills/pr-bug-fix.md

Generate a bug fix PR description.

## Template

## Bug Fix: [Title]

## Bug Details

**What's Broken:**
[Error message, unexpected behavior]

**Steps to Reproduce:**
1. 
2. 
3. 

**Impact:**
- Severity: [Critical/High/Medium/Low]
- Users affected: [number or percentage]
- Frequency: [always/often/sometimes/rare]

## Root Cause
[Technical explanation]

## Solution
[How the fix works]

## Testing
**Verification:**
- [ ] Reproduced bug before fix
- [ ] Bug no longer reproduces
- [ ] Regression test added

Fixes #

## Instructions

1. Analyze the diff
2. Identify what was broken and why
3. Explain the fix clearly
4. Suggest appropriate test cases
5. Mark severity based on code impact

Feature Skill:

# .claude/skills/pr-feature.md

Generate a feature PR description.

## Template

## Feature: [Name]

## User Story
**As a** [user type]
**I want** [goal]
**So that** [benefit]

## Business Value
[Why this feature matters]

## Implementation
[Technical approach]

**New Types:**

typescript
// List interfaces/types added


## Testing
- [ ] Feature works end-to-end
- [ ] Error handling tested
- [ ] Edge cases covered

## Screenshots
[Before/after or new UI]

Implements #

## Instructions

1. Identify the new feature from the diff
2. Infer user story from code
3. List new TypeScript types/interfaces
4. Suggest comprehensive test cases
5. Request screenshots if UI changes detected

Refactoring Skill:

# .claude/skills/pr-refactor.md

Generate a refactoring PR description.

## Template

## Refactor: [What]

## Motivation
**Problems with current code:**
1. 
2. 

**Why now:**
[Why is this worth doing?]

## Changes
**Before:**

typescript
// Old pattern


**After:**

typescript
// New pattern


**Improvements:**
- [ ] Reduced complexity
- [ ] Better type safety
- [ ] Improved performance
- [ ] More testable

## Testing
- [ ] All existing tests pass
- [ ] No behavior changes
- [ ] Performance same or better

Related to #

## Instructions

1. Compare before/after patterns
2. Identify improvements (complexity, types, performance)
3. Ensure NO behavior changes mentioned
4. Verify tests validate refactor safety

Advanced: Checklist Validator Skill

# .claude/skills/pr-checklist-validator.md

You are a PR checklist validator for TypeScript React projects.

## Your Task

Review the code changes and verify each checklist item.

## Checklist to Validate

**Type Safety:**
- No explicit `any` types (or justified with comments)
- No `@ts-ignore` without explanation
- Type imports use `import type` syntax
- Proper null/undefined handling
- Type assertions are justified

**React Patterns:**
- Hooks rules followed (no conditional hooks)
- useEffect dependencies are correct
- No unnecessary re-renders
- Props are properly typed

**Performance:**
- Expensive operations are memoized
- No large imports (use tree-shaking)
- Images are optimized
- Code splitting where appropriate

**Security:**
- No hardcoded secrets
- Input is validated
- No XSS vulnerabilities
- No sensitive data in logs

**Accessibility:**
- Semantic HTML used
- ARIA labels where needed
- Keyboard navigation works

## Instructions

1. Analyze the diff carefully
2. For each checklist category:
   - Mark ✅ if ALL items in that category pass
   - Mark ⚠️ if some items need attention
   - Mark ❌ if critical items are violated
3. For any ⚠️ or ❌, list specific issues with file/line numbers
4. Provide concrete suggestions for fixes

## Output Format

### Type Safety ✅
All type safety checks pass.

### React Patterns ⚠️
Issues found:
- `UserProfile.tsx:45` - useEffect missing `userId` dependency
- `Dashboard.tsx:123` - useMemo needed for expensive calculation

### Performance ✅
No performance concerns.

### Security ❌
Critical issues:
- `api.ts:34` - API key hardcoded in source
- `LoginForm.tsx:67` - Password logged to console

### Accessibility ⚠️
Issues found:
- `Modal.tsx:23` - Missing ARIA label on close button

Usage:

git diff main | claude code --skill pr-checklist-validator

GitHub Copilot for Quick Templates

Copilot is great for quick, lightweight PR descriptions.

In VS Code, trigger Copilot Chat:

@workspace Generate a PR description for my staged changes. 
Use our team template: Problem, Solution, Testing, Type Safety checks.

Copilot strengths:

✅ Fast (inline in IDE)
✅ Understands workspace context
✅ Good for small PRs
✅ Integrated with GitHub PR UI

Copilot limitations:

❌ Less customizable than skills
❌ Shorter context window
❌ Can't enforce team standards as strictly
❌ Inconsistent output quality

Best use: Quick bug fixes and small features.

Claude (Web/API) for Complex PRs

For large, complex PRs, use Claude directly.

Example prompt:

I need a comprehensive PR description. Here's my git diff:

[paste diff]

Please create a PR description with:

1. Problem section (why this change is needed, business impact)
2. Solution section (technical approach, key decisions, why we chose this)
3. Testing section (specific test cases, coverage)
4. Type Safety review (any new types, breaking changes)
5. Performance impact (bundle size, runtime performance)
6. Security considerations
7. Breaking changes (if any, with migration guide)

Our team standards:
- Be specific, not vague
- Include actual numbers (users affected, performance gains)
- List test cases explicitly
- Flag all breaking changes
- Note TypeScript-specific concerns

Make it thorough and professional.

Claude strengths:

✅ Handles large diffs (100KB+)
✅ Deep analysis
✅ Can iterate and refine
✅ Follows complex instructions

Best use: Large refactors, complex features, critical fixes.

The Hybrid Workflow (Recommended)

Combine tools for best results:

# 1. Generate base description with skill
git diff main | claude code --skill pr-description > pr.md

# 2. Validate with checklist skill
git diff main | claude code --skill pr-checklist-validator >> pr.md

# 3. Review and add context
# Open pr.md, add:
# - Business context
# - Impact numbers
# - Screenshots
# - Specific testing details

# 4. Polish with Claude
# Paste pr.md into Claude: "Make this more concise and professional"

# 5. Copy to GitHub PR

Time savings:

Manual: 15-20 minutes
With skills: 5 minutes
With skills + AI polish: 7 minutes

Quality improvement:

Consistent structure ✅
All sections filled ✅
Checklist validated ✅
Professional tone ✅

Creating a Skills Library

Build a collection of reusable skills:

.claude/skills/
├── pr-description.md          # General PR template
├── pr-bug-fix.md             # Bug fix specific
├── pr-feature.md             # New feature specific
├── pr-refactor.md            # Refactoring specific
├── pr-dependency.md          # Dependency update
├── pr-performance.md         # Performance optimization
├── pr-security.md            # Security fix
├── pr-checklist-validator.md # Validate against checklist
├── pr-type-safety-check.md   # Type safety audit
└── pr-breaking-changes.md    # Breaking change detector

Team setup:

# In your README.md
## PR Description Generation

We use Claude Code skills for consistent PR descriptions.

**Quick start:**

bash

Generate PR description

git diff main | claude code --skill pr-description

Validate checklist

git diff main | claude code --skill pr-checklist-validator


**Available skills:**
- `pr-description` - General purpose
- `pr-bug-fix` - Bug fixes
- `pr-feature` - New features
- `pr-refactor` - Refactoring
- `pr-checklist-validator` - Validate against checklist

Example: Complete Skill-Driven Workflow

Scenario: You just fixed a bug.

# 1. Check your changes
git diff main

# 2. Generate bug fix description
git diff main | claude code --skill pr-bug-fix > pr-description.md

# 3. Validate against checklist
git diff main | claude code --skill pr-checklist-validator >> pr-description.md

# 4. Check for breaking changes
git diff main | claude code --skill pr-breaking-changes >> pr-description.md

# 5. Review the generated description
cat pr-description.md

# 6. Add your context:
# - Actual user impact numbers
# - Screenshots
# - Specific testing you performed

# 7. Create PR
gh pr create --title "Fix: User profile crash" --body-file pr-description.md

Result: Professional, complete PR description in under 5 minutes.

Advanced: Type-Safe Checklist Validator

Create a skill that not only validates but generates TypeScript-specific feedback:

# .claude/skills/pr-type-safety-deep-check.md

You are a TypeScript expert reviewing a PR for type safety.

## Deep Type Safety Analysis

Analyze the diff and report on:

**1. Any Usage:**
- Count of explicit `any` types
- Count of implicit `any` (missing types)
- For each `any`, suggest proper type

**2. Type Assertions:**
- List all `as` assertions
- Flag dangerous assertions
- Suggest type guards where appropriate

**3. Null Safety:**
- Find all optional chaining (`?.`) uses
- Find all nullish coalescing (`??`) uses
- Find missing null checks
- Suggest improvements

**4. Generic Types:**
- List all generic functions/components
- Check if constraints are needed
- Verify type inference works correctly

**5. Discriminated Unions:**
- Identify state machines
- Check if discriminated unions are used
- Suggest union types for boolean soup

**6. Type Imports:**
- Count `import type` vs regular imports
- Suggest converting to `import type`

## Output Format

### Type Safety Score: X/10

**Issues Found:**

🔴 **Critical (must fix):**
- Line 45: `any` type without justification
- Line 67: Unsafe type assertion

🟡 **Warnings (should fix):**
- Line 123: Missing null check
- Line 145: Could use discriminated union

🟢 **Suggestions (nice to have):**
- Line 200: Convert to `import type`
- Line 234: Add generic constraint

**Detailed Analysis:**

[For each issue, provide:
- File and line number
- Current code
- Suggested fix
- Explanation why]

Integration with GitHub Actions

Automate skill execution in CI:

# .github/workflows/pr-check.yml
name: PR Quality Check

on: [pull_request]

jobs:
  pr-quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Generate diff
        run: git diff origin/main > /tmp/pr-diff.txt

      - name: Validate checklist
        run: |
          claude code --skill pr-checklist-validator \
            --input /tmp/pr-diff.txt > /tmp/validation.md

      - name: Post validation as comment
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const validation = fs.readFileSync('/tmp/validation.md', 'utf8');

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## Automated PR Validation\n\n${validation}`
            });

Skills vs. Manual Templates: Comparison

Aspect	Manual Template	GitHub Copilot	Claude Code Skills
Consistency	❌ Varies by person	🟡 Somewhat	✅ Exactly the same
Time to fill	15 min	5 min	2 min
Quality	🟡 Depends on author	🟡 Pretty good	✅ Excellent
Team standards	❌ Manual enforcement	❌ Hard to enforce	✅ Automatic
Customization	✅ Fully custom	🟡 Limited	✅ Fully custom
Version control	✅ Yes	❌ No	✅ Yes
Onboarding	Slow (learn template)	Medium	Fast (just run)

Verdict: Claude Code skills win for team consistency and quality.

Real-World Example: Before and After

Before (manual template):

Developer spends 20 minutes filling template
Forgets to check type safety items
Misses performance implications
Generic testing section ("tested it, works")
Inconsistent quality across team

After (Claude Code skills):

# Developer runs:
git diff main | claude code --skill pr-description

# Gets back in 30 seconds:
- Complete, properly filled template
- Type safety checklist pre-validated
- Performance implications flagged
- Specific test cases suggested
- Professional, consistent quality

# Developer adds:
- Screenshots (5 min)
- Business context (2 min)
- Review and submit (1 min)

# Total time: 8 minutes
# Quality: Consistently high

Getting Started with Skills

Week 1: Create basic skill

mkdir -p .claude/skills
# Copy pr-description.md template
# Test it on a sample PR

Week 2: Add checklist validator

# Create pr-checklist-validator.md
# Run on existing PRs to validate

Week 3: Create PR-type-specific skills

# Add pr-bug-fix.md
# Add pr-feature.md
# Add pr-refactor.md

Week 4: Team rollout

# Document in README
# Share with team
# Get feedback and iterate

Using AI Tools with These Templates

Don't fill out these templates manually. Use AI to automate the process while maintaining consistency.

Claude Code Skills: Automating Template Usage

Claude Code skills give you perfect repeatability. Create a skill once, use it on every PR.

Setting Up Template Skills

Step 1: Create .claude/skills/ directory

mkdir -p .claude/skills

Step 2: Create a skill for the Complete TypeScript PR Template

Create .claude/skills/typescript-pr-complete.md:

# Complete TypeScript PR Description Generator

You are helping a developer create a comprehensive TypeScript PR description.

## Your Task

Analyze the git diff and generate a complete PR description following the 
Complete TypeScript PR Template.

## Template Structure

Generate this exact structure:

## Summary
[1-2 sentence overview of changes]

## Problem
[What bug/feature? Why does it matter?]

**Impact:**
[How many users? Business context? Severity?]

## Solution
[High-level technical approach]

**Type Safety:**
[New interfaces? Breaking type changes? Type improvements?]

**Alternatives Considered:**
[What else was tried? Why this approach?]

## Type of Change
[Check ALL that apply]
- [ ] 🐛 Bug fix (non-breaking)
- [ ] ✨ New feature (non-breaking)
- [ ] 💥 Breaking change
- [ ] 📝 Documentation
- [ ] ♻️ Refactor
- [ ] ⚡ Performance
- [ ] ✅ Tests
- [ ] 🔒 Security fix
- [ ] ♿ Accessibility improvement

## TypeScript Checklist
Analyze the diff and check items based on what you find:
- [ ] No new `any` types (or justified with comments)
- [ ] No `@ts-ignore` without explanation
- [ ] All new interfaces/types are exported from appropriate files
- [ ] Type imports use `import type` syntax
- [ ] No type assertions without runtime validation
- [ ] Discriminated unions used for state machines
- [ ] Generic types have proper constraints
- [ ] Return types are explicit for public APIs

## Testing

**Manual Testing:**
[List what should be manually tested based on changes]
- [ ] Tested happy path
- [ ] Tested error cases
- [ ] Tested edge cases

**Automated Testing:**
[Suggest what tests should be added based on changes]
- [ ] Unit tests added/updated
- [ ] Integration tests added/updated
- [ ] All tests passing locally

**Test Cases:**
[List specific test scenarios based on code changes]

## Performance
[Check items that apply based on diff analysis]
- [ ] No performance regressions
- [ ] Expensive operations are memoized
- [ ] No unnecessary re-renders
- [ ] Bundle size impact checked
- [ ] Large imports are code-split

## Security
[Check items that apply based on diff analysis]
- [ ] No sensitive data in logs
- [ ] No hardcoded secrets
- [ ] User input is validated/sanitized
- [ ] No XSS vulnerabilities
- [ ] Authentication/authorization checked

## Accessibility
[Check items if UI changes detected]
- [ ] Semantic HTML used
- [ ] ARIA labels added where needed
- [ ] Keyboard navigation works
- [ ] Focus management is correct
- [ ] Color contrast is sufficient

## Breaking Changes
[List any breaking changes detected, or state "None"]

**Migration Guide:**
[If breaking changes, provide migration steps]

## Screenshots/Videos
[If UI changes detected, request: "REQUIRED: Add before/after screenshots"]

## Deployment Notes
[Check items based on changes detected]
- [ ] No database migrations required
- [ ] No environment variable changes required
- [ ] No infrastructure changes required

**Rollback Plan:**
[Suggest rollback approach based on change type]

## Related
Fixes #[FILL IN ISSUE NUMBER]

## Reviewer Notes
[Suggest what reviewers should focus on based on the changes]

---

## Instructions

1. **Analyze the diff carefully:**
   - Identify file changes, additions, deletions
   - Look for TypeScript-specific patterns
   - Detect type changes, new interfaces, breaking changes
   - Identify performance implications
   - Flag security concerns

2. **Be specific, not generic:**
   - Instead of "fixed bug", say "fixed null reference error in UserProfile"
   - Instead of "added tests", say "added unit tests for email validation edge cases"
   - Include actual type names, file names, line numbers where relevant

3. **Check checklists intelligently:**
   - ✅ Check items that apply based on actual code changes
   - ⬜ Leave unchecked if not applicable
   - Don't check everything blindly

4. **Identify gaps:**
   - If no tests found, flag: "⚠️ No tests detected. Recommend adding tests."
   - If new `any` types found, flag: "⚠️ New `any` types at lines X, Y, Z. Justify or replace."
   - If performance concerns, flag: "⚠️ Large import detected. Consider code-splitting."

5. **Use placeholders for unknown info:**
   - If you can't determine impact: "[NEEDS AUTHOR: User impact numbers]"
   - If screenshots needed but unavailable: "REQUIRED: Add screenshots of [specific UI change]"
   - If related issue unknown: "Fixes #[FILL IN]"

6. **Maintain professional tone:**
   - Clear and concise
   - Technical but readable
   - Constructive, not critical

## Output Format

Generate the complete template with ALL sections filled out based on diff analysis.
Use markdown formatting. Be thorough but concise.

Step 3: Use the skill

# Generate PR description from your changes
git diff main | claude code --skill typescript-pr-complete

# Or save to file
git diff main | claude code --skill typescript-pr-complete > pr-description.md

Step 4: Review and enhance

The skill fills out 80% of the template. You add:

Actual user impact numbers
Screenshots
Specific testing you performed
Business context

Time saved: 15 minutes → 5 minutes

Bug Fix Template Skill

Create .claude/skills/typescript-pr-bugfix.md:

# Bug Fix PR Generator

Generate a bug fix PR description using the Bug Fix Template.

## Template

## Bug Fix: [Brief Description]

## Bug Details

**What's Broken:**
[Analyze diff to identify the bug]

**Steps to Reproduce:**
[Infer from code or state: "NEEDS AUTHOR: Add reproduction steps"]
1. 
2. 
3. 

**Expected Behavior:**
[What should happen]

**Actual Behavior:**
[What actually happens - infer from code]

**Impact:**
- Severity: [Analyze code to estimate: Critical/High/Medium/Low]
- Affected Users: [NEEDS AUTHOR: Provide number or percentage]
- Frequency: [Infer: always/often/sometimes/rare]
- Support Tickets: [NEEDS AUTHOR: Provide count if available]

## Root Cause

[Analyze diff to explain why this bug exists]

## Solution

[Explain the fix based on code changes]

**Code Changes:**
[List files modified and what changed in each]

## Testing

**Reproduction:**
- [ ] Reproduced bug before fix
- [ ] Verified fix resolves issue
- [ ] Cannot reproduce bug after fix

**Regression Testing:**
- [ ] Related features still work
- [ ] Edge cases covered
- [ ] Added regression test

**Test Cases:**
[Based on code analysis, suggest specific test cases]

## Type Safety
[Check items based on diff]
- [ ] No new `any` types
- [ ] Null/undefined handling improved
- [ ] Type guards added where needed

## Risks

**Rollback Plan:**
[Suggest rollback strategy based on change scope]

**Monitoring:**
[Suggest what metrics to watch]

Fixes #[FILL IN]

## Instructions

1. Identify the bug from the diff
2. Explain root cause clearly
3. Describe the fix
4. Suggest comprehensive test cases
5. Flag if reproduction steps or impact metrics needed from author

Usage:

git diff main | claude code --skill typescript-pr-bugfix

Feature Template Skill

Create .claude/skills/typescript-pr-feature.md:

# Feature PR Generator

Generate a feature PR description using the New Feature Template.

## Template

## Feature: [Feature Name from code analysis]

## User Story

**As a** [Infer user type from feature]
**I want** [Infer goal from code]
**So that** [Infer benefit]

## Business Value

**Why This Feature:**
[Analyze code to understand purpose, or state: "NEEDS AUTHOR: Business justification"]

**Success Metrics:**
[NEEDS AUTHOR: Add metrics]
- Metric 1: 
- Metric 2: 

## Implementation

**User Flow:**
[Infer from UI components and logic]
1. 
2. 
3. 

**Technical Approach:**
[Describe architecture from code analysis]

**TypeScript Patterns Used:**
[Check what's actually in the code]
- [ ] Discriminated unions for state
- [ ] Generic components
- [ ] Type-safe API calls
- [ ] Proper error types

## API Changes

**New Endpoints:**
[List if backend changes detected]

**New Types:**

typescript
[Extract and list new interfaces/types from diff]


**Breaking Changes:**
[Flag any breaking changes in API or types]

## UI/UX Changes

**Screenshots:**
[If UI changes detected: "REQUIRED: Add before/after screenshots"]

**Responsive Design:**
- [ ] Mobile [needs testing]
- [ ] Tablet [needs testing]
- [ ] Desktop [needs testing]

**Accessibility:**
[Check based on code]
- [ ] Keyboard navigation works
- [ ] Screen reader compatible
- [ ] ARIA labels added

## Testing

**Feature Testing:**
[Suggest test cases based on feature logic]
- [ ] Happy path works
- [ ] Error handling works
- [ ] Edge cases handled

**Integration Testing:**
[Suggest integration tests needed]

**Performance:**
[Flag if performance testing needed]

## Documentation

- [ ] User documentation needed
- [ ] API documentation needed
- [ ] Code comments added
- [ ] README updated

## Rollout Plan

**Feature Flag:**
[Suggest feature flag name: `ENABLE_[FEATURE_NAME]`]

**Phased Rollout:**
- [ ] Internal testing
- [ ] Beta users
- [ ] Gradual rollout

Implements #[FILL IN]

Checklist Validator Skill

Create .claude/skills/typescript-pr-checklist.md:

# PR Checklist Validator

Validate PR changes against all TypeScript checklists.

## Your Task

Analyze the git diff and validate against EVERY checklist item.

## Checklists to Validate

### Type Safety Checklist

**Check each item:**
- No explicit `any` types (or justified)
- No `@ts-ignore` comments (or explained)
- Type imports use `import type`
- Null checks before access
- Type assertions justified
- Generic types have proper constraints
- Return types explicit for public APIs
- Discriminated unions for state machines

### Performance Checklist

**Check each item:**
- No unnecessary re-renders
- useMemo for expensive calculations
- useCallback for callbacks
- React.memo for expensive components
- Code splitting implemented
- No large library imports (tree-shaking)
- Images optimized

### Accessibility Checklist

**Check each item:**
- Semantic HTML used
- ARIA labels where needed
- Keyboard navigation works
- Focus management correct
- Color contrast sufficient
- Alt text for images
- Form labels associated

### Security Checklist

**Check each item:**
- No hardcoded secrets
- Input validated/sanitized
- No XSS vulnerabilities
- No sensitive data in logs
- Authentication/authorization checked
- Cookies are Secure and HttpOnly

## Output Format

For each checklist:

### [Checklist Name] - [✅ PASS | ⚠️ WARNINGS | ❌ FAIL]

**Status:**
- ✅ All checks pass
- ⚠️ [Count] warnings found
- ❌ [Count] critical issues found

**Issues:**

🔴 **Critical Issues (must fix before merge):**
- `File.tsx:45` - Hardcoded API key
- `Component.tsx:67` - XSS vulnerability

🟡 **Warnings (should fix):**
- `UserProfile.tsx:23` - Missing null check
- `Dashboard.tsx:89` - Expensive calculation not memoized

🟢 **Suggestions (nice to have):**
- `api.ts:12` - Could use `import type`

**Summary:**
[Overall assessment and priority recommendations]

## Instructions

1. Scan diff for each checklist category
2. Flag violations with file:line references
3. Provide specific fix suggestions
4. Prioritize: Critical → Warning → Suggestion
5. Be thorough but constructive

Usage:

# Validate your PR
git diff main | claude code --skill typescript-pr-checklist

# Save validation report
git diff main | claude code --skill typescript-pr-checklist > checklist-validation.md

GitHub Copilot Integration

Copilot works great for quick template filling in the GitHub UI.

In the GitHub PR description field:

Type # to trigger Copilot
Select "Generate PR description"
Copilot analyzes your diff and suggests description

Or use Copilot Chat in VS Code:

@workspace Generate a TypeScript PR description for my staged changes.

Use this template structure:
- Summary
- Problem (with business impact)
- Solution (with TypeScript considerations)
- Testing (manual + automated)
- TypeScript Checklist
- Performance impact
- Security review
- Screenshots (if UI changes)

Be specific and thorough.

Copilot strengths:

✅ Fast (built into IDE/GitHub)
✅ Understands workspace context
✅ Good for small PRs

Copilot limitations:

❌ Less customizable
❌ Can't enforce team-specific templates
❌ Inconsistent output
❌ Not version controlled

Best for: Quick bug fixes, small features under 200 lines

The Hybrid Workflow (Best Practice)

Combine skills + manual input + AI polish:

# Step 1: Generate base description (2 minutes)
git diff main | claude code --skill typescript-pr-complete > pr.md

# Step 2: Validate against checklists (1 minute)
git diff main | claude code --skill typescript-pr-checklist >> pr.md

# Step 3: Add your context (3 minutes)
# Edit pr.md to add:
# - Actual user impact numbers
# - Screenshots
# - Specific testing details
# - Business justification

# Step 4: Polish (1 minute)
# Paste pr.md into Claude:
# "Make this more concise and remove any redundancy"

# Step 5: Create PR (1 minute)
gh pr create --title "Fix: User profile crash on null email" --body-file pr.md

# Total time: 8 minutes (vs 20 minutes manual)

Complete Skills Library

Build a collection for your team:

.claude/skills/
├── typescript-pr-complete.md      # Full template
├── typescript-pr-bugfix.md        # Bug fix template
├── typescript-pr-feature.md       # Feature template
├── typescript-pr-refactor.md      # Refactoring template
├── typescript-pr-dependency.md    # Dependency update
├── typescript-pr-performance.md   # Performance optimization
├── typescript-pr-security.md      # Security fix
├── typescript-pr-checklist.md     # Validate all checklists
├── typescript-type-safety.md      # Deep type safety check
└── typescript-breaking-changes.md # Breaking change detector

Team README section:

## PR Descriptions

We use Claude Code skills for consistent, high-quality PR descriptions.

### Quick Start

bash

Complete PR description

git diff main | claude code --skill typescript-pr-complete

Validate checklists

git diff main | claude code --skill typescript-pr-checklist

Bug fix specific

git diff main | claude code --skill typescript-pr-bugfix


### Available Skills

- `typescript-pr-complete` - Full template with all sections
- `typescript-pr-bugfix` - Bug fix template
- `typescript-pr-feature` - New feature template
- `typescript-pr-refactor` - Refactoring template
- `typescript-pr-checklist` - Validate against all checklists
- `typescript-type-safety` - Deep type safety analysis

See `.claude/skills/` for details.

Automating with GitHub Actions

Run skills in CI to enforce standards:

# .github/workflows/pr-validation.yml
name: PR Quality Check

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0

      - name: Setup Node
        uses: actions/setup-node@v3

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

      - name: Generate diff
        run: |
          git diff origin/${{ github.base_ref }}...HEAD > /tmp/pr.diff

      - name: Validate checklist
        id: validate
        run: |
          claude code --skill typescript-pr-checklist \
            --input /tmp/pr.diff > /tmp/validation.md

      - name: Check for critical issues
        run: |
          if grep -q "🔴.*Critical" /tmp/validation.md; then
            echo "Critical issues found!"
            cat /tmp/validation.md
            exit 1
          fi

      - name: Post validation as comment
        if: always()
        uses: actions/github-script@v6
        with:
          script: |
            const fs = require('fs');
            const validation = fs.readFileSync('/tmp/validation.md', 'utf8');

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: `## 🤖 Automated PR Validation\n\n${validation}`
            });

Result: Every PR gets automatically validated against all checklists.

Real-World Example

Before AI tools:

Developer writes PR manually:
- Fills out template: 15 minutes
- Forgets to check type safety items
- Misses performance implications
- Generic testing description
- Inconsistent with other PRs

Reviewer asks questions:
- What's the impact?
- Why this approach?
- Where are the tests?

Back and forth: 2-3 days

After AI tools (Claude Code skills):

# Developer runs (30 seconds):
git diff main | claude code --skill typescript-pr-complete > pr.md
git diff main | claude code --skill typescript-pr-checklist >> pr.md

# Reviews generated description (2 minutes)
# Adds screenshots, numbers, context (3 minutes)
# Creates PR (1 minute)

Total: 7 minutes
Quality: Consistently high
All checklist items validated
No back-and-forth needed

Reviewer approves: Same day

Comparison: Manual vs AI-Assisted

Aspect	Manual Template	With Skills
Time to create	15-20 min	5-8 min
Consistency	Varies by person	Identical every time
Completeness	Often missing items	All sections filled
Quality	Depends on experience	Consistently high
Type safety check	Manual (often skipped)	Automatic
Checklist validation	Manual (often incomplete)	Automatic
Team onboarding	Slow (learn template)	Fast (run command)
Version control	Template only	Template + automation

ROI of setting up skills:

Setup time: 2 hours (create skills)
Time saved per PR: 10-15 minutes
Break-even: ~10 PRs
Annual savings: ~50 hours per developer

Getting Started This Week

Monday: Create basic skill

mkdir -p .claude/skills
# Copy typescript-pr-complete.md skill template
# Test on a sample PR

Tuesday: Test and refine

# Run on 3 different PR types
# Adjust skill based on output quality

Wednesday: Add checklist validator

# Create typescript-pr-checklist.md
# Test validation on existing PRs

Thursday: Document for team

# Add section to README
# Create quick reference guide

Friday: Team rollout

# Demo to team
# Get feedback
# Iterate based on usage

Next week: 100% adoption, consistently great PRs.

Automation Ideas

Pre-commit Checklist

Use Husky to enforce checklist:

// package.json
{
  "husky": {
    "hooks": {
      "pre-commit": "npm run checklist"
    }
  },
  "scripts": {
    "checklist": "npm run lint && npm run type-check && npm test"
  }
}

Danger.js for PR Validation

// dangerfile.js
import { danger, warn, fail } from 'danger';

// Check PR size
const bigPR = danger.github.pr.additions + danger.github.pr.deletions > 500;
if (bigPR) {
  warn('This PR is quite large. Consider splitting it.');
}

// Require tests for code changes
const hasCodeChanges = danger.git.modified_files.some(f => 
  f.endsWith('.ts') || f.endsWith('.tsx')
);
const hasTestChanges = danger.git.modified_files.some(f => 
  f.includes('.test.')
);

if (hasCodeChanges && !hasTestChanges) {
  warn('No tests added. Consider adding tests for your changes.');
}

// Check for console.log
const consoleLogFound = danger.git.modified_files.some(file => {
  const content = danger.git.fileMatch(file).includes('console.log');
  return content;
});

if (consoleLogFound) {
  fail('console.log found. Remove debug code before merging.');
}

GitHub Actions Checklist

# .github/workflows/pr-checklist.yml
name: PR Checklist

on: [pull_request]

jobs:
  checklist:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Check for console.log
        run: |
          if grep -r "console.log" src/; then
            echo "console.log found in source code"
            exit 1
          fi

      - name: Check for TODO comments
        run: |
          if grep -r "TODO" src/; then
            echo "TODO comments found. Create issues instead."
            exit 1
          fi

      - name: Check bundle size
        run: npm run build && npm run size-check

Customizing for Your Team

Start Simple

Begin with the basic template, then add sections your team needs.

Team-Specific Sections

For e-commerce:

## Business Impact
- [ ] Revenue impact estimated
- [ ] Conversion tracking added
- [ ] Analytics events implemented

For healthcare:

## Compliance
- [ ] HIPAA compliance verified
- [ ] PHI handling reviewed
- [ ] Audit logging implemented

For B2B SaaS:

## Customer Impact
- [ ] Customer-facing changes documented
- [ ] Support team notified
- [ ] Release notes drafted

Progressive Enhancement

Week 1: Basic template
Week 2: Add type safety checklist
Week 3: Add performance checklist
Week 4: Add accessibility checklist
Week 5: Refine based on feedback