Skip to content

Advisory Pre-Commit Hooks — Reminder vs Blocker for Drift Detection

Problem

A pre-commit hook can detect that a generated artifact (e.g., a skill map, a path manifest, a schema snapshot) is out of sync with its source. The question is: should it block the commit (exit 1) or remind (exit 0)?

Blocking is the wrong default when: - Drift is a discoverability inconvenience, not a data-correctness failure - The generated artifact is reference documentation, not runtime-critical config - Normal authoring commits (adding/editing skills) will always trigger drift - Developers reasonably skip regeneration for small changes

Blocking causes friction → developers add --no-verify → hook becomes useless.

Solution: Advisory Hook (exit 0)

Exit 0 always. Print a prominent reminder when drift is detected:

# In pre-commit hook
if echo "$STAGED_FILES" | grep -q "skill-symlinks.manifest"; then
  echo ""
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo "  Skill map reminder: manifest changed."
  echo "  Run: bash bin/generate-skill-map.sh"
  echo "  Then: git add docs/skill-orchestration-map.*"
  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
  echo ""
fi
# Always exit 0 — advisory only

The developer sees the message, regenerates if the change warrants it, and re-commits. If the change is minor (fixing a typo in a skill description that doesn't affect the map significantly), they can ignore it and regenerate in a follow-up commit.

Escalation Path

If advisory drift becomes chronic (developers consistently skip regeneration, map is weeks stale), escalate to hard-fail:

  1. Add a --verify / --check mode to the generator: 
    bash bin/generate-skill-map.sh --check  # exit 1 if would-change
  2. Replace the advisory print with a --check call in the hook
  3. Document in spec that this is an intentional policy change

This pattern mirrors regenerate-skill-paths.sh --check (SPEC-123) which escalated after the soft-warning phase.

When Advisory is Appropriate

Condition Use advisory (exit 0) Use hard-fail (exit 1)
Reference documentation drift ✓
Path/import resolution errors ✓
Security policy violations ✓
Schema compatibility breaks ✓
Generated artifact used by CI/CD ✓
  • SPEC-125 AD-3 (Architecture Decision Log)
  • SPEC-123 regenerate-skill-paths.sh --check (hard-fail escalation example)
  • plugins/core-standards/scripts/pre-commit — implementation