ui-walkthrough

Files (16)

• SKILL.md
• behavior.md
• capture.md
• concurrency.md
• coverage.md
• dev-credentials.example.md
• driver.md
• embedded.md
• evaluate.md
• evidence-hosting.md
• opencap.md
• post-and-report.md
• preview-contract.md
• stack.md
• target-selection.md
• windows.md

SKILL.md (first lines)

# ui-walkthrough

## Input / modes

Treat text accompanying the skill invocation as the input:

| Invocation | Behavior |
|---|---|
| Empty | The PR for the current branch (`gh pr view --json number`). Errors when there is none. |
| `<PR#>` | That PR (resolves to `Atllas-Inc/codebase` unless `--repo`). |
| `<URL>` | Parse owner/name/number from the URL. Unambiguous. |
| `--author` / `--reviewer` | Force the role. Default: inferred from `author == ME` (see Phase 1). |
| `--viewports=desktop,tablet,mobile` | Default all three. Any subset. |
| `--personas=premium[,free,admin]` | Default `premium`. Each extra persona is one extra login, not a second stack boot. |
| `--target=e2e\|dev` | Which stack to walk. **Always defaults to `e2e`**, in every role and environment. `dev` runs only when this flag is typed, see [target-selection.md](target-selection.md). |
| `--lane=N` | Which port lane to boot on. Default: the first free lane. See [concurrency.md](concurrency.md). |
| `--surfaces=/a,/b` | Skip discovery, walk exactly these routes. Semantics in Phase 3. |
| `--no-post` | Assemble the report and print the exact payload. **Post and publish nothing.** |
| `--no-video` | Skip the walkthrough video even when available (local macOS or Windows, either role). See *Video capability* in Phase 0. |
| `--embedded` | Called by another skill: return findings, **post nothing**. See [embedded.md](embedded.md). |

### Repos this skill can walk

`Atllas-Inc/codebase` walks on the sealed `e2e` stack. `Atllas-Inc/aicc-queues` has no frontend.
**Read [preview-contract.md](preview-contract.md) at Phase 0 when the checkout has a
`walkthrough.json` at its root** (`neema-simple-hyzl`, `pointsgpt`): it owns that repo's target,
boot, personas, routes, states, iOS screenshots, and evidence label. The repo owns its boot command.
Any other repo: neutral note.

---

## Core invariants (do not weaken)

1. **Every finding is evidence-bound.** Report a finding only when a screenshot captured this run
   shows it, on a **healthy, identity-verified** stack (Phase 4), or a deterministic detector
   (Phase 5b) fired it and you attach the output. "Looks like it might overflow" is not a finding.
2. **Infra failure is never a finding.** Ports busy, stack did not boot, credentials missing,
   emulator crashed -> **neutral note**, walkthrough skipped. "Did not boot on my machine" is not
   "PR is broken".
3. **Only *detected* defects can block.** Deterministic detector output (Phase 5b: horizontal
   scroll, touch target < 44px, console error, clipped text) and a failed mechanical behavior
   assertion (Phase 5d) can drive `REQUEST_CHANGES`. **Judged** findings
   (taste, hierarchy, spacing, "this feels off") are *always* non-blocking commentary, no matter
   how confident.
4. **The role determines the GitHub post primitive.** GitHub **422s**
   `REQUEST_CHANGES`/`APPROVE` on your own PR, so author mode is comment-only. Reviewer mode posts a
   review. A repository-specific destination follows [evidence-hosting.md](evidence-hosting.md).
5. **This skill never posts `APPROVE`.** It looked at pixels, not logic. Approval is `/review-pr`'s
   call. A clean walkthrough posts a `COMMENT` + proof screenshots and *supports* an approval it
   does not grant.
6. **Never boot onto a stack you did not start.** `playwright.config.ts` sets
   `reuseExistingServer: true`. A foreign server on the lane's FE port gets screenshotted in
   silence, and the evidence then "proves" whatever was already running. Free-or-abort (Phase 4).
7. **`e2e` is the target. `dev` is a typed opt-in.** The sealed stack (local emulators, stubbed
   externals, seeded personas, per-run state) is the default in **every** role and **every**
   environment. `dev` is a shared backend: it can fire real Stripe/Vapi/Twilio calls, its data
   drifts so the evidence is not reproducible, other users' records land in screenshots
   **published** to everyone with repo access, and one walkthrough occupies the port the operator's
   own dev server needs. `dev` therefore runs only when a human types `--target=dev` or exports
   `UIW_TARGET=dev`. **Never** infer it, **never** fall back to it, **never** use it in reviewer
   mode. **Never** staging, **never** production, under any role. `/full-send` holds the one
   autonomous exception, defined in `full-send/evidence.md`.
8. **Never take a lane you did not win.** Ports, the stack lock, the `browse` daemon, and the
   scratch dir are all lane-scoped so two walkthroughs can run at once
   ([concurrency.md](concurrency.md)). Take one lane, hold it for the whole run, release it in
   teardown. Never touch another lane's ports, processes, or lock.
