click_path_audit v1.0.0

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.