explain-pr-step-by-step
Explain a pull request incrementally with concept teaching and confirmation gates between steps. Use when the user asks for a step-by-step PR walkthrough, what changed and why, or asks to pause after
SKILL.mdskills/explain-pr-step-by-step/SKILL.md
GitHubExplain PR Step by Step
Use this skill to teach a PR in guided, checkpointed steps.
Goal
Produce a clear sequence of changes where each step includes:
- what changed,
- why it changed,
- the concept behind it,
- a pause question before moving on.
Required workflow
Collect PR evidence first
- Fetch PR metadata (title, summary/body, commits, files).
- Fetch the full diff and per-file patches if needed.
- Do not infer chronology without checking commit/diff evidence.
Build a teaching sequence
- Group changes into understandable phases, typically:
- feature flag/config enablement,
- contracts/types,
- state domain/data flow,
- UI renderer,
- runtime registration/wiring,
- tests and safety updates.
- Keep each step focused on one core idea.
- Group changes into understandable phases, typically:
Deliver one step at a time
- For each step, include:
- changed files/components,
- behavioral outcome,
- concept explanation (for example lifecycle, caching, hydration).
- End each step with an explicit checkpoint question:
- "Need more detail before we continue to Step N+1?"
- For each step, include:
Honor drill-down questions immediately
- If user asks "where?", "show example", "what does X mean?", pause progression.
- Provide concrete code references and minimal examples.
- Resume next numbered step only after user confirms.
Use collaborative language
- Prefer "we" and "our" phrasing.
- Avoid over-abstract explanations detached from repo code.
Concept teaching rules
- Always link concepts to concrete implementation, deriving examples from the PR's own diff. For example:
- Feature flag -> rollout safety and gating behavior.
- Schema/type change -> contract compatibility between producer and consumer.
- New state field -> data flow and where the source of truth lives.
- Lifecycle/status values -> what each state renders or triggers.
- Keep examples small and directly relevant to current files.
Response template per step
Use this structure:
Step N: <short title>What we changed(files and behavior)Concept(plain-language explanation)Why this mattersCheckpoint question("Need more understanding before Step N+1?")
Quality bar
- Steps must be accurate to the diff.
- Concepts must be technically correct and simple.
- User must control pacing; never dump all steps unless asked.