Demonstrate Issues

Demonstrate Issues (HMIS)

🚨 TOOLS: Playwright MCP is the default (mcp__playwright__*). Every step below is written for Playwright's plain tool names (browser_navigate, browser_snapshot, browser_take_screenshot, ...) — don't reach for claude-in-chrome out of general habit. The mcp__claude-in-chrome__* tools in the allowed-tools frontmatter exist only for the discussed fallback below, not for casual use. If Playwright genuinely isn't usable in the environment (MCP server unavailable, the browser won't launch, etc. — a headless box the user simply can't watch is not such a case; drive it click-by-click per step 2), discuss it with the user first rather than silently switching — they may prefer to solve the Playwright-side blocker (e.g. relay screenshots) over falling back. Only switch tools after they say so.

If the claude-in-chrome fallback is approved: use the mcp__claude-in-chrome__* tools for navigation, page inspection, and form input; don't call Playwright-only tools. Two steps have no fallback equivalent — handle them explicitly rather than skipping silently:

• Screenshot capture (step 3): take the shot with mcp__claude-in-chrome__computer; if it can't be written into the session's tmp/ subfolder, ask the user to save/relay the image, and if even that isn't possible record the demo's evidence as "screenshot unavailable (claude-in-chrome fallback)".
• Native confirm()/alert() (step 3, "Native JS dialogs mid-demo"): there is no browser_handle_dialog equivalent and the dialog blocks the extension — pause and ask the user to resolve it manually in their browser, then continue.

🚨 LOGIN: ask, don't assume. At step 2, once the login page is open, ask the user directly whether they want to log in themselves or have Claude log in and proceed — don't silently default to either one. Only look up credentials or drive the login form after they've said they want Claude to do it.

Structurally separates three phases with hard stops between them: demonstrate → investigate → file. This exists to prevent acting on a partial picture — jumping from "here's a bug" straight to code before every bug the user wants to show is on the table, and before the full picture of each one is understood.

Non-goals

• No development or fixing ever happens inside this skill. It ends at filing GitHub issue(s). Any actual fix is separate, later work — hand the filed issue number(s) to dev-issue.
• Does not change the behavior of dev-issue, playwright-e2e, or any other skill — they keep auto-logging in with Playwright and driving the browser themselves by default, no question asked. The ask-before-login and discuss-before-tool-fallback rules below are local to this skill only.

Reference docs

