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

Step 2: Read Report Configuration

# Read report threshold from settings (local > project > user > default)
THRESHOLD=$(jq -r '.report.thresholdFull // empty' .claude/settings.gh-workflow.local.json 2>/dev/null)
[ -z "$THRESHOLD" ] && THRESHOLD=$(jq -r '.report.thresholdFull // empty' .claude/settings.gh-workflow.json 2>/dev/null)
[ -z "$THRESHOLD" ] && THRESHOLD=$(jq -r '.report.thresholdFull // empty' "$HOME/.claude/settings.gh-workflow.json" 2>/dev/null)
[ -z "$THRESHOLD" ] && THRESHOLD=100

Step 3: Determine Report Tier

Evaluate diff complexity:

1. Count total lines changed from git diff --numstat
2. Count distinct directories touched (top-level grouping)
3. Check for new modules — files in directories that don't exist on the default branch

Minimal tier when ALL of these are true:

• Total lines changed < threshold (default 100)
• Changes touch a single top-level directory
• No new modules or directories created
• Changes are limited to docs, config, or existing file modifications

Full tier when ANY of these are true:

• Total lines changed >= threshold
• Changes span multiple top-level directories
• New modules or directories created
• New dependencies added

Step 4: Generate Report

Minimal Report

## Comprehension Report

**Tier**: Minimal ({N} lines changed, single area)

### Summary

{2-3 sentence plain-language description of what changed and why. Reference the issue objective. Written for a human who hasn't seen the code.}

### Requirements Adherence

| # | Acceptance Criterion | Status | Evidence |
|---|---------------------|--------|----------|
| 1 | {criterion from issue} | Met | {file:line or brief description} |
| 2 | {criterion from issue} | Met | {file:line or brief description} |

Full Report

## Comprehension Report

**Tier**: Full ({N} lines changed, {M} areas)

### Summary

{2-3 sentence plain-language description of what changed and why. Reference the issue objective. Written for a human who hasn't seen the code.}

### Architecture Decisions

{Key structural choices extracted from the decision journal. For each significant decision:}

{**Sensitivity filtering**: Parse each journal entry's `Sensitivity:` field. Only include entries with `Sensitivity: public`. For entries with `Sensitivity: internal`, emit: `- **[Internal decision]** — [See decision journal for details]`. Never include internal decision details, rationale, or context in the PR body.}

- **{Decision title}** — {What was decided and why}. Risk: {risk level}. {If alternatives were considered, mention them briefly.}

{If no decision journal exists: "No decision journal found — decisions inferred from diff analysis."}

### How It Connects

{Relationship to existing system components. What existing code does this interact with? What patterns does it follow or extend? Are there new integration points?}

- **Extends**: {existing module/pattern}
- **Integrates with**: {existing component}
- **New entry point**: {if applicable}

### Requirements Adherence

| # | Acceptance Criterion | Status | Evidence |
|---|---------------------|--------|----------|
| 1 | {criterion from issue} | Met | {file:line or brief description} |
| 2 | {criterion from issue} | Interpreted | {what was interpreted and how} |
| 3 | {criterion from issue} | Partially Met | {what's done, what's missing} |
| 4 | {criterion from issue} | Not Addressed | {reason — deferred, out of scope, blocked} |

**Status definitions:**
- **Met** — Criterion directly implemented and testable
- **Interpreted** — Criterion was ambiguous; implementation reflects a specific interpretation
- **Partially Met** — Some aspects implemented, others pending
- **Not Addressed** — Not implemented in this change

### What to Verify

{Specific things a human should check. Not generic advice — concrete actions based on this specific diff.}

- [ ] {Specific verification action 1}
- [ ] {Specific verification action 2}
- [ ] {Specific verification action 3}

Step 5: Return Output

Return the complete report markdown. The calling command (gh-pr) includes it in the PR body.

Output Format

Input	Returns
Diff + issue + journal	Structured comprehension report markdown (minimal or full tier)

Graceful Degradation

Missing Capability	Fallback
No decision journal	Generate report from diff + issue only, note "decisions inferred from diff analysis"
No issue context (gh issue view fails)	Generate report from diff only, skip requirements adherence
Empty diff	Return "No changes to analyze" notice
Branch has no issue number	Use branch name as context, skip issue-specific sections
Report threshold not configured	Default to 100 lines

Integration Points

This skill is invoked by:

• gh-pr — Phase 3 (parallel with code review agents), output included in Phase 7 PR body
• gh-address — After fixes applied, to regenerate stale reports