gh-bradleyboehmke-brads-marketplace-git-workflow/commands/pre-commit-check.md

description

description
Run comprehensive pre-commit checks with project-aware validation

Pre-Commit Check

You are running pre-commit quality checks before allowing a commit or push.

Command Parameters

Scope Parameter:

• --scope=commit (default) - Check staged changes and commit message
• --scope=push - Check all commits on branch before push

Auto-Fix Parameter:

• --auto-fix (default: false) - Attempt to fix issues automatically

Format Parameter:

• --format=console (default) - Display results in console
• --format=markdown - Generate markdown report

Output Parameter:

• --output=<path> - Custom report path (only with --format=markdown)

Usage Examples:

/git-workflow:pre-commit-check                    # Check staged changes
/git-workflow:pre-commit-check --scope=push       # Check before push
/git-workflow:pre-commit-check --auto-fix         # Fix issues automatically
/git-workflow:pre-commit-check --format=markdown  # Generate report

Objective

Run comprehensive quality checks based on:

1. Project type detection (Python, Data Science, Plugin Marketplace)
2. Pre-commit framework status (installed or not)
3. Universal checks (always run)
4. Project-specific checks (context-aware)

Activated Agent

Activate: git-workflow-specialist agent

Activated Skills

• commit-message-standards - Validate commit format
• github-workflow-patterns - Branch naming, pre-commit best practices
• pre-commit-quality-standards - Project type detection, quality checks, pre-commit configs

Check Process

Step 0: Check Git Status and Handle Unstaged Changes

IMPORTANT: Before running any checks, detect what files need to be checked.

# Check for staged changes
git diff --cached --name-only

# Check for unstaged changes
git diff --name-only

# Check for untracked files
git ls-files --others --exclude-standard

Determine the state:

State 1: Files already staged

If there are staged files, proceed to check them:

Found staged changes:
  - src/api/export.py
  - tests/test_export.py

Running quality checks on 2 staged files...

Continue to Step 1 (Detect Project Type).

State 2: No staged files, but unstaged/untracked files exist

If no files are staged but there are modified or new files, offer interactive options:

No staged changes found.

Detected modified/new files:
  - src/api/export.py (modified)
  - src/utils/validation.py (modified)
  - tests/test_export.py (new file)

What would you like to do?
1. ✓ Check all modified/new files (recommended)
2. ✏️  Stage specific files first, then check (git add -p)
3. ⏭️  Cancel - nothing to check

If user chooses Option 1 (Check all files):

• Temporarily stage all modified/new files for checking purposes
• Run all quality checks
• After checks complete, unstage them if they weren't originally staged
• Report: "Files checked but not staged. Run /git-workflow:draft-commit to stage and commit."

If user chooses Option 2 (Selective staging):

• Pause and instruct user to run git add -p or git add <specific-files>
• After staging, re-run pre-commit-check
• Continue to Step 1

If user chooses Option 3 (Cancel):

• Exit with message: "No files to check. Make changes first."

State 3: No changes at all

If no staged, unstaged, or untracked files:

No changes detected.

Current state:
- Working directory clean
- No files staged for commit

Make some changes first, then run /git-workflow:pre-commit-check

Exit gracefully.

---

Step 1: Detect Project Type

Use the pre-commit-quality-standards skill to detect project type(s).

Examine repository for indicators of:

• Python projects
• Data Science projects
• Plugin Marketplace projects
• Mixed projects (e.g., Python + Data Science)

Step 2: Check Pre-Commit Status

# Check if pre-commit is configured
test -f .pre-commit-config.yaml && echo "configured" || echo "not configured"

# If configured, check if installed
pre-commit --version 2>/dev/null && echo "installed" || echo "not installed"

Three scenarios:

1. Configured + Installed: Run pre-commit hooks
2. Configured but not installed: Warn and suggest pre-commit install
3. Not configured: Run Claude-native checks + offer to generate config

Step 3: Universal Checks (Always Run)

Run all universal checks from the pre-commit-quality-standards skill:

1. Commit Message Validation (if --scope=commit) - Use commit-message-standards skill
2. Branch Naming Validation - Use github-workflow-patterns skill
3. Secret Detection - Use patterns from pre-commit-quality-standards
4. Large File Detection - Thresholds defined in pre-commit-quality-standards
5. Merge Conflict Markers - Check for <<<<<<<, =======, >>>>>>>
6. Trailing Whitespace - Use git diff --staged --check
7. Direct Commits to Protected Branches - Fail if on main/master

Step 4: Run Pre-Commit Hooks (If Configured)

If .pre-commit-config.yaml exists and pre-commit is installed:

# For commit scope - run on staged files only
pre-commit run

# For push scope - run on all files
pre-commit run --all-files

Parse output:

• Extract failed hooks
• Report specific file/line issues
• If --auto-fix: re-run with auto-fixing enabled

If pre-commit configured but NOT installed:

⚠️ **Pre-commit configured but not installed**

Your project has `.pre-commit-config.yaml` but pre-commit is not installed.

