qa-manual

The same engine that drives your app to find bugs (qa-explore) can drive it to document it. Instead of a bug report, the output is a living manual: a coherent, screenshot-annotated guide walked in the order a real person would use the app.

recon the live app  →  ORDER the features as a real setup/usage sequence
                    →  propose a Table of Contents + AUDIENCE          [GATE 1: you approve]
per section, in order:  drive the app to that view → screenshot → annotate the steps
                    →  assemble ONE coherent Markdown manual (one clean example throughout)
                    →  draft ready                                      [GATE 2: you review before it ships]
Markdown is the master → re-run when the UI drifts → docs update instead of rotting

What makes it a good manual (not a screenshot dump)

• Setup order, not file order. Dependencies/prerequisites first; each section builds on the previous. The recon step reorders whatever it discovers into the sequence a human actually follows.
• One coherent example throughout. The same clean sample data/flow runs across the whole manual, so screenshots tell a single story instead of contradicting each other.
• Audience is a knob. The same app yields an installer / configuration guide or an end-user / daily-use guide by setting audience (which also reshapes the TOC and the depth of each step).
• Every screenshot is annotated with what to do and what to notice — captured from the real app, never mocked.
• It won't document a broken flow. If a section's happy path hits a blocking bug, qa-manual flags it and leaves that section out (or marked "known issue") rather than teaching a broken path — run qa-explore/qa-fix first.

🔒 The two gates (never publish auto-docs blind)

1. Approve the TOC + audience up front. The engine returns a proposed table of contents and audience; you edit/approve it before a single screenshot is taken. This is where you catch "wrong order", "wrong audience", "skip this section".
2. Review the draft before it ships. The Markdown master is handed back for a human read before it becomes the published manual. Docs that go out unread are how wrong instructions reach users.

Engine (invoke via the Workflow tool; do not inline)

• ${CLAUDE_PLUGIN_ROOT}/skills/qa-manual/engine/qa-manual.workflow.js

(If $CLAUDE_PLUGIN_ROOT is unset, the skill is at ~/.claude/skills/qa-manual — resolve the engine path relative to this SKILL.md.)

Prerequisites

• The same qa.config.json qa-explore uses (baseUrl, appPath, login, shotsDir, viewports, projectType). No tracker or E2E dir needed — this writes docs, not tests.
• Two manual-specific knobs (in a manual block, all optional):
  • audience — "end-user" (default) or "installer" (config/admin guide). Reshapes the TOC + step depth.
  • outFile — where to write the master, e.g. docs/manual-usuario.md (default docs/manual.md).
  • title, product, brand — cover copy.
  • sampleHint — one sentence describing the clean example to use throughout (e.g. "a fictional client 'Demo SL'"), so screenshots stay coherent.
• Runs against a running app. Credentials come from env (QA_EMAIL/QA_PASS or the login recipe) — never inline them in the config.

How to run

1. Resolve config. Load qa.config.json; confirm the login works (don't print secrets). Pick the audience (ask the user if unclear — an installer guide and an end-user guide are very different documents).
2. Recon → propose TOC (GATE 1). Run the engine with no toc: Workflow({ scriptPath: "<engine>/qa-manual.workflow.js", args: { ...config, manual: { audience, ... } } }). It explores the app and returns { audience, toc: [{ key, title, goal }], notes }. Show the user the TOC + audience and get approval/edits before continuing. Do not screenshot anything yet.
3. Capture + assemble. Re-run the engine with the approved toc in args.manual.toc. It walks each section in order (driving the real app), screenshots + annotates, and assembles one coherent Markdown master at outFile, with the shared example throughout. Sections whose happy path is blocked by a bug come back flagged, not faked.
4. Review the draft (GATE 2). Read the returned Markdown before publishing. Fix wording/order if needed (edit the master and re-assemble, or re-run just the affected section).
5. Ship the format the user wants. The master is Markdown. If they want a single self-contained file to hand over (e.g. email an HTML with screenshots embedded), bundle it as a last step (base64-inline the images). Flag if any screenshots contain real personal data — a manual full of real contacts should be delivered directly, not committed to the repo.
6. Report back. Summarize: audience, sections written, any section flagged (blocked by a bug → point at qa-explore/qa-fix), and where the master + screenshots live.

Re-generating when the UI drifts

The Markdown is the master; the screenshots are regenerated, not hand-pasted. When the app changes, re-run step 3 (optionally scoped to the sections that changed) and the manual updates instead of rotting. Keep the approved toc in the config to skip GATE 1 on routine refreshes.

Where it fits

qa-explore finds bugs · qa-heal keeps the suite honest · qa-fix fixes the bugs · qa-manual turns the same "an agent that operates your app" engine into docs that stay true to the app. A flow with an open bug gets fixed first, then documented — the manual never teaches a broken path.

Notes

• Human approves twice (TOC, then draft). qa-manual never publishes unread.
• Never invents UI. Every step and screenshot comes from driving the real app; if something can't be reached, the section is flagged, not fabricated.
• Personal data aware. If the app shows real user data, the shared clean example should use fictional/sample records where possible; when real data is unavoidable in a screenshot, the skill flags the output as "deliver directly, do not commit".
• Cadence: on demand (/qa-manual) and after shipping a feature that changes a documented flow.