From 8b6dae8181d766321973feae41416ee6100a0890 Mon Sep 17 00:00:00 2001 From: Phillip Tarrant Date: Wed, 1 Jul 2026 13:44:00 -0500 Subject: [PATCH] Skills update --- chapter-workflow/SKILL.md | 13 ++++++++++ playwrite-testing/SKILL.md | 52 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) create mode 100644 playwrite-testing/SKILL.md diff --git a/chapter-workflow/SKILL.md b/chapter-workflow/SKILL.md index a8dcde2..b9094c8 100644 --- a/chapter-workflow/SKILL.md +++ b/chapter-workflow/SKILL.md @@ -109,6 +109,14 @@ Propose a scene-by-scene plan: - Opening hook and closing beat - Timeline placement (what day, what bells) — cross-reference with `timeline-book{BOOK}.md` +**Callback pass (BOOK ≥ 2 only):** Consult the Key Callbacks table in `chapters/book{BOOK}/CLAUDE.md` and this chapter's entry in `outline/book{BOOK}-outline.md`. List every prior-book reference the scene plan will land. For each, classify: + +- **Inline backfill** — a new reader needs a one-sentence Phelan-voice reminder. Mark which scene carries it. +- **Texture only** — name drop or atmosphere; no backfill needed. +- **Intentionally opaque** — institutional/thriller opacity is the point. Note that choice is deliberate. + +Present the classification to the author alongside the scene plan. Opaque choices need explicit approval. If `BOOK == 1`, skip this pass. + **Wait for author approval before proceeding to Stage 3.** ## Stage 3: Draft @@ -158,6 +166,9 @@ Before writing scenes involving these elements, consult: - Named location details → `world/locations/{name}.md` - Magic system usage → `world/magic/runic-flow-rules.md` and `world/magic/exploits-log.md` - Prior chapter state → `world/story-summary-book{BOOK}.md` +- Prior-book callbacks (BOOK ≥ 2) → `chapters/book{BOOK}/CLAUDE.md` Key Callbacks table + `world/story-summary-book{N}.md` for each prior book. Apply the Stage 2 callback classification: write the inline backfill sentence where planned, using Phelan's established backfill patterns (functional explanation without source attribution; consequence-driven reference; carrier character encoding history). + +**Inline backfill length cap:** one sentence, Phelan's voice, no source attribution ("the Floundry job," not "in Book 1 I…"). If a callback needs more than one sentence, the Stage 2 scene plan should have flagged it as a dedicated beat, not inline. When uncertain, mark `[CONTINUITY FLAG: note]` inline rather than guessing. @@ -174,6 +185,7 @@ Before saving the draft and telling the author it's ready, run this pass: 3. **Paragraph-opener scan:** Read only the first few words of each paragraph. Flag any cluster of identical openers. 4. **Continuity scan:** Verify any time references, currency amounts, character-knowledge claims, and location details against the canonical files listed in the continuity pre-check. 5. **Crutch construction scan:** Search the chapter for the construction templates above. Trim any that cluster. +6. **Callback scan (BOOK ≥ 2):** For every prior-book reference in the draft, confirm it matches the Stage 2 classification. Add any missed callbacks to the list and either backfill (one sentence, Phelan-voice, no source attribution) or flag as deliberately opaque. Fix issues before handing off. The less manuscript-analysis finds post-hoc, the better. @@ -196,6 +208,7 @@ The author has edited `chXX-draft.md`. Now perform a final review focused on: - Crutch constructions over quota (*"X the way Y [verb] X"*, anaphoric *"It was [noun] of someone who…"* pairs, *"The X was not X. The X was X…"* architecture, *"I did not X. I did not Y…"* clusters, *"Not X. Not Y."* opener counts) - Paragraph-opener clusters (3+ consecutive paragraphs with the same opener) 9. **Noise parenthetical discipline** — verify count within target (4–6 establishing, 3–5 ongoing) and that each does narrative work; flag any consecutive parentheticals not demanded by pacing (hyperfocus, crash, action spike) +10. **Callback handling (BOOK ≥ 2)** — for each prior-book reference in the chapter, verify it matches its Stage 2 classification. Inline-backfill callbacks must read cleanly for a reader who has never seen the prior book; opaque callbacks must be deliberate, not accidental. Flag any unclassified callback that slipped in during drafting. **Output format:** Present findings organized by category. For each issue, quote the relevant text and suggest a fix. After author approval of any changes, **rename** `chXX-draft.md` to `chXX-final.md` using `mv` — do NOT rewrite the file contents. diff --git a/playwrite-testing/SKILL.md b/playwrite-testing/SKILL.md new file mode 100644 index 0000000..403ec5b --- /dev/null +++ b/playwrite-testing/SKILL.md @@ -0,0 +1,52 @@ +--- +name: browser-testing +description: Use when asked to test a web UI in a real browser — verify a page renders, click through a user flow, check a login/form works, confirm a homelab service's web interface is up, or do end-to-end/browser testing. Drives the homelab Playwright MCP server (headless Chromium on 10.10.20.39). Do NOT use for scraping/extracting page content (that's firecrawl on the webtools box). +--- + +# Browser testing with the Playwright MCP + +Interactive browser testing is done through the **Playwright MCP server** — a real +headless Chromium the homelab runs for exactly this. Prefer it over guessing whether a +UI works, and over `curl` when the check needs a rendered page, JS, clicks, or forms. + +## Prerequisite: the MCP must be connected + +The Playwright tools only exist if this machine has the MCP registered. Check with `/mcp` +(look for `playwright`) or `claude mcp list`. If it's missing, tell the user to run: + +```bash +claude mcp add --transport http playwright https://playwright.home.sneakygeek.net/mcp -s user +``` + +(Full setup/verification: `docs/playwright-mcp.md`.) Do not try to install or launch a +browser locally — testing happens on the remote box, not this host. + +## How to test (the loop) + +1. **Navigate** to the target URL. +2. **Snapshot first, screenshot second.** Take an *accessibility snapshot* to read page + structure/text and get element refs — it's the source of truth and far cheaper than + pixels. Only take a screenshot when the user needs a visual, or to debug layout. +3. **Act on refs** from the snapshot (click, fill, select, press), then **re-snapshot** to + observe the result. Don't assume an action worked — verify from the new state. +4. **Assert against observed state**, not assumptions: confirm the expected text/element is + present, the URL changed, the error is gone, etc. Report what you actually saw. +5. **Wait explicitly** for slow/async pages (wait for a selector/text) instead of retrying + blindly. Ad-heavy or SPA pages need a beat after navigation. + +## Homelab specifics + +- Internal services use `*.home.sneakygeek.net` (e.g. `todo.home.sneakygeek.net`, + `grafana.home.sneakygeek.net`, `gatus.home.sneakygeek.net`). These resolve only via the + internal AdGuard DNS — the MCP box is on VLAN 20 and can reach them. +- **Headless Chromium only** (the Docker image supports nothing else) — don't request + firefox/webkit/headed mode. +- Sessions cost memory (each is a Chromium; the container is capped at 4 GB). When done, + **close pages/contexts** you opened so the box stays clean for the next run. +- Credentials: ask the user for logins; never hardcode. Vaultwarden holds real secrets. + +## When NOT to use this + +- **Just need page content / markdown / a crawl?** That's **firecrawl** (`http://10.10.20.37:3002`, + or `firecrawl.home.sneakygeek.net`), not this. Playwright MCP is for *interactive* testing. +- A plain reachability/HTTP-status check is fine with `curl` — don't spin up a browser for it.