bmad-walkthrough

Guides human reviewers through code changes with orientation, risk analysis, and testing steps.

52.5k|6.0k|Updated Apr 13, 2025
One-click install
npx skills add https://github.com/bmad-code-org/BMAD-METHOD --skill bmad-walkthrough
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: bmad-walkthrough
Source: https://github.com/bmad-code-org/BMAD-METHOD/tree/main/src/bmm-skills/ship/bmad-walkthrough
Command: npx skills add https://github.com/bmad-code-org/BMAD-METHOD --skill bmad-walkthrough

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Reviewing a code change without context is slow and error-prone: reviewers must reconstruct intent, find the important spots, and figure out how to verify behavior on their own. This Skill walks a human reviewer through a change step by step, from purpose and surface area to risk hotspots and hands-on verification.

Core Features & Use Cases

  • Orientation and Intent Summary: Identifies the change from a PR, commit, branch, spec, or sprint status, then presents the intent and diff statistics (files changed, modules touched, boundary crossings, new public interfaces).
  • Concern-Based Walkthrough: Organizes the review by design concerns rather than files, with clickable path:line stops ordered for comprehension, generating a review trail from the diff when none exists.
  • Risk and Testing Guidance: Surfaces high-blast-radius spots tagged by category (auth, schema, billing, security, config) and suggests concrete manual observations to confirm the change works.
  • Use Case: After a teammate opens a PR for an authentication refactor, invoke the walkthrough to get the intent summary, a guided tour of the key code locations, a list of risky spots like token validation changes, and commands to observe the new behavior before approving.

Quick Start

Ask the assistant to walk you through the current change or a specific PR, for example by saying "walk me through this change" or "walkthrough PR 42".

Frequently Asked Questions about bmad-walkthrough

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I review a pull request with an AI-guided walkthrough?

Invoke the walkthrough and pass a PR reference, commit SHA, or branch name. The workflow resolves the PR via gh, summarizes the intent, and presents concern-grouped code stops in path:line format so you can click through the change in order.

How does the walkthrough identify high-risk code changes?

It scans the diff for risk-sensitive patterns and tags each spot by category: auth, public API, schema, billing, infra, security, or config. Spots are ordered by blast radius, and up to five are shown with a path:line reference and a short reason phrase.

Can I review a commit that has no spec or review trail?

Yes. In bare-commit mode the workflow uses the commit message as the intent source and generates a review trail from the diff itself. If the message is terse, it drafts a one-sentence intent and flags it as inferred so you can correct it.

What happens if git is unavailable during the review?

Trail generation fails gracefully and the workflow falls back to identifying concerns directly from available context. Surface-area statistics are skipped with a note rather than guessed, and the walkthrough continues with its non-trail path.

Does the walkthrough approve pull requests automatically?

No. The final step asks you to choose approve, rework, or discuss, and halts until you decide. For PRs it can offer to run gh pr review --approve, but only after explicit confirmation since it is a visible action on a shared resource.