bmad-walkthrough

어떤 스킬인가요?

Guide a human review of a commit, PR, file, or directory. Use when invoked by name

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

[skill]
bmod = "bmod-method"
source = "github:bmad-code-org/BMAD-METHOD/skills"

# DO NOT EDIT -- overwritten on every update.
#
# Workflow customization surface for bmad-walkthrough.
# Mirrors the agent customization shape under the [workflow] namespace.

[workflow]

# --- Configurable below. Overrides merge per BMad structural rules: ---
#   strings: override wins • arrays (persistent_facts): append
#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.

# Executed when the workflow starts.
on_activation = ""

# Executed when a block is first presented.
on_block_activation = ""

# Facts the workflow keeps in mind for the whole run
# (standards, compliance constraints, stylistic guardrails).
# Each entry is either:
#   - a literal sentence, e.g. "All stories must include testable acceptance criteria."
#   - a file reference prefixed with `file:`, e.g. "file:{project-root}/docs/standards.md"
#     (glob patterns are supported; the file's contents are loaded and treated as facts).
persistent_facts = []

# Executed when the user says a block is done.
on_block_complete = ""

# Executed when the user wraps up.
on_complete = ""

---
name: bmad-walkthrough
description: 'Guide a human review of a commit, PR, file, or directory. Use when invoked by name'
---

Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory:

```bash
uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}"
```

- The command prints the skill's workflow: follow it. `HALT: <reason>`: report the reason and stop.
- If the script is not found, BMad is not set up here. Offer to run the `bmad` skill's setup, installing `bmad` first if you do not have it (`npx skills add bmad-code-org/BMAD-METHOD --skill bmad`), then run the command above once more.
- On any other failure (including `uv` being unavailable), report the command output and HALT. Do not run any workflow source directly.

# Step 1: Orientation

Understand what the target is and what it is for. When a ticket
covers the target (initiative-, epic-, story-, spike- or bug-*.md
under the initiative folder, or an older SPEC*.md), read it first
and in full and trust it. Then use the plan, PR description, and
commit messages when they exist. Ask the user questions until you
know both.

## CHECKPOINT

If subagents are available: is the background subagent for writing
the log and narrative files running? If not, spawn it now. Doing
that work in the main session distracts the user. Do not load the
next step until that subagent is running.

## NEXT

Read fully and follow: `{{ rendered("step-02-narrative.md") }}`

# Step 2: Create review narrative

Write the review narrative and the review log in a new folder
`walkthrough-<slug>/` under
`{{ initiative_folder }}/`: the narrative as
`walkthrough-<slug>.md`, the log as `walkthrough-<slug>-log.md`.
`<slug>` is a short review slug; check that the folder name is
unused before creating it.

- **Review narrative:** Write blocks in the Block shapes. Use
  unchecked boxes for unvisited, in-progress, or reopened blocks,
  labeling their state; check a block when the user indicates they
  are satisfied with it. Note whether it changed during review and
  identify the current block. Work performed on a block does not
  itself mean it is accepted.
- **Review log:** Read and use `{{ rendered("templates/log-template.md") }}`.
  Keep findings, decisions, edits, and test results out of the review
  narrative.

If you are running in a sidebar of VS Code, Cursor, or another
editor, open the narrative file in the editor.

## NEXT

Read fully and follow: `{{ rendered("step-03-walkthrough.md") }}`

# Step 3: Walkthrough

Give the block's link into the narrative, its content in that block's
shape.
{% if workflow.on_block_activation %}

{{ workflow.on_block_activation }}
{% endif %}

On block 1, list the moves in one line so the user knows the
repertoire; past seven, name seven at random and say how many more
there are. On every block, suggest 1-3 moves that fit; when more fit
than you will name, prefer ones not yet suggested in this review.
Then stop. The named moves are not exhaustive; if something else is
more obvious, suggest that instead. The user may choose something you
did not suggest, or just ask a question: answer it in this session
with clickable references, without any formal review skill. Do what
the user says. Stay with the current block until the user explicitly
says it is done.

Do not add status chatter ("still current", "waiting on you") on
later turns unless the reviewer asks where they are.

If they reject a block's shape, rewrite that block in the shape they
describe, in both the session and the narrative, and record the
constraint in the log so it applies to every later block. Do not
present the same block a third time in a different shape without
being asked.

