comprehension-report

Comprehension Report

Generates a structured narrative that helps humans understand what AI built, why it made the choices it did, and whether those choices align with the original intent.

Purpose

In a fully AI-driven workflow, code is produced faster than humans can read it. This skill bridges the gap by:

• Translating diffs into plain-language summaries
• Mapping acceptance criteria to implementation evidence
• Surfacing architecture decisions from the decision journal
• Identifying what humans should verify manually

Report Tiers

The report scales based on diff complexity. Complexity is determined from git diff --stat output.

Diff Complexity	Report Level	Sections
< threshold lines, single area, docs/config only	Minimal — Summary + Requirements Adherence	2 sections
threshold+ lines or multi-area or new modules	Full — All sections	5 sections

The threshold is configurable via .report.thresholdFull in settings. Default: 100 lines changed.

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 (consistent with gh-workflow commands)
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef --jq '.defaultBranchRef.name' 2>/dev/null)
[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"

# Get diff statistics to determine report tier
git diff --stat "$DEFAULT_BRANCH"...HEAD
git diff --numstat "$DEFAULT_BRANCH"...HEAD | awk '{ added += $1; removed += $2 } END { print "Lines added:", added, "Lines removed:", removed, "Total:", added + removed }'

# Get changed files with directory breakdown
git diff --name-only "$DEFAULT_BRANCH"...HEAD

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

# 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"

# Read decision journal if it exists
cat "$JOURNAL_DIR/issue-$ISSUE_NUM.md" 2>/dev/null