Przejdź do treści
Biblioteka skilli
Programowanie · Przegląd i audyt

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ć.

Licencja
LGPL
Ostatnia zmiana repozytorium
28.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
8
Skrypty
7
Komentarze HTML
2
Adresy URL w SKILL.md
1
Przestarzałość

Brak sygnałów. Repozytorium zmienione 28.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

LGPL, otwarta.

Co sprawdzić przed instalacją
  • 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

walkthrough 만들어줘make a walkthroughPR #N에 walkthrough 달아줘add a walkthrough to PR #N
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

  1. 0. Is it needed?
  2. 1. When to run
  3. 2. Preflight
  4. 3. Write the stop manifest
  5. 4. Choose the stops
  6. 5. Wording
  7. 6. Run it
  8. 7. Post it
  9. 8. Report to the user
  10. 9. Out of scope
Sekcje z nagłówków SKILL.md, w oryginale · 377 linii, 3 166 słów
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

RepozytoriumWynikLicencja
Ta strona · lablup/backend.ai-webui100LGPL
oborchers/proqi100MIT
frolic/repo-defaults100MIT
ryanb/dotfiles100MIT
glebis/humane-agentic-design100MIT
rustyrazorblade/skills100Apache-2.0
udecode/kitcn100Apache-2.0
smallnest/goal-workflow100MIT
adamos486/skills100MIT

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ć.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.