comprehension-report

What this skill does

# 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

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

```bash
# 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 }'
```

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

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

```bash
# 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

```bash
# 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

```markdown
## 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

```markdown
## 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