agentleFS
jamesblackwelljamesblackwell/falcondeck/.agents/skills/qa-spider/SKILL.md

qa-spider

Skill7 starsChanged 8 days agoMITView on GitHub

Extensive document-only UI QA spider. Inventory every reachable route or screen, then drive the real UI in a browser route-by-route and interaction-by-interaction, logging each bug with a screenshot. Use when the user asks for a full QA pass, QA spider, route-by-route audit, UX/UI audit, test every page, spider the app, exhaustive QA, mobile or desktop QA sweep, or runs /qa-spider. Do not use for a single-bug repro, a one-flow smoke test, or to implement fixes (this skill documents only).

The file

Show its rules and text

We split this skill into the rules it gives an agent

23 rules. About 0 are common, 19 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈19

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Document only. Do not change application code, CSS, copy, or tests.

    line 24
  2. Very specific:

    If a row cannot be tested, write BLOCKED or SKIPPED with the reason.

    line 29
  3. Distinctive:

    Do not mark a route done because a nearby route "looked the same".

    line 30
  4. Distinctive:

    Do not stop after N bugs, after the core journey, or because the report "looks substantial".

    line 31
  5. Very specific:

    If docs/qa/ already has an in-progress report for this request (Resume points at a next row, empty-status inventory rows remain), reopen …

    line 35
  6. Distinctive:

    Test one row at a time with the per-route protocol.

    line 40
  7. Distinctive:

    After every row: update the report, tick the todo, point Resume at the next pending row, continue.

    line 41
  8. Distinctive:

    Stop only at the completion gate.

    line 42
  9. Distinctive:

    If the user's message already names the target, viewport, or focus (for example "mobile onboarding", "desktop billing", "full spider at …

    line 46
  10. Distinctive:

    If they only invoked the skill or asked for a vague "QA pass", ask at most these, in one message, then wait:

    line 48
  11. Distinctive:

    Do not ask about severity scales, templates, or process.

    line 54
  12. Distinctive:

    Treat each requested viewport as a dimension on the inventory (same path can be two rows).

    line 56
  13. Distinctive:

    Read root AGENTS.md. Then the nearest frontend AGENTS.md if present.

    line 60
  14. Distinctive:

    Start the stack only if health checks fail.

    line 63
  15. Distinctive:

    Create artifact dirs (see references/report.md).

    line 64
  16. Distinctive:

    If a prior audit exists for this app, read it.

    line 68
  17. Distinctive:

    Do not navigate-and-judge random pages yet.

    line 72
  18. Distinctive:

    If there are more than ~50 rows, reorder so the core user journey and onboarding come first.

    line 84
  19. Distinctive:

    Read references/inventory.md for extraction and row rules.

    line 86
  20. Very specific:

    Put a continuation goal in the report (template in references/report.md).

    line 92
  21. Very specific:

    Create todos: one per inventory row, in the report order.

    line 93
  22. Distinctive:

    Log bugs as they happen: Write the route results line.

    line 105
  23. Distinctive:

    If you run out of context, update Resume and stop mid-loop.

    line 121

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

QA Spider

Long-running, document-only UI audit. Find bugs by actually using the product. Do not fix code. Do not open issues unless asked. Do not commit the report or screenshots unless asked.

The inventory is the contract. You are not done until every inventory row has a result. Screenshot-only page loads are not testing.

Related skills

Load these when they exist in the current project or harness:

  • automated-qa-testing (or equivalent): test users, local-login, fixtures, browser gotchas. Read it during bootstrap, before judging any flow.
  • frontend-design (or equivalent): design tokens and UI rules. Read it before the first design review.
  • goal-writer: optional, after inventory, if you want a copyable continuation contract. The report Resume box is still required.
  • ntfy: notify when the inventory is frozen, on a hard blocker, and at completion.
  • publish-report: only if the user wants a phone-friendly link at the end.

Hard rules

  1. Document only. Do not change application code, CSS, copy, or tests.
  2. One persistent browser session for the whole run. Do not fan out route testing to subagents; they will fight over the session and skip interactions.
  3. One idea per bug. Each entry must be enough for a different agent to fix without re-deriving the repro.
  4. Log a bug the moment you confirm it. Do not batch-write findings at the end.
  5. Re-verify known bugs from prior docs/qa/ audits when you hit those routes. Reuse their IDs; do not renumber.
  6. If a row cannot be tested, write BLOCKED or SKIPPED with the reason. Silent skips are a skill failure.
  7. Do not mark a route done because a nearby route "looked the same".
  8. Do not stop after N bugs, after the core journey, or because the report "looks substantial". The denominator is the inventory count.

