map-understand

name	map-understand
description	Interactive deep-understanding and quiz mode for MAP sessions. Use when the user wants to understand code, a diff, workflow result, debugging cause, or architecture and be checked with restatements or quizzes. Do NOT use to implement, review, or persist lessons; use map-explain for one-shot walkthroughs and map-learn for saved project memory.
effort	medium
disable-model-invocation	true
argument-hint	[target | workflow artifact | --depth eli5|eli14|intern|expert]

MAP Understand - Interactive Learning Check

Target: $ARGUMENTS

Purpose: Make the user's understanding a first-class deliverable. This is an opt-in teaching and quiz mode, not a normal workflow step.

Effort and Parallelism Policy

thinking_policy: medium/adaptive
parallel_tool_policy: independent_reads_only

• Use adaptive reasoning to teach accurately and check comprehension, but stop at learning: do not plan, implement, review, or write durable memory from this skill.
• Parallelize independent reads of files, diffs, logs, and .map/<branch>/ artifacts before teaching.
• Keep the actual teaching loop sequential: explain one milestone, ask for a restatement or answer, then fill gaps before moving on.

Behavior Contract

• This skill is opt-in only. Do not make /map-plan, /map-efficient, /map-check, /map-review, or /map-learn more verbose because this skill exists.
• Keep the checklist transient in the conversation. Do not create or update files from this skill.
• Use gender-neutral wording.
• Maintain a running Markdown checklist named Understanding checklist and update it as the user demonstrates understanding.
• Cover the problem/context, why it existed, alternatives or branches considered, the solution, design decisions, edge cases, and broader impact.
• Work incrementally. Do not dump the full explanation at the end.
• At natural milestones, ask the user to restate their understanding or answer a check question.
• Multiple-choice checks are allowed, but do not reveal the answer key before the user responds.
• End only when the user demonstrates enough understanding for the selected depth or explicitly opts out.

Depth Modes

Infer the depth from $ARGUMENTS when present:

Mode	Use When	Teaching Style
eli5	The user wants a simple conceptual explanation	Metaphors first, no jargon until defined
eli14	The user wants a practical beginner explanation	Simple mechanics, light terminology, concrete examples
intern	Default for engineering onboarding	Explain why, how, tradeoffs, and common mistakes
expert	The user already knows the domain	Focus on invariants, edge cases, consequences, and design alternatives

If no depth is provided, default to intern. If the user's wording clearly asks for a different depth, use that depth without asking.

Target Resolution

Resolve the target before teaching:

1. If $ARGUMENTS names a file, directory, symbol, PR ref, commit range, or code snippet, use that target.
2. If it names a workflow artifact such as .map/<branch>/learning-handoff.md, verification-summary.md, review-bundle.md, run_health_report.json, or task_plan_<branch>.md, read that artifact and any directly referenced files needed to explain it.
3. If $ARGUMENTS is empty on a feature branch, explain the branch diff against origin/main or origin/master, whichever exists.
4. If $ARGUMENTS is empty on main/master, explain the project or latest relevant .map/<branch>/ handoff when one clearly exists.
5. If the target is too broad to teach interactively, ask the user to choose a narrower target or teach the highest-leverage slice first and say what was deferred.

Useful bootstrap commands for empty-target branch diff mode:

BASE=$(git rev-parse --verify --quiet origin/main >/dev/null && echo origin/main \
       || (git rev-parse --verify --quiet origin/master >/dev/null && echo origin/master))
if [ -n "$BASE" ]; then
  git fetch origin "${BASE#origin/}" --quiet
  git --no-pager diff --stat "$BASE"...HEAD
  git --no-pager diff "$BASE"...HEAD
fi

Teaching Loop

1. State the mode and target. Say which depth you selected and what evidence you read.
2. Create the checklist. Start with 5-9 unchecked items. Keep items concrete enough to be verified.
3. Teach milestone 1. Explain only the first meaningful slice: usually problem/context and why it existed.
4. Check understanding. Ask one open-ended restatement question or one multiple-choice question. If multiple-choice, withhold the answer key.
5. Fill gaps. After the user responds, mark checklist items as complete only when the response shows understanding. Correct gaps directly and briefly.
6. Continue by milestone. Repeat for design decisions, implementation mechanics, edge cases, alternatives, and impact.
7. Close with proof of understanding. Ask for a short final summary or scenario application. End with final checklist state and remaining optional reading only after the user passes or opts out.

Check Question Guidance

Prefer open-ended checks when the user needs durable understanding:

• "Restate why this bug happened in your own words."
• "What would break if we removed this guard?"
• "Which alternative did we reject, and why?"

Use multiple-choice only when it helps focus the learner:

Which invariant matters most here?
A. The cache is always warm before validation.
B. The validator must reject stale generated surfaces before install.
C. The CLI should skip template rendering when tests pass.

Pick one and explain why. I will not reveal the answer until you answer.

How This Differs From Nearby Commands

• /map-explain is a one-shot walkthrough. Use it when the user wants a complete explanation without a quiz loop.
• /map-learn persists reusable project lessons after a workflow. Use it when the team wants future sessions to remember patterns.
• /map-understand is interactive and transient. Use it when the user's comprehension needs to be verified now.

Examples

/map-understand --depth intern
/map-understand --depth eli14 src/mapify_cli/delivery/template_renderer.py
/map-understand --depth expert HEAD~1..HEAD
/map-understand .map/my-branch/verification-summary.md
/map-understand why #221 changed the skill metadata contract

Troubleshooting

• The user wants only a walkthrough, no quiz - use /map-explain instead, or ask one confirmation question and stop if they opt out.
• The user wants lessons saved for future sessions - use /map-learn; this skill intentionally does not write .claude/rules/learned/ or .map/ artifacts.
• The target is huge - teach the highest-leverage slice first and ask whether to continue with another slice.
• The user answers incorrectly - do not advance the checklist. Correct the exact misconception and ask a simpler follow-up.
• A multiple-choice answer was accidentally revealed early - discard that check and ask a new question without an answer key.