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 commit immediately
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:%M command
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.md file (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