---
name: "click_path_audit"
description: "Audit every click path on a website end to end: crawl internal links for broken flows, detect dead-end and orphan pages, script multi-step flow checks (forms, checkout, signup), and emit a fix report. Triggers when the user asks to QA a site's navigation, find broken links or dead ends, or check that user flows actually work."
---

# Click Path Audit

## Purpose

Walk a site the way a visitor does, but exhaustively: crawl every reachable
internal page, validate every link and image, flag dead ends and orphan pages,
then run scripted checks on the flows that matter (signup, checkout, contact,
login). The output is a fix report a developer can work through top to bottom.

Two layers:
1. **Crawl layer** (static, stdlib-only): `bin/click_path_audit.py` crawls the
   site, validates links, and finds structural problems. No dependencies.
2. **Flow layer** (dynamic, Playwright): `references/playwright-flow-checks.md`
   holds copy-paste scripts that click through multi-step flows and assert
   state, capturing console errors and failed requests along the way.

## Workflow

### 1. Crawl the site

```bash
python3 ~/workspace/skills/click_path_audit/bin/click_path_audit.py \
  --url https://example.com --max-pages 300 \
  --output report.md --json report.json
```

Flags: `--check-external` (also validate outbound links), `--delay 0.5`
(seconds between requests), `--timeout 20`. The crawler:

- Follows internal links breadth-first from the base URL, same origin only.
- Records status code, redirect chains, and response errors per URL.
- Uses HEAD for validation, falls back to GET when HEAD is rejected.
- Flags: 4xx/5xx (broken), redirect chains of 2+ hops, pages with zero
  outgoing internal links (dead ends), pages never linked by any other page
  (orphans), and possible soft 404s (HTTP 200 with "not found" content).

### 2. Script the flows that matter

Pick the 3-5 flows that must not break: signup, login, contact form,
checkout, password reset. For each, write a Playwright script per
`references/playwright-flow-checks.md`:

- Assert the success signal (confirmation text, URL change), never just that
  the button clicked.
- Capture `console` errors and `requestfailed` events during the run.
- Test one failure path per flow (bad input, declined card, expired link).

### 3. Review the confusing-sequence checklist

Machines cannot judge confusion, so run `references/confusing-sequences.md`
as a manual pass on the top-traffic pages: back-button behavior, form data
loss on validation error, missing progress indicators, links that open
nowhere.

### 4. Write the fix report

Merge crawler output and flow-check results into one report:

- **Broken**: things that fail outright (404s, 5xx, flow steps that error).
  Each gets: page URL, element/selector, status or error, suggested fix.
- **Warning**: redirect chains, soft 404s, dead ends, slow pages (>3s TTFB).
- **Review**: orphans and confusing-sequence findings for a human to judge.

Severity order matters. A broken checkout link outranks a dead-end blog tag
page. Include the raw `report.json` alongside the markdown so fixes can be
re-verified with a diff on the next run.

## Output Contract

- A markdown fix report: Broken / Warning / Review sections, each finding
  with URL, repro or location, and a suggested fix.
- A JSON report (`report.json`) with per-URL status, link sources, and
  flow-check results, suitable for diffing between runs.
- No findings presented without a URL or selector. "The site looks fine" is
  not a report.

## Operating Rules

1. Stay same-origin and polite: default `--delay 0.5`, sequential requests.
   Never hammer a production site.
2. Do not treat placeholders as broken. `href="#"` and `javascript:void(0)`
   get noted separately, not flagged as errors.
3. A 3xx redirect is live, not broken. Flag chains of 2+ hops as warnings.
4. Soft 404s are heuristics: flag for human review, never assert.
5. Flow scripts must assert outcomes, not clicks. A script that clicks "Submit"
   and reports success without checking the confirmation is a stub.
6. Every factual claim in the report traces to a crawl result or a script run.
   No invented numbers, no confident unverified claims.