Pre-Push Validation Skill

Ensures critical documentation files are updated before pushing changes to the repository.

What This Skill Does

Automatic validation before git push - The pre-push hook checks that documentation is current:

1. CHANGELOG.md - Must document your changes
2. README.md - Must reflect any project structure changes
3. CLAUDE.md - Must reflect any AI instruction changes

How It Works

Pre-Push Hook

The hook .claude/hooks/pre-push-validation.sh runs automatically before git push operations:

Validation Logic:

• ✅ Checks commit dates - Documentation must be updated since oldest unpushed commit
• ✅ Detects uncommitted changes - Warns if docs have uncommitted changes
• ✅ Validates file existence - Ensures all critical files exist
• ❌ Blocks push - If documentation is outdated relative to code changes

Example Output:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 PRE-PUSH VALIDATION
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📊 Commits to push: 3
🌿 Branch: main → origin/main

📝 Checking documentation files...

✓ CLAUDE.md: Updated 2025-12-10
✓ README.md: Updated 2025-12-10
❌ CHANGELOG.md: Not updated since 2025-12-09

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ VALIDATION FAILED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Please update the following files before pushing:
  • CHANGELOG.md

💡 Tips:
  1. Update CHANGELOG.md with your changes
  2. Update README.md if project structure changed
  3. Update CLAUDE.md if AI instructions changed
  4. Commit your documentation updates
  5. Push again

When to Update Each File

CHANGELOG.md (Required for ALL commits)

Always update when:

• Adding new features
• Fixing bugs
• Refactoring code
• Changing dependencies
• Modifying configuration
• Updating documentation

Format:

## [YYYY-MM-DD<letter>] - Brief Title

### Added/Changed/Fixed/Removed
- Detailed description of changes
- Impact and rationale
- Technical details

### Files Modified
1. `path/to/file.js` - Description
2. `path/to/file.css` - Description

**Total: X files modified**

README.md (Update when project changes)

Update when:

• Adding new blocks or components
• Changing project structure
• Adding new npm scripts
• Modifying development workflow
• Adding new dependencies
• Changing infrastructure

CLAUDE.md (Update when AI instructions change)

Update when:

• Adding new coding patterns
• Changing project conventions
• Adding new skills or commands
• Modifying development requirements
• Updating architecture decisions
• Changing configuration patterns

Using the Skill

Before Every Push

1. Review your commits:

   git log origin/main..HEAD --oneline
   

2. Update documentation:

   • CHANGELOG.md - Document all changes
   • README.md - Update if structure changed
   • CLAUDE.md - Update if AI instructions changed

3. Commit all changes (including user edits):

   git add .
   git commit -m "docs: Update documentation for [feature/fix]"
   

4. Push with confidence:

   git push
   

   The hook will validate and either allow or block the push.

Bypassing Validation (NOT RECOMMENDED)

If you absolutely must push without updating documentation:

git push --no-verify

⚠️ Warning: Only use this for:

• Emergency hotfixes
• Work-in-progress branches
• Documentation-only changes

Never use --no-verify for main/production branches.

Hook Installation

The hook is automatically available in Claude Code projects. To verify:

ls -la .claude/hooks/pre-push-validation.sh

Should show executable permissions: -rwxr-xr-x

If not executable:

chmod +x .claude/hooks/pre-push-validation.sh

Workflow Integration

Recommended Git Workflow

1. Make code changes - Implement features/fixes
2. Commit code - git commit -m "feat: Add new feature"
3. Update documentation - CHANGELOG.md, README.md, CLAUDE.md as needed
4. Commit documentation - git commit -m "docs: Document new feature"
5. Push - git push (hook validates automatically)

Multi-Commit Sessions

If you have multiple commits:

# Commits in current session
git log origin/main..HEAD --oneline

# The hook checks documentation is newer than ALL unpushed commits

Best Practice: Update documentation as you go, not at the end.

Troubleshooting

"VALIDATION FAILED" Error

Problem: Documentation files are outdated compared to code commits.

Solution:

1. Check which files need updating (listed in error message)
2. Update those files with your changes
3. Commit all changes (including user edits): git add . && git commit -m "docs: Update documentation"
4. Try pushing again: git push

"Has uncommitted changes" Warning

Problem: Documentation file has uncommitted changes.

Solution:

1. Review changes: git diff [file]
2. Stage all changes: git add .
3. Commit changes: git commit -m "docs: Update [file]"
4. Push: git push

Hook Not Running

Problem: Push succeeds without validation.

Possible causes:

1. Hook file not executable - Run: chmod +x .claude/hooks/pre-push-validation.sh
2. Not in git repository - Verify: git rev-parse --is-inside-work-tree
3. New branch without upstream - Expected behavior, validation skipped

Benefits

1. Consistent Documentation - Forces documentation updates before push
2. Better Change History - CHANGELOG.md always current
3. Team Alignment - Everyone knows what changed and why
4. AI Assistant Context - CLAUDE.md stays current with project changes
5. Prevents "I forgot to document" - Automated validation reminder

Configuration

The hook is configured via critical files array in the script:

CRITICAL_FILES=(
    "CLAUDE.md"
    "README.md"
    "CHANGELOG.md"
)

To add more files, edit .claude/hooks/pre-push-validation.sh and add to the array.

See Also

• Hook configuration: .claude/hooks/CONFIG.md
• Git hooks documentation: .claude/hooks/README.md
• CHANGELOG format: CHANGELOG.md (see existing entries)
• README structure: README.md (top-level sections)
• CLAUDE.md patterns: CLAUDE.md (configuration patterns section)