Pre-Commit Breaking Impact Analysis

Purpose

1. Detect breaking API changes, database schema changes, and config migrations in staged code
2. Block commits containing unmitigated breaking changes (exits with code 1)
3. Warn on risky changes that may impact stability (exits with code 0, logs warnings)
4. Allow safe changes to pass silently (exits with code 0, minimal output)
5. Provide actionable remediation steps for detected breaking changes

Trigger

Property	Value
Event	pre-commit
Blocking	Yes
Timeout	30s
Failure Mode	Block commit, display breaking change analysis
Skip Command	git commit --no-verify

Behavior

When Triggered

The hook executes when git commit is invoked. It analyzes all staged files for:

• API Breaking Changes: Removed endpoints, changed signatures, deprecated header removals
• Database Schema Changes: Dropped columns, renamed primary keys, constraint modifications
• Configuration Breaking Changes: Required new environment variables, config restructuring
• Dependency Changes: Major version upgrades with incompatibilities
• File System Changes: Relocated critical paths, renamed module exports

Configuration

Create .coditect/config/breaking-impact-hook.json:

{
  "enabled": true,
  "timeout_seconds": 30,
  "analysis_modes": {
    "strict": false,
    "warn_risky": true,
    "pass_safe": true
  },
  "detection_patterns": {
    "api_endpoints": [
      "def delete_.*\\(",
      "def remove_.*\\(",
      "@deprecated"
    ],
    "database": [
      "DROP TABLE",
      "ALTER TABLE.*DROP COLUMN",
      "RENAME TO"
    ],
    "config": [
      "os.environ\\[.+\\]",
      "getenv\\(.+\\)"
    ]
  },
  "exemption_patterns": [
    "CHANGELOG.md",
    "*.test.py",
    "docs/",
    ".coditect/config/"
  ],
  "remediation_templates": {
    "api_removal": "Add deprecation notice (6-month window) before removal",
    "schema_change": "Add migration task and deployment notes",
    "config_change": "Document in BREAKING-CHANGES.md with migration guide"
  },
  "notify_channels": {
    "breaking_found": "slack",
    "risky_found": "log"
  }
}

Integration

The hook integrates with:

• Skill: breaking-impact-review - Detection and analysis logic
• Hook Chain: Runs before pre-commit-test-validation.md hook
• Bypass: Only via git commit --no-verify (tracked in audit log)
• CI Bridge: Failures replicated in CI pre-merge checks

Output

Safe Changes (Exit 0, Silent)

✓ No breaking changes detected

Risky Changes (Exit 0, Warnings)

⚠ WARNING: Risky changes detected (will pass, but monitor)
  - Endpoint signature change in users.py (line 45)
    Impact: Client compatibility risk
    Mitigation: Add deprecation warning header

  Run: git show --staged users.py | head -50

Breaking Changes (Exit 1, Blocked)

✗ BLOCKED: Breaking changes require mitigation

Breaking Change #1: API Endpoint Removed
  File: src/api/routes.py (line 123)
  Removed: DELETE /api/v1/users/{id} (no deprecation period)
  Impact: CRITICAL - Breaking client code
  Remediation: Add 6-month deprecation, redirect to v2 endpoint

Breaking Change #2: Required Config Added
  File: config/defaults.py (line 67)
  New: MANDATORY_AUTH_TOKEN environment variable
  Impact: HIGH - Deployment will fail
  Remediation: Document migration path, update deploy checklist

Commit blocked. Remediation options:
  1. Add deprecation + 6-month window
  2. Document breaking changes in BREAKING-CHANGES.md
  3. Use git commit --no-verify to skip (will require release review)

Failure Handling

Scenario	Action	Exit Code
Breaking change detected	Block commit, show remediation	1
Risky change detected	Warn but allow	0
Hook timeout (>30s)	Warn and allow (log incident)	0
Hook execution error	Log error, allow commit (tracked)	0
Detection pattern error	Skip pattern, continue analysis	0

Error Recovery:

# Manually review breaking changes
git diff --staged | grep -E "(DROP TABLE|DELETE|@deprecated)"

# Override after review (logs override reason)
git commit --no-verify -m "chore: breaking change - ADD_REASON_HERE"

Related Hooks

Hook	Timing	Relationship	Purpose
pre-commit-test-validation.md	Pre-commit (after)	Sequential	Validates tests before breaking change check
pre-deploy-release-gate.md	Pre-deploy	Downstream	Quality gate receives breaking change report
post-deploy-smoke-test.md	Post-deploy	Verification	Validates no regressions from breaking changes
pre-push-changelog-enforcer.md	Pre-push	Documentation	Ensures BREAKING-CHANGES.md updated

Principles

1. Fail-Safe Defaults: Breaking changes blocked by default; only --no-verify allows bypass
2. Transparent Detection: All patterns logged; false positives reported to skill team
3. Remediation-Focused: Every breaking change includes specific mitigation steps
4. Audit Trail: All bypasses (--no-verify) logged with reason for review
5. Fast Feedback: 30s timeout ensures developers get immediate feedback
6. Skill-Driven: Detection patterns and remediation templates managed by breaking-impact-review skill
7. CI Parity: Same logic runs in CI pre-merge checks for consistency

---

Related Documentation:

• ADR-183 - Governance hook architecture
• CODITECT-STANDARD-AUTOMATION.md - Automation principles
• skills/breaking-impact-review/SKILL.md - Detection patterns