Workflow

  1. If docs/qa/ already has an in-progress report for this request (Resume points at a next row, empty-status inventory rows remain), reopen that session and continue there. Do not rebuild the inventory.
  2. Scope (ask only if the user did not already say).
  3. Bootstrap the project, stack, design system, and browser session. Read references/browser.md.
  4. Build the full route/screen inventory and write it into the report before any testing. Read references/inventory.md and references/report.md.
  5. Freeze a continuation goal and a todo list with one item per inventory row.
  6. Test one row at a time with the per-route protocol. Read references/per-route.md before the first row and keep following it.
  7. After every row: update the report, tick the todo, point Resume at the next pending row, continue.
  8. Stop only at the completion gate.

1. Scope

If the user's message already names the target, viewport, or focus (for example "mobile onboarding", "desktop billing", "full spider at 390px"), do not re-ask. Proceed.

If they only invoked the skill or asked for a vague "QA pass", ask at most these, in one message, then wait:

  • Focus: full app, or a named area / journey?
  • Viewport(s): narrow (~390x844), medium (~768x1024), wide (~1440x900), or more than one?
  • Anything to skip, any known-broken environment, any existing docs/qa/ audit to continue?

Do not ask about severity scales, templates, or process. After answers (or a specific initial brief), do not ask permission to continue.

Treat each requested viewport as a dimension on the inventory (same path can be two rows). Do not default to mobile or desktop when they did not say.

2. Bootstrap

  1. Read root AGENTS.md. Then the nearest frontend AGENTS.md if present.
  2. Load the project's browser-QA skill and design-system skill when they exist.
  3. Discover frontend origin, API origin, health checks, and the documented dev-start command. A common local shape is a Vite/React app on :5173 and a Laravel API on :8000 — confirm from this repo, do not assume.
  4. Start the stack only if health checks fail. Wait for a real 200, not a process spawn.
  5. Create artifact dirs (see references/report.md). Create the report file up front with the severity key, bug template, empty inventory heading, and Resume box.
  6. Open one browser session at the agreed viewport(s). Dismiss cookie/consent/NPS overlays before interacting with page content.
  7. Auth: use the project's documented impersonation / local-login / test users. Manual login only when the login form itself is under test. For signup QA, use a unique throwaway address. Do not reset shared fixtures as preflight.

If a prior audit exists for this app, read it. Continue numbering from the last bug ID. Note environmental caveats so you do not re-log them as new product bugs.

3. Inventory (blocking)

Do not navigate-and-judge random pages yet.

Build the complete reachable-route list, write it into the report as a checklist, and estimate the count. Include:

  • Declared router paths (auth, layout, name)
  • Query/state variants that change the UI
  • Auth/plan/role variants when the same path renders differently
  • Empty / first-run / paywalled / context-required variants when they are distinct screens
  • Routes found by spidering nav, sidebar, footer, account menus, and in-product CTAs that the static list missed

Categorise each row: anonymous, authed, role/plan-gated, admin, context-required.

If there are more than ~50 rows, reorder so the core user journey and onboarding come first. Do not delete the tail. The tail stays in the checklist.

Read references/inventory.md for extraction and row rules.

4. Freeze the run (blocking)

The inventory is useless if the agent "finishes" after a handful of pages. Immediately after writing it:

  1. Put a continuation goal in the report (template in references/report.md). Done means: every inventory row is PASS, FAIL, BLOCKED, or SKIPPED, each with protocol evidence.
  2. Create todos: one per inventory row, in the report order. The current row is in_progress. Never a single todo named "QA the app". If the todo tool caps count, keep the next batch of ~10 plus the current row, and treat the report checklist as canonical.
  3. Set the Resume box to the first pending row: path, viewport, auth user, next action.
  4. Tell the user one line: inventory count and the first path. Start that row in the same turn. Do not stop for approval.

5. Per-route loop

For every row, in order, with no batching:

  1. Navigate. Full screenshot. Measure horizontal overflow. Read console.
  2. List interactions from a fresh interactive snapshot before clicking. Write that checklist into the report.
  3. Design review first against the design system — anomalies even when nothing is "broken".
  4. Exercise every listed control. Assert a state change (URL, text, snapshot). Happy path plus one failure path per form. Open/close/scroll overlays at the current viewport.
  5. Log bugs as they happen. Write the route results line. Then the next row.

A route todo may be completed only when every interaction on that row is tested or explicitly skipped with a reason.

PASS criteria and the interaction taxonomy live in references/per-route.md.

6. Completion gate

You may write the final summary only when every inventory row has a status. The summary must include:

  • Rows tested / total (and BLOCKED / SKIPPED counts)
  • Bugs by severity
  • The 5 issues you would fix first, with IDs
  • What remains untested and why
  • Viewport(s), session name, report path, artifact dir

If you run out of context, update Resume and stop mid-loop. A partial report with a next-row pointer is correct; a premature "done" is not.

Anti-patterns (these mean you drifted)

  • Closing after the core journey while later rows are still pending
  • Passing a route from a screenshot without an interaction checklist
  • Testing only primary CTAs and ignoring tabs, menus, empty states, and failure paths
  • Relogging known benign console noise
  • Fixing CSS "while you are here"
  • Parallel browser sessions or subagent spiders
  • Asking "want me to continue?" after the inventory is frozen

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.