Decision Log - Pre-Commit Workflow
CRITICAL: ALWAYS Execute This Workflow Before Any Commit
This skill is mandatory when user mentions commit. Do NOT skip to git commit directly.
Workflow (Execute in Order)
Step 1: STOP - Do Not Commit Yet
When user says "commit" or "git commit":
- DO NOT execute
git commitimmediately - User wants a commit, but you must generate decision log FIRST
Exception: If user explicitly says "skip decision log" or "commit without log":
- Respect their choice and proceed directly to git commit
- Skip Steps 2-6 entirely
Step 2: Review What's Being Committed
Run these commands in sequence:
# See what files are staged
git diff --cached --name-only
# See the actual changes
git diff --cached
Show the user:
- Which files changed
- Key changes (summarize if diff is >50 lines)
Step 3: Generate Decision Log
Based on the diff, create a 3-line decision log:
[YYYY-MM-DD HH:MM] <one-line summary>
- Why: <core reason for this change>
- Risk: <known issues/shortcuts or "none">
CRITICAL - Time Format Rules:
- Use current system time for HH:MM
- Get it from:
date +%H:%Mcommand - DO NOT guess or make up times
- DO NOT use placeholder times like "14:30" or "18:00"
Example of getting current time:
$ date +%Y-%m-%d
2026-01-29
$ date +%H:%M
10:47
# Use these exact values:
[2026-01-29 10:47] Summary here
Rules:
- Summary: Extract from user's recent messages or infer from code changes
- Why: The business/technical reason (not "user asked")
- Risk: Be honest about shortcuts, missing tests, or edge cases
Example:
[2026-01-29 10:47] Sync pairing settings types across test env
- Why: Test suite needed updated Setting type to match production
- Risk: May break other tests expecting old type structure
Step 4: Show Proposed Commit
Present to user:
I'll commit these changes:
Files:
- src/types/setting.ts
- src/test/setup.ts
(+ 3 more files)
With message:
---
fix: sync pairing settings types and test env
[Decision Log]
[2026-01-29 10:47] Sync pairing settings types across test env
- Why: Test suite needed updated Setting type to match production
- Risk: May break other tests expecting old type structure
---
Proceed with commit? [y/n/skip]
- y: Commit with decision log
- n: Cancel and revise
- skip: Commit without decision log
Step 5: APPEND Decision Log to File (DO NOT OVERWRITE)
CRITICAL: This step must APPEND, not overwrite existing content
Execute these commands in this exact order:
# 1. Create directory if needed
mkdir -p .decisions
# 2. Get current date and time from system
TODAY=$(date +%Y-%m-%d)
TIME=$(date +%H:%M)
# 3. APPEND to file (NEVER overwrite)
# Use >> for append, NOT > which overwrites
cat >> .decisions/$TODAY.md << EOF
[$TIME] Make build workflow package-only
- Why: Build pipeline should only produce artifacts without tagging or releasing
- Risk: none
EOF
VERIFICATION REQUIRED:
After appending, verify the file still contains old entries:
# Show the file to confirm old entries are preserved
cat .decisions/$TODAY.md
Expected output:
[09:05] Add pairing orchestration tracing...
[09:51] Improve pairing usecase...
[10:28] Remove direct deps...
[10:47] Make build workflow package-only ← New entry with CURRENT time
If old entries are missing → ABORT and show error
Step 6: Stage the Decision Log File
# Stage the entire .decisions/ directory
git add .decisions/
Why this matters:
- The decision log file must be included in the same commit
- Without staging, it won't be part of the commit
Step 7: Execute Commit
Only after user confirms AND verification passes, run:
git commit -m "fix: make build workflow package-only
[Decision Log]
[2026-01-29 10:47] Make build workflow package-only
- Why: Build pipeline should only produce artifacts without tagging or releasing
- Risk: none"
If user chose "skip" in Step 4:
# Commit without decision log
git commit -m "fix: make build workflow package-only"
Result:
- Commit includes both code changes AND the
.decisions/YYYY-MM-DD.mdfile (if not skipped) - Old decision log entries are preserved in the file
- Time reflects actual commit time, not a guess
User Options During Confirmation
When asking "Proceed? [y/n/skip]":
y - Commit with decision log (default workflow) n - Don't commit, let user revise message or decision log skip - Commit immediately without decision log (skip Steps 5-6)
Examples:
User: "y" → Full workflow with decision log
User: "n" → Cancel, ask what to change
User: "skip" → Direct git commit, no decision log
User: "skip decision log" at any point → Immediately skip to git commit
User: "commit without log" → Skip entire workflow, direct commit
Anti-Patterns (NEVER DO THESE)
❌ Using > instead of >>: This OVERWRITES the file
cat > .decisions/2026-01-29.md # ❌ WRONG - deletes old content
✅ Correct: Use >> This APPENDS to the file
cat >> .decisions/2026-01-29.md # ✅ CORRECT - preserves old content
❌ Guessing the time: Using placeholder times
[14:30] Summary # ❌ WRONG - where did 14:30 come from?
✅ Correct: Use system time
TIME=$(date +%H:%M)
[$TIME] Summary # ✅ CORRECT - actual current time
❌ Not verifying after append: Always check that old entries still exist
❌ Ignoring user's "skip" request: If user says skip, don't force decision log
Complete Example Workflow
User: "commit"
Claude:
[Step 1] Reviewing staged changes...
[Step 2]
Files to commit:
- src/workflows/build.yml (modified)
Key changes:
- Removed release steps from build workflow
[Step 3] Getting current time...
$ date +%Y-%m-%d
2026-01-29
$ date +%H:%M
10:47
Generated decision log:
[2026-01-29 10:47] Make build workflow package-only
- Why: Build pipeline should only produce artifacts without tagging
- Risk: none
[Step 4]
I'll commit with this message:
---
fix: make build workflow package-only
[Decision Log]
[2026-01-29 10:47] Make build workflow package-only
- Why: Build pipeline should only produce artifacts without tagging
- Risk: none
---
Proceed? [y/n/skip]
User: "y"
Claude:
[Step 5] Appending decision log...
$ mkdir -p .decisions
$ TODAY=$(date +%Y-%m-%d)
$ TIME=$(date +%H:%M)
$ cat >> .decisions/$TODAY.md << EOF
[$TIME] Make build workflow package-only
- Why: Build pipeline should only produce artifacts without tagging
- Risk: none
EOF
[Verification] Checking file contents...
$ cat .decisions/2026-01-29.md
File contents:
[09:05] Add pairing orchestration tracing...
[09:51] Improve pairing usecase...
[10:28] Remove direct deps...
[10:47] Make build workflow package-only ✓ Appended with actual time
[Step 6] Staging decision log...
$ git add .decisions/
[Step 7] Committing...
$ git commit -m "fix: make build workflow package-only
[Decision Log]
[2026-01-29 10:47] Make build workflow package-only
- Why: Build pipeline should only produce artifacts without tagging
- Risk: none"
✓ Committed: abc1234
✓ Decision log appended (preserving 3 previous entries)
Example: User Skips Decision Log
User: "commit but skip the decision log this time"
Claude:
[Step 1] User requested to skip decision log.
Committing without decision log...
$ git commit -m "fix: make build workflow package-only"
✓ Committed: abc1234
(no decision log created)
Time Extraction Commands
Always use these exact commands:
# Full timestamp
date +"%Y-%m-%d %H:%M"
# Output: 2026-01-29 10:47
# Just date (for filename)
date +%Y-%m-%d
# Output: 2026-01-29
# Just time (for log entry)
date +%H:%M
# Output: 10:47
Never:
- Hardcode times like "14:30" or "18:00"
- Guess based on previous entries
- Use placeholder times from examples
Troubleshooting
Problem: Wrong time in decision log
Symptoms:
$ cat .decisions/2026-01-29.md
[14:30] Entry 1 # Actual commit was at 10:47
Cause: Used hardcoded time instead of date +%H:%M
Fix:
Always run date +%H:%M to get current time before creating log entry
Problem: Old entries disappeared
Symptoms:
$ cat .decisions/2026-01-29.md
[10:47] Make build workflow package-only # Only new entry, old ones gone
Cause: Used > instead of >>, or recreated the file
Fix:
- Check git history:
git show HEAD^:.decisions/2026-01-29.md - Restore old entries from previous commit
- Append new entry correctly with
>>
Problem: User wants to skip but workflow continues
Symptoms: User says "skip decision log" but AI still generates one
Cause: Didn't check for skip keywords in Step 1
Fix: Always check user's message for "skip", "without log", "no log" before starting workflow
Resources
This skill includes a helper script that correctly handles time and append operations.