walkthrough
/walkthrough
Tworzy numerowane przystanki do przeglądu zmiany w działającym serwerze deweloperskim, z opisem tego, co się zmieniło i co sprawdzić.
- Autor
- lablup ↗
- Repozytorium
- backend.ai-webui ↗
- Licencja
- LGPL
- Ostatnia zmiana repozytorium
- 28.10.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 8
- Skrypty
- 7
- Komentarze HTML
- 2
- Adresy URL w SKILL.md
- 1
Brak sygnałów. Repozytorium zmienione 28.10.2026, bez odwołań do wycofanych modeli i API.
LGPL, otwarta.
- 7 skryptów w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
Skrypty: scripts/comment.sh, scripts/manifest.mjs, scripts/manifest.test.mjs, scripts/mint.mjs, scripts/resolve.mjs, scripts/resolve.test.mjs, scripts/test-comment.sh
Co robi i kiedy
Tworzy numerowane przystanki do przeglądu zmiany w działającym serwerze deweloperskim, z opisem tego, co się zmieniło i co sprawdzić.
Wyzwalacze z opisu
Oryginalny opis (EN)
Mint a walkthrough for the PR this session just implemented: a set of numbered stops a reviewer opens in the live dev server, each one marking an element on screen with what changed and what to check. Decide first whether the PR needs one (section 0); when it does, run it as the LAST step of the implementation workflow, after the `dev-server` skill has advertised the PR's server — and on demand for any PR by number, booting a dev server for its branch when none is live. Trigger on "walkthrough 만들어줘", "make a walkthrough", "PR #N에 walkthrough 달아줘", "add a walkthrough to PR #N", `/walkthrough <p
Jak działa
- 0. Is it needed?
- 1. When to run
- 2. Preflight
- 3. Write the stop manifest
- 4. Choose the stops
- 5. Wording
- 6. Run it
- 7. Post it
- 8. Report to the user
- 9. Out of scope
Podgląd SKILL.md
---
name: walkthrough
description: >
Mint a walkthrough for the PR this session just implemented: a set of
numbered stops a reviewer opens in the live dev server, each one marking an
element on screen with what changed and what to check. Decide first whether
the PR needs one (section 0); when it does, run it as the LAST step of the
implementation workflow, after the `dev-server` skill has advertised the
PR's server — and on demand for any PR by number, booting
a dev server for its branch when none is live. Trigger on "walkthrough
만들어줘", "make a walkthrough", "PR #N에 walkthrough 달아줘", "add a
walkthrough to PR #N", `/walkthrough <pr>`, "워크스루 다시 만들어줘",
"re-mint the walkthrough", "after the dev server is advertised for a PR I
implemented", or a request to show a reviewer what changed on screen. It
never posts to Teams, never edits the dev-server comment itself (booting a
server for a PR goes through `dev-server`, which does), and never marks a
PR ready.
---
# Walkthrough
A walkthrough is the reviewer's guided tour of a PR: one `#bai=v3` set link
that opens the dev server on the first stop and walks the rest. Each stop is a
pin the **implementing session** authored, carrying the FR-3949 stop fields —
`ch` (what changed), `ck` (what to check), `old`/`new`, `type`, `kind`, `code`
and the `via` steps (clicks, typing, a select) that reveal it.
You write the stop manifest; `scripts/mint.mjs` does the mechanical half (log
in, replay, mint, verify, link) and `scripts/comment.sh` posts it.
## 0. Is it needed?
Decide from the diff and the PR body **before** booting a server or reading
on. A skip ends here; name it in the final message with its one-line reason.
Mint one only when a reviewer holding the PR body would otherwise have to hunt
for the change or set up a state to see it:
- reaching it takes interaction: a dialog, a wizard step, a tab, a filter, a
hover, a row action;
- the change spans two or more places, or a flow across pages;
- what shows depends on data (a status, a permission, a resource value), so
the check is value → what shows (section 5).
Skip it when:
- **nothing a person can recognize on screen changed**: schema, tests, docs,
generated files, i18n key plumbing, a refactor meant to render the same.
Boot no dev server either.
- **the change is one spot a reader finds on landing**: a relabel, a copy
fix, an icon, a color or spacing change on a page's first screen. Write
`Where to look: <page> › <element>` in the PR body instead; the dev server
still boots.
- **the connected backend can show none of it**: every stop would only say
what this server cannot produce. Put the condition (value → what shows) in
the PR body.
- **a re-run changed no UI** (doc-only, test-only, a fix behind the same
elements): the stops still point at the same elements, and a re-mint would
only churn the ids.
Between a one-stop walkthrough and one line in the PR body, the line wins.
An explicit request (section 1a) overrides the one-spot skip, not the
nothing-on-screen one.
## 1. When to run
- **The last step of the implementation workflow**, when section 0 says it is
needed, after `dev-server` has
advertised the PR's server (the boot record exists and the PR carries the
dev-server comment). The walkthrough is about the diff, so it runs on the
branch you implemented, for that branch's PR only — lower layers of a stack
got theirs on their own turn.
- **On demand, by PR number** — `/walkthrough 9751`, "PR #9751에 walkthrough
달아줘" — for a PR this session did not implement, from any checkout. The
steps are section 1a; `mint.mjs --pr <n>` does the resolution.
- **Re-runs**: an implementation re-run that changes the UI re-mints and edits
the comment in place (section 0 covers the ones that do not).
### 1a. On demand for a PR by number
The branch path assumes the session is on the PR's branch with the diff in
its head. Given only a number, get both first:
1. **Is there a server?** `mint.mjs --pr <n> --dry-run` needs no manifest
and answers in one line (section 6): the live server that serves the PR, or
exit 3. It refuses a PR that is not open, so that check is not yours.
2. **No server** — boot one for `headRefName` with the `dev-server` skill,
from a checkout at the PR head: reuse a worktree already on that branch
only when this session made it or it is clean; otherwise
`git worktree add .claude/worktrees/<KEY> origin/<headRefName>` (where
`EnterWorktree` and `fw:cleanup-worktrees` keep them) and `pnpm install`
there. Say before booting that `advertise.sh` will comment the server's
URL on a PR this session did not implement. When the backend is
unreachable, that is a preflight failure here as everywhere: one line,
no walkthrough. Re-run the dry run once the record exists.
3. **A server on the layer above** — for a stack, the top layer's server
serves every lower PR and its head contains theirs; `mint.mjs` accepts
that (it says so on stderr) and the stops are verified against that
build. Only a server whose commit does not contain the PR head is refused.
4. **The diff.** Read the PR body's own summary first; it names what the
author thinks is visible, and often settles section 0 without the diff. Then
`gh pr diff <n> --name-only`, and read only the UI files it lists. Sections 3–5
apply unchanged.
5. **Mint and post** with `--pr <n>` (section 6) and `comment.sh … --pr <n>` (section 7).
The report's `pr` and `sha` come from GitHub, not from the current branch.
## 2. Preflight
Stop and say why, in one line, if any of these does not hold. A preflight
failure produces **no comment and no walkthrough**, not a partial one.
| Check | How |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The box has joined the dev gateway | `~/.config/fw/dev-gw.json` exists |
| A live server for the PR | the boot record `mint.mjs` resolves (section 6): this branch's, or with `--pr` the one that serves the PR |
| The server is routable | the record's `url` answers a 2xx with `X-Portless: 1` |
| The server has guided mode | `/__review/guided.js` answers 200; an older overlay (a branch that predates FR-3950) draws a stop as a bare pin without its notes, so `mint.mjs` exits 3 and says to rebase onto a main that includes it |
| The server serves a `config.toml` | `<url>/config.toml` answers with a content type other than `text/html`; `text/html` is the SPA fallback for a worktree without the file, so every switch is at its default and a stop behind one (the PR body's `Config:` line) would mark nothing — `dev-server` section 2f writes the file |
| The app shell survives login | `mint.mjs` checks it and exits 3 |
The set link goes in a public PR comment, so an unroutable server is a
preflight failure, not a reason to fall back to the record's `localUrl` — the
same refusal `advertise.sh` makes.
The last check is the one that actually bites, and it is about the **backend**,
not the server. Resolve the endpoint the way the `dev-server` skill does
(its section 2c: the PR description's named test server, then the shell/`.env` value,
then `config.toml`) and pass it as `--endpoint`; then verify the app shell
survives login — `mint.mjs` does, and exits 3 with one line when it does not.
A shell that dies leaves nothing to mint against. The symptom to recognize is
a backend whose schema the build is ahead of: the shell renders
`An error has occurred` and the console carries
`Cannot query field "scopes" on type "Role"`.
## 3. Write the stop manifest
A JSON file — `{"stops": [...]}` or a bare array — one object per stop:
```json
{
"stops": [
{
"route": "/data",
"find": { "text": "Create Folder" },
"type": "modified",
"kind": "button",
"ch": "The upload button moved from every row into the card header.",
"ck": "A \"Create Folder\" button shows at the top right, above the list.",
"old": "⬆ icon on every row",
"new": "\"Create Folder\" in the header",
"code": [{ "path": "react/src/pages/VFolderListPage.tsx", "line": 120 }]
},
{
"route": "/data",
"via": [{ "click": { "text": "Create Folder" } }],
"find": { "testid": "model-usage-mode" },
"type": "added",
"kind": "radio",
"ch": "The folder create modal gained a Models usage-mode radio.",
"ck": "The modal's usage mode shows a \"Models\" choice.",
"code": [
{
"path": "react/src/components/FolderCreateModal.tsx",
"line": 88,
"to": 104
}
],
"lng": "en",
"i18n": {
"ko": {
"ch": "폴더 생성 모달에 Models 사용 모드 라디오가 추가됐습니다.",
"ck": "모달의 사용 모드에 \"모델\" 선택지가 보여야 합니다."
}
}
}
]
}
```
- `route` — origin-relative, **below** the project scope (`/data`, not
`/project/<name>/data`). `mint.mjs` prepends the base the app lands on.
A page outside the project scope — the admin pages under `/admin/…` —
says `"scope": "app"` and is opened as written.
The link carries the project either way: each stop records the page path
it was minted on (`anchor.p`), after any redirect, and the set link opens
it. Project names differ per backend (the shared test box has `default`,
staging only `frontend-default`), and the minting login can land on
another project than expected. To pin one, write `"scope": "app"` with
the full path, `/project/frontend-default/deployments`. A project-less
flat route (`/deployments`) does not help: the app redirects to the
current project before the anchor is recorded.
- `via` — the steps that reveal the element, replayed in order. At most 8,
each exactly one of:
- `{"click": {"text": "…"}}` (exact visible text) or `{"click": {"tid": "…"}}`;
- `{"fill": {"label": "…", "value": "…", "enter": 1}}` — type `value` into
the field its label, `aria-label` or placeholder names (or `"tid"`, on the
field or on a wrapper holding only it); `enter: 1` presses Enter after;
- `{"select": {"label": "…", "option": "…"}}` — open the select (or
`"tid"`) and choose the option with that text.
A `fill` value is published in the PR comment's link, so the manifest
refuses one aimed at a password / secret / token / key field. Prefer a
`route` query over a `fill` when the page keeps the state in the URL (list
filters, sort, tabs): the reader lands on it with nothing to do. In an
`i18n` entry, a step lends the reader-language `text` / `label` / `option`
and the base keeps the testid; write the whole step, `value` included.
- `find` — `{"testid": "…"}` (preferred), `{"text": "…"}` on a control, or
`{"selector": "…"}` (a CSS selector, optionally with `"text"` to pick the
node whose text matches — an SVG label, a table cell).
- `label` — optional; without it the comment's head is
`Page › testid › tag "text"`, derived from the anchor.
- `lng` / `i18n` — always `"lng": "en"` with exactly one `i18n` entry, `ko`
(section 5); `manifest.mjs` refuses any other. Each extra language would add a
replay per stop at mint time. The `ko` entry needs `ch` and `ck`; `old`,
`new` and `via` fall back to the English ones when it omits them.
- Capture inside a `[role=dialog]` sets `dlg: 1` on its own — do not write it.
`scripts/manifest.mjs` validates the file before a browser starts and reports
every problem at once; the caps mirror the overlay's `stop-guard.ts`.
## 4. Choose the stops
- **One stop per change a person can recognize on screen** — a control that
appeared, moved or was relabeled, a new column, new state text, a changed
validation message.
- **N identical call sites → one stop** on the most representative one; name
the rest in that stop's `ch` ("…, in all three lists").
- **No code-only stops.** A hook, a test, an i18n key, a generated file has no
element. Those go to the PR description's **"Not shown in the walkthrough"**
list (`comment.sh describe --not-shown`), never into the manifest.
- **As few as cover the change, usually 1–5.** Each stop is a browser replay
at mint time and a step for the reviewer. 20 is the hard cap; group long
before it.
- **Order = the requester's flow**: the page where the feature starts, then
interaction order within it, then the page where the result shows.
Same-page stops stay contiguous, and a dialog stop follows the stop that
opens it.
## 5. Wording
- `ch` — what changed and how, **past tense**, one or two sentences, naming
the previous state when there was one. ≤ 280 chars.
- `ck` — **one** outcome the reader can verify by looking or with one click
("… shows …"). ≤ 280 chars.
- **`ck` states the condition that produces the new behaviour**, as value →
what shows: `A folder whose mount permission is "none" shows "Not mountable";
"ro" shows "Read only"`. When the connected backend cannot produce that value yet (the
feature is not deployed there), keep the condition and add one clause saying
what this server cannot show — and list it under "Not shown in the
walkthrough" (section 7). "Should look the same as before" is not a check: it
describes the unchanged branch and hides the one the PR added.
- `old` / `new` — literals, ≤ 40 chars each. Omit both when nothing was
replaced.
- **The PR reads English; the stop reads English or Korean.** Whatever the
chat language, the base fields are English with `"lng": "en"`, and the same
stop in Korean goes under `"i18n": {"ko": {…}}`; no other language is
written. The PR comment prints only the base fields, so it is always
English, as are `label` and the "Not shown in the walkthrough" list. The popover's EN/KO toggle switches the stop text
and the app's language together.
- **Each language quotes its own UI labels verbatim**: the English stop the
label in `resources/i18n/en.json`, the Korean one the label in `ko.json`.
Look both up rather than translating a label yourself. The translation says
the same thing about the same element; `old`, `new` and `via` fall back to
the English ones when the `ko` entry omits them, so give it only what reads
differently.
- **Write for the person looking at the screen, not for the code.** Name
what they see — the red line, the dotted line, the button's label, the
panel's title — and what it does now versus before. No function or
variable names, no file names, no "series", "scale", "convert", "÷10",
no internal terms; the `code` links carry that. A reader who has never
opened the source must be able to check the stop from `ck` alone. Say
"the dotted average line now sits at the real average; before it was ten
times too high", not "the reference line now goes through
`convertMetricUnit` like the plotted series".
## 6. Run it
```bash
node .claude/skills/walkthrough/scripts/mint.mjs \
--manifest /tmp/walkthrough.json \
--endpoint http://10.82.0.130:8090 \
--report /tmp/walkthrough-report.json
```
Which server, in one place: without `--pr`, the app is the name
`dev-server` claims for the current branch (`--app` overrides), the PR is
that record's `served[]` entry, `--sha` defaults to `git rev-parse HEAD`.
With `--pr <n>` the PR is looked up in `--repo` (default
`lablup/backend.ai-webui`, never the cwd's remote) and must be open; the app
is the live boot record that serves it — never stopped, pid alive, the same
repo — preferring the record on the PR's own branch over a stack layer above
it, then the newest boot; `--app` narrows that to one record; `--sha`
defaults to the PR head. Either way the server must serve the sha (its
`/__review/state.head`, else the record's worktree) or a commit that
contains it; a server behind the sha exits 3.
`--env-file` overrides where the admin account is read from (the server's own
checkout, then this one) — never print or commit it. `--dry-run` resolves
everything and launches no browser — without `--manifest`, for the one
question section 1a starts with.
Which backend: the one reviewers will sign in to, since the link's project
must exist there (section 3, `route`). The PR's dev server pre-fills one
backend and signs in by itself, so boot it on the same backend
(`pnpm run dev-env use <server> <account>`, then restart the server) and
pass that backend as `--endpoint`. `mint.mjs` signs in with
`E2E_ADMIN_EMAIL` / `E2E_ADMIN_PASSWORD`; a catalog server without an admin
entry (staging) needs an `--env-file` holding the account to use. Say in the
PR which backend and project the walkthrough assumes.
A translated stop carries the element's text (`txt`) per language, since
every resolution tier ANDs it: `mint.mjs` replays the stop once in each
language to read it. A `find` whose anchor is one testid unique on the page
needs no text, so that stop skips the per-language replays and mints in one
pass. That is the cheap path, and why `find` should name a `testid` (section 3).
The script logs in, replays each stop, mints the anchor with the overlay's own
in-page modules, builds the set link, then opens it in a **fresh page** and
checks each stop marks its element within 30 s **over the landmark it was
captured on** — the element is stamped `data-bai-change` (guided mode) or a
`.markbox` is drawn for it (the reviewer overlay). A mark that lands on another
testid, or on none, is a failure and goes to `couldNotPin[]` with its `ck`. Exit **0** with a link, **2** on a
bad manifest, **3** on preflight.
**One fix pass, then post.** When `couldNotPin[]` is non-empty, correct the
manifest once (a better `find`, a missing `via` step, a `route` query) and
re-run. Whatever still does not pin is posted under "Could not pin" with its
`ck`: the reviewer checks it by hand faster than a third mint finds it.
The report's `stops[]` carries each stop's wording read back off the _stripped_
anchor, so the comment says exactly what the link carries; a `dropped` list
appears when the guard refused a field, which validation means should never
happen. A stop whose anchor exceeds 2048 chars is refused rather than minted —
`parseFragments` would drop that part of the link silently.
## 7. Post it
```bash
bash .claude/skills/walkthrough/scripts/comment.sh upsert \
--pr <n> --report /tmp/walkthrough-report.json
bash .claude/skills/walkthrough/scripts/comment.sh describe \
--pr <n> --report /tmp/walkthrough-report.json --not-shown /tmp/not-shown.txt
```
`upsert` writes **one comment per PR**, found by
`<!-- bai-walkthrough v1 pr=<n> … -->` and edited in place on a re-mint. It
numbers and counts only the stops that **resolved**; the rest appear under
"Could not pin" alone. It carries the set link once — no
per-stop dev links, no `<!-- bai-review -->` marker, no `> 📍` quote block. A
stop is not a review finding, and `review-pins parse` leaves one out of its
findings unless asked with `--include-stops` (FR-3949).
`describe` upserts a `## Walkthrough` section in the PR description holding
`- [Walkthrough](<comment url>)` and the "Not shown in the walkthrough" list. It
rewrites that section and nothing else.
## 8. Report to the user
After today's two dev-server URL lines, add:
```
[Walkthrough](<set link>) · 6 stops
```
and, when some stop did not pin:
```
[Walkthrough](<set link>) · 6 stops (2 could not be pinned)
- Session start › resource slider — check: Step 2 shows a GPU slider.
- Data › sort indicator — check: The Name header shows a sort arrow.
```
Each unpinned stop keeps its `ck`, so the reviewer can still check it by hand.
A preflight failure, or a section 0 skip, replaces the whole line with the one-line
reason.
## 9. Out of scope
- **Never posts to Teams**, and never to Jira.
- **Never touches the dev-server comment** or its boot record — that comment
stays URL-only and separate (`dev-server` section 5 owns it).
- **Never marks a PR ready.** Draft → ready is the `fw:pr-ready-gate` skill's.
- **Never edits the PR description outside its `## Walkthrough` section**, and
never opens, closes, labels or reviews a PR.
## 10. Tests
```bash
node --test .claude/skills/walkthrough/scripts/manifest.test.mjs
node --test .claude/skills/walkthrough/scripts/resolve.test.mjs
bash .claude/skills/walkthrough/scripts/test-comment.sh
```
Pliki w paczce (8)
- SKILL.md 21 KB
- scripts/comment.sh 8 KB
- scripts/manifest.mjs 9 KB
- scripts/manifest.test.mjs 8 KB
- scripts/mint.mjs 41 KB
- scripts/resolve.mjs 3 KB
- scripts/resolve.test.mjs 5 KB
- scripts/test-comment.sh 11 KB
Wersje
| Repozytorium | Wynik | Licencja |
|---|---|---|
| Ta strona · lablup/backend.ai-webui | 100 | LGPL |
| oborchers/proqi | 100 | MIT |
| frolic/repo-defaults | 100 | MIT |
| ryanb/dotfiles | 100 | MIT |
| glebis/humane-agentic-design | 100 | MIT |
| rustyrazorblade/skills | 100 | Apache-2.0 |
| udecode/kitcn | 100 | Apache-2.0 |
| smallnest/goal-workflow | 100 | MIT |
| adamos486/skills | 100 | MIT |
Migawka bazy z 13.11.2026 · wersja paczki c3fb274977d9 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100aw-create-walkthrough
Tworzy jednostronicowy przegląd zakończonej pracy w pliku walkthrough.md: co się zmieniło, jakie przyjęto założenia i jakie są dowody, przed szkicem pull requesta. - 100v1-pr-walkthrough
Tłumaczy pull request lub gałąź w formie wizualnego przeglądu, krok po kroku, dla innych osób w zespole. - 100pr-walkthrough
Generuje jeden plik HTML z przewodnikiem po PR-ze: cel, wpływ na użytkowników, zmiany w interfejsie i ryzyka kompatybilności. - 95pragma-walkthrough-ask
Odpowiada na pytania o przewodnik Walkthrough w Pragma ADE, po wcześniejszym odczytaniu jego kroku w CLI. - 90bmad-walkthrough
Prowadzi użytkownika przez przegląd zmiany: po co jest, na co patrzeć uważnie i jak ją przetestować. - 90bmad-walkthrough
Prowadzi użytkownika przez przegląd zmiany: po co jest, na co patrzeć uważnie i jak ją przetestować.