synaptiai/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}

---

Output: Return the header markdown and the resolved journal directory (from .journal.dir in settings, default .decisions). The calling command writes it to {journal-dir}/issue-{N}.md.

Mode: log

Input (from invocation prompt): Description of what phase just completed (e.g., "task breakdown", "staged changes for commit", "addressed review feedback"). The calling command provides the relevant context.

Process:

Step 1: Gather Context

# Get current branch and issue number
BRANCH=$(git branch --show-current)
ISSUE_NUM=$(echo "$BRANCH" | grep -oE 'issue-[0-9]+' | grep -oE '[0-9]+')

# Get the default branch
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")

# Read all comprehension config from settings (local > project > user > default)
# Single merge for both journal and gates — used in Steps 1-3
GHW_CONFIG=$(jq -n '
  def defaults: {
    gates: {
      newDependencies:"on", securityChanges:"on", schemaChanges:"on",
      apiSurfaceChanges:"on", scopeDeviations:"on", ambiguousRequirements:"on",
      customTriggers:[], customTriggersMode:"on"
    },
    journal: { dir:".decisions", sensitivityDefault:"public" }
  };
  defaults
    * (try input catch {})
    * (try input catch {})
    * (try input catch {})
' "$HOME/.claude/settings.gh-workflow.json" \
  ".claude/settings.gh-workflow.json" \
  ".claude/settings.gh-workflow.local.json" 2>/dev/null)

JOURNAL_DIR=$(echo "$GHW_CONFIG" | jq -r '.journal.dir')
SENSITIVITY_DEFAULT=$(echo "$GHW_CONFIG" | jq -r '.journal.sensitivityDefault')
echo "Journal directory: $JOURNAL_DIR"
echo "Default sensitivity: $SENSITIVITY_DEFAULT"

Use $JOURNAL_DIR instead of .decisions for all journal file paths in this mode. Use $SENSITIVITY_DEFAULT as the default sensitivity for new entries.

# Get the diff to analyze (staged changes for commit, or branch diff for other phases)
git diff --stat "$DEFAULT_BRANCH"...HEAD
git diff --name-only "$DEFAULT_BRANCH"...HEAD

# Get issue context
gh issue view "$ISSUE_NUM" --json title,body,labels 2>/dev/null

Step 2: Extract Decisions (Post-Hoc)

Analyze the completed diff against the issue context. Identify decisions by comparing:

• What changed vs. what the issue requested — scope decisions, requirement interpretations
• Patterns chosen vs. alternatives available — architecture, implementation trade-offs
• Files touched vs. expected impact area — scope deviations

For each significant decision found, generate a journal entry:

### {YYYY-MM-DD HH:MM} [{CATEGORY}] {Decision Title}

**Command**: {gh-start | gh-commit | gh-address}
**Decision**: {What was decided}
**Alternatives**: {What else was considered, or "N/A" for obvious choices}
**Rationale**: {Why this choice was made}
**Risk**: {Low | Medium | High | Critical}
**Sensitivity**: {public | internal}
**Gate**: {No — AI decision}
**References**: {#M, #K — cross-issue refs, or "None"}

---

Categories: architecture, requirements, trade-off, implementation, risk, scope

Sensitivity rules:

• Default: Use the $SENSITIVITY_DEFAULT value from Step 1 config (falls back to public if not configured)
• Use internal for decisions involving: security rationale, credential/secret handling, vulnerability remediation, access control logic
• Never document specific vulnerability details, exploitation vectors, previous insecure states, or secret values/locations — even in internal entries

Step 3: Evaluate Gate Triggers

Extract gate configuration from the $GHW_CONFIG loaded in Step 1:

# Extract gates from the config already loaded in Step 1
echo "$GHW_CONFIG" | jq '.gates'

If no configuration found, all gates default to on.

Check the diff against these gate detection heuristics:

| Trigger | Detection Method | Config Key | |---------|-----------------|------------| | New dependency | New entries in package.json, requirements.txt, Gemfile, go.mod, Cargo.toml, or new git submodule | .gates.newDependencies | | Security changes | Files matching *auth*, *security*, *permission*, *token*, *secret*, *crypto*, *session*; changes to .env*, CORS/TLS config | .gates.securityChanges | | Schema changes | Database migration files, changes to schema.*, *model* definitions, API type definitions | .gates.schemaChanges | | API surface changes | New route/endpoint definitions, changed function signatures in public modules, new command/skill files | .gates.apiSurfaceChanges | | Scope deviations | Files modified outside the expected impact area from the issue | .gates.scopeDeviations | | Ambiguous requirements | Acceptance criteria containing vague terms ("should be fast", "user-friendly", "appropriate"), contradictory criteria | .gates.ambiguousRequirements |

# Example detection for new dependencies
git diff "$DEFAULT_BRANCH"...HEAD --name-only | grep -E "(package\.json|requirements\.txt|Gemfile|go\.mod|Cargo\.toml|\.gitmodules)" 2>/dev/null

# Example detection for security-related files
git diff "$DEFAULT_BRANCH"...HEAD --name-only | grep -iE "(auth|security|permission|token|secret|crypto|session|\.env)" 2>/dev/null

# Evaluate custom trigger patterns (glob patterns from config)
CUSTOM_TRIGGERS=$(echo "$GHW_CONFIG" | jq -r '.gates.customTriggers[]' 2>/dev/null)
if [ -n "$CUSTOM_TRIGGERS" ]; then
  CHANGED_FILES=$(git diff "$DEFAULT_BRANCH"...HEAD --name-only)
  echo "$CUSTOM_TRIGGERS" | while read -r pattern; do
    echo "$CHANGED_FILES" | grep -E "$pattern" 2>/dev/null
  done
fi

Custom trigger matches use the .gates.customTriggersMode config key (on/log/off), following the same behavior as the named gates.

For each trigger that fires:

1. Check the corresponding config key
2. If on — include in gate trigger output
3. If log — log the decision entry with Gate: Logged (auto-approved) but do not include in gate triggers
4. If off — skip entirely

Step 4: Return Output

Output format:

## Decision Entries

{One or more journal entries in the schema format above}

## Gate Triggers

{If any gates fired with config = `on`:}

| Category | Trigger | Reason | Recommended Action | Alternatives |
|----------|---------|--------|--------------------|-------------|
| security-changes | gates.securityChanges | Modified auth middleware | Review security implications | Proceed without review |

{If no gates fired:}

No gate triggers detected.

The calling command:

• Appends decision entries to {journal-dir}/issue-{N}.md (using the resolved $JOURNAL_DIR from Step 1)
• If gate triggers are present, presents AskUserQuestion with the gate format
• Logs gate responses (approved/bypassed) back to the journal

Mode: summarize

Input (from invocation prompt): Issue number, sensitivity filter preference.

Process:

1. Extract the issue number from the invocation prompt and read journal configuration:

# Extract issue number from invocation prompt (the calling command provides this)
# Example invocation: "Mode: summarize. Issue number: 42. Sensitivity filter: redact internal entries."
# Parse the issue number from the prompt text.

# Read journal-dir 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"

# Read the specific journal file using the issue number from the invocation prompt
cat "$JOURNAL_DIR/issue-$ISSUE_NUM.md" 2>/dev/null

Note: $ISSUE_NUM should be set from the issue number provided by the calling command in the invocation prompt (e.g., "Mode: summarize. Issue number: 42."). If not provided, fall back to branch detection: ISSUE_NUM=$(git branch --show-current | grep -oE 'issue-[0-9]+' | grep -oE '[0-9]+').

2. Parse entries by splitting on --- separators
3. For each entry:
   • If Sensitivity: public — include full entry in summary
   • If Sensitivity: internal — replace with: [Internal decision — see decision journal for details]
4. Condense into a summary format:

Output format:

## Decision Summary

**Total decisions**: {N} ({M} public, {K} internal)
**Gates triggered**: {X} ({Y} approved, {Z} bypassed)

### Key Decisions

| # | Category | Decision | Risk |
|---|----------|----------|------|
| 1 | architecture | {title} | {risk} |
| 2 | requirements | {title} | {risk} |

### Decision Details

{For each public entry, include a condensed version:}

**{Category}: {Title}** — {Decision}. {Rationale}. Risk: {risk}.

{For internal entries:}

**{Category}: [Internal decision]** — [See decision journal for details]

### Gate Activity

{Summary of gate triggers and responses}

Output Format

All modes return structured markdown. The calling command handles file I/O.

| Mode | Returns | |------|---------| | init | Journal file header markdown | | log | Decision entries + gate trigger table | | summarize | Condensed summary for PR body |

Graceful Degradation

| Missing Capability | Fallback | |-------------------|----------| | No gate config in settings | All gates default to on | | No issue context (gh issue view fails) | Extract decisions from diff only, skip requirement comparison | | No existing journal file (for summarize) | Return "No decision journal found" notice | | Empty diff | Return "No changes to analyze" with no entries | | Branch has no issue number | Use branch name as identifier, skip issue context |

Integration Points

This skill is invoked by:

• gh-start — Phase 2 (init mode), Phase 5 (log mode)
• gh-commit — Phase 2 (log mode)
• gh-pr — Phase 3 (summarize mode)
• gh-address — After feedback aggregation (log mode)

The calling command handles all file persistence (Write/Edit to {journal-dir}/issue-{N}.md, where journal-dir is read from settings via .journal.dir, default .decisions) and AskUserQuestion presentation for gate triggers.