/epcc-commit

name: epcc-commit
description: Commit phase of EPCC workflow - finalize with confidence
version: 3.1.0
argument-hint: "[commit-message] [--amend|--squash]"

EPCC Commit Command

You are in the **COMMIT** phase of the Explore-Plan-Code-Commit workflow. Finalize implementation with quality validation, git commit, and optional PR creation.

**Opening Principle**: High-quality commits capture atomic units of work with clear intent, enabling confident deployment through systematic validation and reversibility.

@../docs/EPCC_BEST_PRACTICES.md - Comprehensive guide covering git workflows, quality gates, and deployment patterns

Commit Target

$ARGUMENTS

🎯 Commit Philosophy

**Core Principle**: Validate quality → Git commit with safety → Document completion. Execute autonomously, only ask when genuinely blocked.

Commit Modes

Parse mode from arguments:

• **Default**: Standard commit (quality checks → commit → document)
• **`--amend`**: Amend previous commit (use carefully - verify authorship first)
• **`--squash`**: Squash commits (interactive rebase preparation)

Execution-First Pattern (Critical)

**This phase is heavily AUTOMATED. Execute with safety checks, don't ask permission for standard operations.**

Auto-Execute Pattern

1. **Run quality checks** → Tests, coverage, linting, type checking, security 2. **Auto-fix** → Formatting, linting, simple bugs 3. **Re-run** → Verify fixes worked 4. **Stage changes** → Review diff, stage relevant files only 5. **Commit** → Generate message, create commit with safety checks 6. **Document** → Generate EPCC_COMMIT.md 7. **Ask only if blocked** → Quality gates failed after fixes, or user input needed

When to Ask vs Execute

**✅ Ask when:**

• Critical/High security vulnerabilities can't be auto-fixed
• Tests failing after multiple fix attempts (can't resolve)
• Breaking changes detected (user needs to approve)
• PR creation (user decides whether to push/create PR)
• Commit message unclear from context (what to describe?)

**❌ Don't ask when:**

• Quality checks failed with clear errors (auto-fix)
• Linting/formatting issues (run auto-fix tools)
• Coverage slightly below target (document in commit)
• Standard git operations (execute with safety checks)
• Generating commit message (draft from EPCC_PLAN.md + changes)

Quality Validation Workflow

Phase 1: Run Quality Checks

Execute checks from EPCC_EXPLORE.md (or sensible defaults if greenfield):

# Tests
[test-command]  # pytest, npm test, cargo test, etc.

# Coverage
[coverage-command]  # pytest --cov, npm run coverage, etc.

# Linting
[linter-command]  # ruff check, eslint, clippy, etc.

# Type checking
[type-check-command]  # mypy, tsc, etc.

# Security scan (if security-reviewer ran in CODE phase)
# Results already in EPCC_CODE.md

**Auto-fix pattern**: Run → fix issues → re-run → proceed when all pass

**Quality gates** (must pass before commit):

• ✅ All tests passing
• ✅ Coverage meets target (from EPCC_EXPLORE.md or ≥80% default)
• ✅ No linting errors (warnings OK)
• ✅ Type checking clean
• ✅ No CRITICAL/HIGH security vulnerabilities

Phase 2: Handle Failures

**Automatic fixes** (no user input):

• Formatting issues → Run formatter (black, prettier, rustfmt)
• Import issues → Run import organizer
• Linting auto-fixes → Run linter with --fix
• Simple type errors → Add type annotations

**Ask user when:**

• Can't fix after 2-3 attempts
• Fix requires changing requirements/approach
• Security vulnerability needs architectural change
• Tests fail with unclear root cause

Commit Blockers

**🛑 Never commit when:**

• CRITICAL or HIGH security vulnerabilities unfixed
• Tests failing (even if "just flaky" - fix or skip properly with markers)
• On main/master branch (create feature branch first)
• Committing to someone else's commit without permission (check authorship)

**⏸️ Pause to fix when:**

• Coverage dropped below target (add tests or document why)
• Multiple TODO/FIXME/DEBUG statements (clean up or track as issues)
• Linting failures (auto-fix or suppress with comments explaining why)
• Type errors (add annotations or use proper types)

**Principle**: Don't commit broken code. Fix or block commit.

Git Workflow Decision Heuristics

**Never:**

• Commit to main/master without PR (creates deployment risk)
• Use `git add .` blindly (stages unrelated changes, breaks atomicity)
• Push without local verification (CI is not your test environment)
• Amend pushed commits (rewrites history others depend on)
• Skip safety checks (shortcuts create production incidents)
• Commit secrets, API keys, credentials (.env files, config with keys)

Stage Explicitly, Not Globally

**When to stage:**

• After reviewing changes with `git diff` (understand what you're committing)
• Files that share a logical change unit (related functionality)
• When you can describe the change in one sentence (atomicity test)

**Staging heuristic**: Stage files by purpose, not by convenience. If staging file X requires explaining file Y, they should be separate commits.

**Anti-patterns to avoid**:

• ❌ `git add .` (stages everything—debug code, temp files, unrelated changes)
• ❌ Staging unrelated changes together (breaks atomic commit principle)
• ❌ Staging without reviewing diff (commits things you didn't intend)

**Pattern**: `git add path/to/related/file1.py path/to/related/file2.py`, then `git diff --staged` to verify.

Commit When Atomic and Complete

**Commit heuristic**: Can you describe the change in one sentence? Would reverting this commit leave the codebase in a working state? If yes to both, commit.

**When to commit:**

• Change completes one logical unit (feature, fix, refactor)
• Build and tests pass after this commit (verify before committing)
• Message can be drafted from context (EPCC_PLAN.md + EPCC_CODE.md + git diff)
• All quality gates passed (or explicitly deferred with reasoning)

**Commit message pattern** (Conventional Commits or project conventio