Qa Manual

---
name: qa-manual
description: Living user / configuration manual generated by an agent that actually operates your app — the same drive-your-app engine as qa-explore, pointed at a different output (docs instead of bugs). It recons the app, ORDERS the features into a real setup/usage sequence, proposes a table of contents + audience for you to approve, then walks the happy path in that order, screenshots and annotates every step, and assembles one coherent Markdown manual. The Markdown is the master, so it re-generates when the UI drifts instead of rotting. Use when asked to "write the manual", "document the app", "generate the user guide", "make an onboarding guide", "config/installer manual", or "update the docs to match the app".
---

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