Initial commit

commands/commit-best-practices/check-pre-commit.md

@@ -0,0 +1,214 @@
+# Operation: Pre-Commit Validation
+
+Validate repository state and changes before committing to ensure quality standards.
+
+## Parameters from $ARGUMENTS
+
+- **quick** (optional): `true` for fast checks only, `false` for full validation (default: false)
+
+Parse as: `check-pre-commit quick:true` or `check-pre-commit`
+
+## Pre-Commit Validation Workflow
+
+### Step 1: Repository State Check
+
+Verify git repository is valid and has changes:
+
+```bash
+# Check if git repository
+if ! git rev-parse --git-dir >/dev/null 2>&1; then
+    ERROR: "Not a git repository"
+    exit 1
+fi
+
+# Check for changes to commit
+git status --short
+```
+
+If no changes, inform user: "Working tree clean. No changes to commit."
+
+### Step 2: Run Pre-Commit Checks Script
+
+Execute comprehensive validation:
+
+```bash
+cd $(git rev-parse --show-toplevel)
+./.claude/commands/commit-best-practices/.scripts/pre-commit-check.sh quick:${quick:-false}
+```
+
+The script returns JSON:
+```json
+{
+  "status": "pass|fail",
+  "checks": {
+    "tests": {"status": "pass|fail|skip", "message": "..."},
+    "lint": {"status": "pass|fail|skip", "message": "..."},
+    "debug_code": {"status": "pass|fail", "count": 0, "locations": []},
+    "todos": {"status": "pass|warn", "count": 0, "locations": []},
+    "merge_markers": {"status": "pass|fail", "count": 0, "locations": []}
+  }
+}
+```
+
+### Step 3: Parse Results
+
+**If status = "pass"**:
+```
+✅ Pre-commit validation passed!
+
+All checks completed successfully:
+  ✅ Tests: passed
+  ✅ Lint: passed
+  ✅ Debug code: none found
+  ✅ TODOs: none in committed code
+  ✅ Merge markers: none found
+
+Safe to commit. Proceed with: /commit
+```
+
+**If status = "fail"**:
+```
+❌ Pre-commit validation failed!
+
+Issues found:
+  ❌ Tests: 2 failing
+     - test/auth.test.js: OAuth flow test
+     - test/api.test.js: null pointer test
+
+  ❌ Debug code: 3 instances found
+     - src/auth.js:42: console.log(user)
+     - src/api.js:18: debugger statement
+     - src/utils.js:91: print(response)
+
+  ❌ TODOs: 1 found in staged code
+     - src/auth.js:56: TODO: refactor this
+
+Cannot commit until issues are resolved.
+
+Actions to take:
+1. Fix failing tests
+2. Remove debug statements (console.log, debugger, print)
+3. Resolve or remove TODOs in staged files
+4. Run: /commit-best-practices check-pre-commit (to re-validate)
+```
+
+### Step 4: Provide Guidance
+
+Based on failures, provide specific remediation:
+
+**Tests Failing:**
+```
+To fix tests:
+1. Run tests locally: npm test (or pytest, cargo test, etc.)
+2. Review failures and fix issues
+3. Verify all tests pass
+4. Re-run validation
+```
+
+**Debug Code Found:**
+```
+To remove debug code:
+1. Search for: console.log, debugger, print(, pdb.
+2. Remove or comment out debug statements
+3. Consider using proper logging instead
+4. Re-stage files: git add <file>
+```
+
+**TODOs in Committed Code:**
+```
+TODOs found in staged code:
+1. Either: Fix the TODO items now
+2. Or: Unstage files with TODOs (git reset HEAD <file>)
+3. Or: Remove TODO comments temporarily
+
+Best practice: Don't commit TODOs to main/master
+```
+
+**Merge Markers Found:**
+```
+Merge conflict markers detected:
+- <<<<<<<
+- =======
+- >>>>>>>
+
+Actions:
+1. Resolve merge conflicts completely
+2. Remove all conflict markers
+3. Test merged code
+4. Re-stage resolved files
+```
+
+## Output Format
+
+Provide clear, actionable feedback:
+
+```
+Pre-Commit Validation Report
+============================
+
+Status: [PASS|FAIL]
+
+Checks Performed:
+  [✅|❌] Tests: [result]
+  [✅|❌] Lint: [result]
+  [✅|❌] Debug Code: [result]
+  [✅|❌] TODOs: [result]
+  [✅|❌] Merge Markers: [result]
+
+[If FAIL: Detailed issue list with file locations]
+
+[If FAIL: Remediation steps]
+
+[If PASS: "Safe to commit" confirmation]
+```
+
+## Quick Mode
+
+If `quick:true`:
+- Skip test execution (assume tests run in CI)
+- Skip lint execution (assume linter runs separately)
+- Only check: debug code, TODOs, merge markers
+- Much faster (~1 second vs ~30 seconds)
+
+Use quick mode for rapid iteration during development.
+
+## Error Handling
+
+**Not a git repository:**
+```
+ERROR: Not a git repository
+Run: git init (to initialize)
+Or: cd to correct directory
+```
+
+**No changes to validate:**
+```
+INFO: Working tree clean
+No changes staged for commit
+Use: git add <files> (to stage changes)
+```
+
+**Script execution error:**
+```
+ERROR: Pre-commit check script failed
+Check: .claude/commands/commit-best-practices/.scripts/pre-commit-check.sh exists
+Verify: Script is executable (chmod +x)
+```
+
+## Integration with Agent
+
+When user says "commit my changes":
+1. Agent MUST run this check FIRST
+2. If check fails, BLOCK commit and provide guidance
+3. If check passes, proceed with commit workflow
+4. Never allow commit with failing validation (unless user explicitly forces)
+
+## Best Practices Enforced
+
+1. **Tests must pass** - Failing tests = broken code
+2. **No debug code** - console.log, debugger not for production
+3. **No committed TODOs** - Fix or remove before commit
+4. **No merge markers** - Resolve conflicts completely
+5. **Lint compliance** - Follow project style
+
+These checks ensure high code quality and prevent common mistakes.