9. **Never touch source, the index, or the PR branch.** Phase 7 publishes screenshots through the
   repository's approved evidence destination.
10. **Never post a REVIEW to a draft PR**, and **never review your own**. Re-check both immediately
   before posting, not just at discovery. **Author mode is exempt from the draft half**: the rule
   exists to stop unrequested reviewer noise on unready work, and an author commenting evidence on
   their own draft is neither unrequested nor noise. Reviewer mode still skips drafts outright.
11. **Coverage is measured in changed components.** A route can render perfectly, return 200, and
   show none of the diff, because the changed component sits behind a tab, a state, or a document
   shape the fixture never created. Every changed file under `pages/`/`components/` must be proven
   on screen by a mount probe in at least one captured shot (the Phase 3 ledger, probed in 5a). A
   component that never mounted is reported as uncovered, by file name, in the posted Coverage
   block. It is never counted as walked because its route was captured.

### Severity -> what happens

| Class | Source | Reviewer mode | Author mode |
|---|---|---|---|
| **BLOCKER** | detector fired, or the surface failed to render, or a console error attributed to this PR, or a mechanical behavior assertion failed | inline on the diff + `REQUEST_CHANGES` | flagged in the comment as self-caught |
| **MEDIUM** | judged inconsistency, visible in a screenshot | inline + `COMMENT` | listed in the comment |
| **NIT** | polish | local report only | local report only |
| clean | none | proof comment + `COMMENT` | walkthrough comment |

**A screenshot alone produces a BLOCKER only when the surface fails to render**: blank page, error
page, or an HTTP 4xx/5xx response for the route. Every layout, spacing, contrast, alignment, and
hierarchy judgment is **MEDIUM at most**, in both modes, however obvious it looks.

---

## Writing style

Copied verbatim from `~/.claude/CLAUDE.md`, which a headless run never loads.
Binding on every body posted in Phase 8, both modes, and on the Phase 9 report.

When you write technical text (documentation, READMEs, runbooks, procedures, error messages, release notes, reports), write plain English in the spirit of ASD-STE100 Simplified Technical English, so that a smart reader outside the field understands it on one read. Obey these rules:

CLASSIFY FIRST. Procedural text tells the reader what to do: imperative mood, maximum 20 words per sentence, one instruction per sentence. Descriptive text explains: simple tenses, maximum 25 words per sentence, one topic per paragraph, maximum six sentences per paragraph. Never mix the two in one passage.

PLAIN WORDS, for replies and for explanations written for readers outside the field. Use the common word when one exists ("use", not "utilize"). Define a concept term at its first use, in under ten words, at most one per sentence: "idempotent (safe to run twice)". Do not define product names, standard names (Postgres, S3, HTTP), or the tool the document is about. Address the reader as "you". Lead with the point. Procedures and reference documents follow the rules above alone.

VERBS. Use only: infinitive, imperative, simple present, simple past, simple future, past participle as adjective. No present perfect ("has completed" → "completed"). No "-ing" verb forms ("making it easy" → new sentence). Active voice; passive only in descriptions when the agent is unknown. Approved modals: can, will, must. Banned: should, would, may, might, could. For "should": write "must" if required, delete if optional.

SENTENCES. Keep complete grammar: no contractions, keep articles, keep "that" ("make sure that the file exists"). Put conditions before commands, with a comma: "If the test fails, read the log." No semicolons: write two sentences. No em-dashes: an em-dash hides the logic between two statements. Name the relation ("because", "but", "for example", "that is") or write two sentences. Use a vertical list for more than two items or steps.

WORDS. One word, one meaning, for the whole document: use "make sure that" for check/verify/confirm, and "configuration" for config/settings. Noun chains of maximum three words. Break longer ones with prepositions ("the timeout value for the connection pool"). Delete words that carry no fact: simply, seamlessly, robust, powerful, comprehensive, leverage, delve, pivotal, "in order to", "it is worth noting". Do not open or close with chat filler: "in conclusion", "in summary", "let's dive in", "that being said", "I hope this helps".

AVOID THE AI DRIFTS. Guard against these by direction: inflated significance ("crucial", "a testament to"), "not just X, it is Y" reframes, decorative triplets, vague attribution ("studies show"), "it is important to note" asides, and formatting habits (no emoji as structure, no boldface as decoration). State the fact. The fact carries itself. Replace: utilize → use, prior to → before, in the event that → if, e.g. → for example. American spelling.

WARNINGS. Command or condition first, then the risk: "Do not run this against production. The command deletes rows."

NEVER TOUCH. Code blocks, identifiers, CLI commands, file paths, quoted error messages, product names. Each counts as one word toward sentence limits. Facts too: when the source does not give a number or a cause, keep the general statement — do not invent specifics.

SELF-CHECK before returning: scan for contractions, "has been", "should", ", making", semicolons, em-dashes, and the deleted-word list above. Count words in your three longest sentences and split any over the limit. Collapse synonym rotation.

From ptrandev/agent-skills, MIT.

More from ptrandev/agent-skills