When they say the block is done:
{{ workflow.on_block_complete | default("
- present the next block first so they can keep going.
- then record that the previous block is done: check it
  in the narrative silently, and revise the remaining narrative if it
  needs to change.
- If the tree is dirty, ask the user whether to commit.
  A dirty tree is generally undesirable; the user can still move on.", true) }}

# Moves

A repertoire the user may select from. Do not start a move unless the user
picks it. Record the outcome in the review log and keep their place in
the review narrative.

- **Second opinion:** Put a question to a fresh subagent that does
  not have this review's conversation. Do not use any formal review
  skills. Suggest it when your own read may be anchored by the review
  so far.
- **Formal review:** Use the most appropriate formal review skill
  available. If it's code and `bmad-code-review` skill is installed, prefer
  that unless the user says otherwise. Suggest it for the riskiest
  block of the change.
- **Test:** Help test the part under discussion. Identify useful checks
  and expected behavior, run what you can, and guide the user through
  observations that need them. Record what was actually tested, the
  results, and anything still unverified. Suggest it when behavior is
  easier to check than to reason out, or the tests do not cover it.
- **Drive:** Start the app and tell the user which buttons to push to
  see the target do its thing. Suggest it when the target is
  observable and the user has the app at hand.
- **Demo:** Exercise the change yourself and show the user what
  happened: screenshots or a transcript, in a rendered view the host
  offers; say which. Save them in the walkthrough folder and link
  them from the log. Suggest it when the target is observable and
  the user would rather watch than drive.
- **Draw:** Diagram the block's mechanism, showing only what the
  linked code does, in a rendered view the host offers; say which.
  Save the source in the walkthrough folder and link it from the
  log. Suggest it when the mechanism has several moving parts.
- **Wrap-up:** The review is finished. Guess the follow-through
  this work was for (e.g. merge the PR, write the review, commit
  and push if they edited) and ask the user if that is what they
  want. Do not do it until they say so. Do not end with only a
  summary in chat. Suggest it when every block has been gone
  through. {% if workflow.on_complete %}{{ workflow.on_complete }}{% endif %}

{% raw %}# Review log: {{review_identifier}}

Target: {{target_reference}}

<!--
Append-only record of outcomes/decisions.
Main purpose: persisted context for resuming or analyzing
the review process. You're writing this log for consumption
by another LLM session.

Record decisions and their reasons, user constraints, unresolved
findings, and references needed to recover evidence. Link to large
results rather than copying them here.
This is NOT a transcript or internal deliberation.
The review narrative (the human-facing file) owns review blocks
and their statuses.

Log entry:
Use format below. Omit empty fields. In Result, give each finding's
disposition: fixed, accepted as-is, deferred, or open. When a
disposition changes, append a new entry; do not edit earlier ones.
Record the actual session ID supplied by the environment and an ISO
8601 timestamp with local timezone for each entry. If the session ID
is unavailable, write "unavailable" rather than inventing one.

Token budget: up to 150 tokens per entry.
The smaller the better, but do not sacrifice precision.
-->

## {{entry_number}} — {{block_or_area}} — {{activity}}

Session: {{session_id}} · Timestamp: {{timestamp}}

- Action: {{what_was_examined_changed_or_tested}}
- Result: {{findings_outcome_or_decision_and_reason}}
- Evidence: {{file_references_commands_or_result_links}}
- Open: {{unresolved_work_or_question}}
{% endraw %}

Guide a human review of a target, one block at a time. They may
stop to inspect, edit, or test. Keep track of which blocks the
user has called done. A block or the review as a whole is done
only when the user says it is.

# Terms

- **Target:** The commit, PR, file, or directory being reviewed.
- **Review:** The session. Done when the user says it is.
- **Block:** One slice of the walkthrough. Accepted only when the user
  says so.
- **Review narrative:** The human-facing writeup. Organized in blocks.
  Owns block review status.
- **Review log:** Append-only record of review activities and outcomes.
- **Finding:** A concrete issue from inspection.
- **Move:** A user-selected action, maybe from a repertoire of
  moves in the walkthrough step.

# Human attention is scarce

Show only what a human needs to see. Do not distract them. Write
the log, edit the narrative, look things up, reason — but do not
put it in the session.

When subagents are available, spawn a cheap background one for
writing log and narrative files. Doing that work in the main
session distracts the user.

# Write for a human

The session output and the review narrative file are for a human.
Assume that said human has reasonable understanding of the
surrounding context, but doesn't know anything about the target
except things that have been mentioned in this session. Leave the
brief log style to the log.

# Clickable file refs

Never write a file or `file:line` reference in human-facing output
as plain text.

In the review narrative file, every file and `file:line` must be a
markdown link relative to that file (`[label](../src/foo.ts)`).

In the session, never write a markdown link. Use a form the host
can click: a Cursor code citation (`startLine:endLine:path` on the
opening fence); a VS Code `#file:path`; or a CWD-relative
`path:line` with no leading `/`. If unsure, use `path:line`.

# Block shapes

**Intent** (block 1). What the change is for and why it exists now.
If the target's ticket states the intent, paste it verbatim; failing
that, a plan file's intent section. Otherwise generate from what you
know about the target, no more than 300 tokens. Include a short note
on where you got it from.

**Broad strokes** (block 2). What the change generally is, and its top
level: the three to five entry points a reader would open first, each
with one clickable reference and one clause saying what it is. This is
neither a second prose account of the intent nor an index of every
changed file. If you find yourself listing a layer's files, stop; that
belongs in the slices. Test: the reviewer can open the linked spots in
order and understand the mechanism without reading anything else.

**Slices** (middle blocks). One concern per block, not one file. Lead
with the mechanism in two or three sentences, then the specific places
with references.

For a simple change applied to a large number of files, group the
files by how they were changed (one or several groups). Treat each
group as a slice: one or two worked examples, plus a clickable list
of the rest that got the same treatment.

**Periphery** (last block). Docs, build registration, small enablers.
References only, one clause each.

{% if workflow.on_activation %}
# On Activation

{{ workflow.on_activation }}
{% endif %}
{% if workflow.persistent_facts %}
# Persistent facts

Do not compact these away. Load `file:` paths. Expand globs and read
every match. Other entries are facts.

{{ workflow.persistent_facts }}

{% endif %}
# Workflow

Follow the step files in order. Read one step fully, execute it, then
load the next step only when directed. Do not skip, reorder, or
pre-load steps.

# FIRST STEP

Read fully and follow: `{{ rendered("step-01-orientation.md") }}` to begin.