mjmorales/comprehend

Comprehend: $ARGUMENTS

Generate 3-5 questions about a recent diff, quiz the developer interactively, and log comprehension gaps. Tone is collaborative, not evaluative. Max 5 questions (target 2-5 minutes).

Phase 1: Gather Diff

1. Scope: Use $ARGUMENTS if provided (SHA, range, or path). Otherwise detect:
   • Unstaged/staged changes: git diff
   • Clean tree: git diff HEAD~1
   • Initial commit: git show HEAD
2. Validate: git diff --stat on chosen scope. Empty diff -- inform and stop.
3. Large diffs (>500 lines): Focus on structurally significant files (new files, new functions, modified control flow). If >5 files, use AskUserQuestion to let user pick focus files.
4. Show file list and line count. Proceed without confirmation unless scope seems wrong.

Phase 2: Generate Questions

1. Read the full diff and each changed file for surrounding context.

2. Generate 5 questions (drop to 3 if <3 functions or ~50 lines). Each targets one category:

   | Category | Example | |----------|---------| | Causality | "What happens if this error handler is removed?" | | Design rationale | "Why was a Map used here instead of a plain object?" | | Data flow | "Where does this config value originate and what consumes it?" | | Edge cases | "What happens when this list is empty?" | | Integration | "How does this change affect existing callers?" |

3. Quality requirements:

   • Reference a specific line, function, or pattern from the diff
   • Require understanding relationships between multiple parts (not single-line reads, not syntax trivia)
   • Prefer questions where a wrong answer would cause a real bug
   • Vary categories across questions

4. Answer options per question: One correct answer, one plausible-but-wrong answer, "I'm not sure" (last). Randomize correct/wrong position.

Phase 3: Interactive Quiz

For each question:

1. Present via AskUserQuestion: header "Q{n}/{total}", question prefixed with [Category], three options.

2. Respond:

   • Correct: Brief acknowledgment + one sentence explaining why, referencing specific code.
   • Wrong/unsure: 2-4 sentence explanation with file/line references. Describe what bug the wrong answer would cause if relevant.

3. Track: category, question, answer, correct/incorrect.

Phase 4: Session Summary

1. Score: X/{total}
2. Rating:
   • All correct: Strong -- you own this code
   • 1 wrong: Solid -- minor gap, noted below
   • 2 wrong: Moderate -- review gaps before extending this code
   • 3+ wrong: Needs Review -- read through changed files before proceeding
3. Gaps (missed questions only): category, one-line gap description, file/function to re-read
4. Key takeaway: one sentence on the most important thing about this diff.

Phase 5: Log

Skip if .prove/ directory does not exist.

AskUserQuestion (header "Log"):

• "Save to .prove/learning/" -- log for future reference
• "Skip"

If saving, write to .prove/learning/YYYY-MM-DD-<topic-slug>.md:

# Comprehension Log: <topic>
**Date**: YYYY-MM-DD
**Scope**: <diff description>
**Score**: X/{total}
**Rating**: Strong | Solid | Moderate | Needs Review

## Questions
### Q1: [Category] <question>
- **Answer**: <user's answer>
- **Correct**: Yes | No
- **Explanation**: <if wrong>

## Gaps
- <category>: <gap> -- re-read `<file>:<function>`

## Takeaway
<one sentence>

Inform user where the log was saved.

Committing

This skill does not modify project code. Delegate learning log commits to the commit skill.