• Playwright E2E Testing Workflow — PrimeFaces widget commit patterns, dialog handling, the §1 login/department gate, the §2 never-navigate-by-URL rule (the user drives here, so follow their menu path and record it — never "shortcut" to a page by URL when reproducing later; a URL-loaded page renders against uninitialised session state and yields a bug report that isn't real), and the §8/§8a screenshot-privacy-check convention this skill reuses for evidence capture.
• Playwright MCP Guide — generic MCP tool mechanics (clicking, dropdowns, common errors).

1. Deploy check (environment-agnostic — never hardcode names/ports)

• Resolve the WAR path deterministically each run: prefer <finalName> from pom.xml over globbing. Only fall back to target/*.war if pom.xml doesn't resolve one, and if that glob matches more than one file, treat it as the "ambiguous working tree state" case below rather than guessing which one to use — never assume a fixed filename like rh-3.0.0.war, the version differs across checkouts/machines.
• Resolve the Payara admin port and the app's HTTP port from the local credentials file for this machine (C:\Credentials\credentials.txt or equivalent) — never assume the defaults (4848 / 8080). Multiple Payara installs can coexist on one box on non-default ports (see playwright-e2e-workflow §27). Don't Read the whole credentials file into context — it may hold passwords/tokens alongside the ports. Extract just the port line(s) (e.g. grep/findstr for the admin-port/http-port keys) and use only those values.
• Resolve the deployed context root / URL path via asadmin --port <admin-port> list-applications rather than assuming /rh — different instances are deployed as /rh, /hmis, /coop, etc.
• Compare the resolved WAR's build time against git log -1 (HEAD) — mtime alone doesn't prove the WAR was built from HEAD, so also check git status --short and record the current commit SHA alongside it. If the running app is behind HEAD, rebuild (mvn clean package -DskipTests, JDK 11) and redeploy automatically using the resolved admin port/app name — see §0a. Only pause and ask if the build fails or the working tree state is ambiguous (e.g. uncommitted changes on a file that affects the build, or more than one candidate WAR as above).

2. Open login page, then ask how to handle login

• browser_navigate to the resolved login URL.
• Ask the user whether they want to log in and select department themselves (e.g. in a visible Playwright-launched browser window, or by directing Claude click-by-click if the browser isn't visible to them), or whether they'd rather Claude look up credentials and log in/select department on its own, same as playwright-e2e's normal login flow.
• Don't assume either way, and don't look up or enter credentials before they've said Claude should.
• Wait until login and department selection are actually complete before starting the demonstration loop. If the user handles it, pause until they confirm both steps are done (or the browser clearly shows the authenticated post-department landing page). If Claude handles it, proceed only once that landing page is reached. The shared workflow requires a selected department before any inner-page action — continuing early makes the demos run against unauthenticated / wrong-department state and produce false failures.

3. Demonstration loop

• The user narrates/points out each issue in chat while driving the browser themselves (e.g. "see this — clicking X should do Y but does Z").
• On the user's cue, capture:
  • an accessibility snapshot (browser_snapshot)
  • a screenshot (browser_take_screenshot) into the project tmp/ folder, one subfolder per session
  • the user's description, verbatim
  • auto-detected environment context: department and user role read from the page header (not the raw account/login name), current git branch + commit SHA (git rev-parse --abbrev-ref HEAD / git rev-parse HEAD), timestamp
• Pure capture only at this stage — no code investigation yet. Confirm each capture ("Got it, recorded as demo #N") and wait for the next cue or the end signal.
• Multiple issues can be demonstrated in one session, back to back.

Content-free capture cues

If the cue to capture carries no description at all (e.g. just "capture", or "check playwrite"), don't capture speculatively and ask afterward what it was for — ask for the one-line description. If the user provides it in the same turn, capture the demo; otherwise wait and do not capture until the description is available.

Forward-looking narration vs a firm bug cue

Distinguish "I'm about to show you X" (scene-setting for a demo that hasn't happened yet) from "see this, X is broken" (the actual cue). Narration that describes what's coming next is not itself a capture cue — wait for the concrete bug before recording anything.

The same non-capture handling applies to plain navigation/setup instructions interspersed between demos — "go to inpatient dashboard", "click room details", "now click admit" — where the user is just directing the browser to the next thing worth showing, with no bug implied. Follow the instruction, but don't treat it as a capture cue on its own; wait for the user to actually point out a problem.

Keep a running navigation breadcrumb, even when not capturing

The user is driving the browser, not you — when they say "I'm on page X" or narrate a click, you often can't reconstruct that path from code (it may depend on session state: a selected patient, department, in-progress form) and the user may not be able to repeat the exact clicks on request. Losing the trail forces them to redo manual navigation, which defeats the point of letting them drive.

So on every non-capture navigation/narration turn, silently note (don't announce it — this isn't a capture, just a running log) the menu path/button clicked and, if visible from context already in front of you, the resulting page's title and URL. Don't spend an extra browser_snapshot call purely to fill in this log — use whatever page context you already have (the last snapshot/screenshot taken, or the user's own words). If a hop's destination truly isn't inferable that way, leave it unlabeled rather than interrupting the flow to ask; a gap in the trail is better than breaking the user's narration to ask a tracking question.

Sanitize before storing, not just before filing. URLs and page titles/breadcrumbs routinely carry patient identifiers (BHT number, PHN, patient name) even at this scratch stage — strip or generalize those as you log each hop (e.g. BHT/56757 → [selected admission]). Don't rely on the step-7 filing-time redaction pass alone for this: by then the trail has already been promoted into "Steps to reproduce" text, so anything left unredacted here flows straight into the draft issue body.

Keep only the trail since the last completed capture (or session start, whichever is more recent), most recent step last — this is scratch context, not a demo record, and applies to whatever workflow is being demonstrated, not just inpatient/admission ones. When a demo is actually captured — not merely cued; a content-free cue (previous section) leaves the trail open while it waits for the required description — that trail becomes the "Steps to reproduce" backbone for that demo. Clear it once the capture is consumed, so a later demo in the same session doesn't inherit an earlier demo's steps. Any trail still open at session end is simply discarded.

If a capture already happened and the user later clarifies that demo #N was not meant as a bug report (e.g. "no error in this page yet, just gathering facts"), treat that as an explicit instruction to drop the prior capture — whether that clarification arrives in the very next message or a later one: acknowledge it ("Dropping demo #N — noted as context only") and exclude it from the investigation/filing phases. Don't carry the ambiguity forward and make the user re-resolve it during investigation.