decision-journal

Decision Journal

Captures, structures, and persists significant decisions made during AI-driven workflow execution. Uses post-hoc extraction from diffs rather than AI self-reporting during execution.

Purpose

In a fully AI-driven workflow, decisions happen invisibly. This skill makes them visible by:

• Extracting decisions from completed diffs (what changed vs. what was expected)
• Detecting high-stakes changes that warrant human approval (gates)
• Structuring decisions into a machine-parseable journal format
• Condensing journals into PR-body-ready summaries

Mode Routing

This skill operates in one of three modes. The calling command specifies the mode in its invocation prompt.

Mode	When Used	What It Does
init	gh-start after branch creation	Creates journal file header
log	gh-start, gh-commit, gh-address after changes	Extracts decisions from diff + evaluates gate triggers
summarize	gh-pr during PR content generation	Condenses journal for PR body

Read the mode from the invocation prompt and execute only that mode's instructions. If the mode is not one of init, log, or summarize, return an error: "Unknown mode: {mode}. Expected one of: init, log, summarize."

Mode: init

Input (from invocation prompt): Issue number, branch name, issue title, issue body.

Process:

Step 1: Read Configuration

# Read journal directory from settings (local > project > user > default)
JOURNAL_DIR=$(jq -r '.journal.dir // empty' .claude/settings.gh-workflow.local.json 2>/dev/null)
[ -z "$JOURNAL_DIR" ] && JOURNAL_DIR=$(jq -r '.journal.dir // empty' .claude/settings.gh-workflow.json 2>/dev/null)
[ -z "$JOURNAL_DIR" ] && JOURNAL_DIR=$(jq -r '.journal.dir // empty' "$HOME/.claude/settings.gh-workflow.json" 2>/dev/null)
[ -z "$JOURNAL_DIR" ] && JOURNAL_DIR=".decisions"
echo "Journal directory: $JOURNAL_DIR"

Step 2: Generate Header

Generate the journal file header:

# Decision Journal: Issue #{N} — {issue title}

**Issue**: #{N}
**Branch**: {branch-name}
**Started**: {YYYY-MM-DD}

---