To install:
\```bash
pip install pre-commit
pre-commit install
\```

Continuing with Claude-native checks...

Step 5: Project-Specific Claude-Native Checks

If pre-commit is NOT configured, run project-specific checks from the pre-commit-quality-standards skill based on detected project type(s):

• Python Projects: Syntax validation, debug statements, print statements, hardcoded paths
• Plugin Marketplace Projects: JSON validation, markdown linting, plugin structure
• Data Science Projects: Notebook size, outputs in notebooks, large data files

See pre-commit-quality-standards skill for complete check definitions.

Step 6: Generate Recommendations

If pre-commit is NOT configured, use the pre-commit-quality-standards skill to:

1. Select appropriate pre-commit config template based on detected project type
2. Offer to create .pre-commit-config.yaml file
3. Provide installation instructions

Output Format

When All Checks Pass

## Pre-Commit Check Results

**Scope**: commit
**Project Type**: Python
**Pre-commit**: Configured ✅

---

**All Checks Passed** ✅

- ✅ Branch naming follows convention (feature/add-export)
- ✅ Not on protected branch
- ✅ No secrets detected
- ✅ No large files
- ✅ No merge conflict markers
- ✅ Pre-commit hooks passed (black, ruff, mypy)

**Checked Files**:
- src/api/export.py
- src/utils/validation.py
- tests/test_export.py

**Summary**: Quality checks passed! Files are ready to commit.

**Next Step**: Run /git-workflow:draft-commit to stage and commit these changes.

When Checks Fail

## Pre-Commit Check Results

**Scope**: commit
**Project Type**: Python
**Pre-commit**: Not configured ⚠️

---

**Status**: ❌ FAIL

**Blocking Issues**:

1. ❌ **Commit message invalid**
   - Current: "fix bug"
   - Problem: Too vague, missing scope
   - Fix: Use format `fix(<scope>): specific description`
   - Run: `/git-workflow:draft-commit` to generate proper message

2. ❌ **Potential secret detected**
   - File: `src/config.py`
   - Line 15: `api_key = "sk-1234567890abcdef"`
   - Action: Remove hardcoded secret, use environment variable

3. ❌ **Debug statement found**
   - File: `src/api/users.py`
   - Line 42: `import pdb; pdb.set_trace()`
   - Action: Remove debug statement

**Warnings**:

1. ⚠️ **Large file staged**
   - File: `data/export.csv` (15.2 MB)
   - Consider: Use Git LFS or exclude from repository

2. ⚠️ **Print statements found**
   - File: `src/api/export.py`
   - Lines: 23, 45, 67
   - Consider: Use logging instead of print()

**Summary**: 3 errors, 2 warnings - Cannot commit

---

## Recommendations

**Install pre-commit hooks** for automated checking:

\```bash
pip install pre-commit
\```

Create `.pre-commit-config.yaml` using the template from **`pre-commit-quality-standards`** skill for your project type:
- Python projects: Use Python template (black, ruff, mypy, detect-secrets)
- Plugin Marketplace: Use Marketplace template (markdownlint, YAML/JSON validation)
- Data Science: Use Data Science template (nbQA, nbstripout, black, ruff)

Then run:
\```bash
pre-commit install
\```

Would you like me to create this file for you? (yes/no)

When Pre-Commit Configured But Not Installed

## Pre-Commit Check Results

**Scope**: commit
**Project Type**: Python
**Pre-commit**: Configured but not installed ⚠️

---

⚠️ **Pre-commit hooks are configured but not installed**

Your project has `.pre-commit-config.yaml` with these hooks:
- black (formatting)
- ruff (linting)
- mypy (type checking)
- detect-secrets

**To install**:
\```bash
pip install pre-commit
pre-commit install
\```

**Continuing with Claude-native checks...**

---

[Rest of check results...]

Auto-Fix Workflow

When --auto-fix is enabled:

Step 1: Attempt Automatic Fixes

If pre-commit configured:

# Many pre-commit hooks support auto-fixing
pre-commit run --all-files

Hooks like black, prettier, trailing-whitespace will fix issues automatically.

If using Claude-native checks:

• Fix trailing whitespace
• Remove debug statements (if user confirms)
• Format basic syntax issues

Step 2: Report What Was Fixed

## Auto-Fix Results

**Fixes Applied** ✅:

1. ✅ **Formatted code with black**
   - Files: `src/api/users.py`, `src/api/export.py`
   - Changes: Line length normalized, imports sorted

2. ✅ **Removed trailing whitespace**
   - Files: 5 files affected

**Issues Requiring Manual Fix** ❌:

1. ❌ **Potential secret detected**
   - File: `src/config.py`
   - Cannot auto-fix: Requires manual review and environment variable setup

2. ❌ **Commit message invalid**
   - Run: `/git-workflow:draft-commit` to generate proper message

**Next Steps**:
1. Review auto-applied fixes: `git diff`
2. Fix remaining issues manually
3. Re-run checks: `/git-workflow:pre-commit-check`

Push-Scope Checks

When --scope=push:

Additional Checks:

1. Validate All Commits on Branch:

# Get all commits on current branch
git log main..HEAD --format="%H %s"

# Validate each commit message
for commit in $(git log main..HEAD --format="%H"); do
  git log -1 $commit --format="%s%n%n%b" | validate
done

2. Check for Divergence:

# Check if branch is behind main
git fetch origin
git rev-list HEAD..origin/main --count

⚠️ Warn if branch is behind main (suggest rebase/merge)

3. Verify No Direct Commits to Main: Already covered in universal checks, but more critical for push.

4. Check for Force Push Protection:

# Check if this would be a force push
git push --dry-run --force 2>&1 | grep "rejected"

❌ Fail if force push to protected branch

Important Notes

• Non-blocking by default: Checks report issues but don't prevent commits (user decides)
• Can be integrated: Results can drive actual git hooks via exit codes
• Progressive enhancement: Works without pre-commit, better with it
• Project-aware: Adapts checks to project type
• Educational: Explains WHY issues are problems and HOW to fix

Exit codes (for git hook integration):

• 0 - All checks passed
• 1 - Blocking issues found
• 2 - Warnings only (non-blocking)

---

Remember: This command is flexible - it works standalone, as a pre-commit hook, or as a quality gate before pushing.