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