Skip to main content
Agent skill

Click Path Audit

Trace every user-facing button/touchpoint through its full state change sequence to find bugs where functions individually work but cancel each other out, produce wrong final state, or leave the UI in an inconsistent state. Use when: systematic debugging found no bugs but users report broken buttons, or after any major refactor touching shared state stores.

Get started

Get the complete skill folder, including its scripts and reference files.

·

When to use this skill

Use Click Path Audit when an AI agent needs a reusable SKILL.md workflow for this job: Trace every user-facing button/touchpoint through its full state change sequence to find bugs where functions individually work but cancel each other out, produce wrong final state, or leave the UI in an inconsistent state. Use when: systematic debugging found no bugs but users report broken buttons, or after any major refactor touching shared state stores.

When not to use it

Skip Click Path Audit when the task is outside the coding category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/click-path-audit
# Save SKILL.md to ~/.claude/skills/click-path-audit/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/click-path-audit/SKILL.md. For a shared project, commit the folder at .claude/skills/click-path-audit/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Click Path Audit skill for this task: After systematic debugging finds "no bugs" but users report broken UI. Confirm any required inputs or files before making changes.

What supports this recommendation?

83/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
92/100
Practical detail
92/100
Source evidence
63/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# /click-path-audit — Behavioural Flow Audit

Find bugs that static code reading misses: state interaction side effects, race conditions between sequential calls, and handlers that silently undo each other.

## The Problem This Solves

Traditional debugging checks: - Does the function exist? (missing wiring) - Does it crash? (runtime errors) - Does it return the right type? (data flow)

But it does NOT check: - **Does the final UI state match what the button label promises?** - **Does function B silently undo what function A just did?** - **Does shared state (Zustand/Redux/context) have side effects that cancel the intended action?**

Real example: A "New Email" button called `setComposeMode(true)` then `selectThread(null)`. Both worked individually. But `selectThread` had a side effect resetting `composeMode: false`. The button did nothing. 54 bugs were found by systematic debugging — this one was missed.

---

## How It Works

For EVERY interactive touchpoint in the target area:

``` 1. IDENTIFY the handler (onClick, onSubmit, onChange, etc.) 2. TRACE every function call in the handler, IN ORDER 3. For EACH function call: a. What state does it READ? b. What state does it WRITE? c. Does it have SIDE EFFECTS on shared state? d. Does it reset/clear any state as a side effect? 4. CHECK: Does any later call UNDO a state change from an earlier call? 5. CHECK: Is the FINAL state what the user expects from the button label? 6. CHECK: Are there race conditions (async calls that resolve in wrong order)? ```

---

## Execution Steps

### Step 1: Map State Stores

Before auditing any touchpoint, build a side-effect map of every state store action:

``` For each Zustand store / React context in scope: For each action/setter: - What fields does it set? - Does it RESET other fields as a side effect? - Document: actionName → {sets: [...], resets: [...]} ```

This is the critical reference. The "New Email" bug was invisible without knowing that `selectThread` resets `composeMode`.

**Output format:** ``` STORE: emailStore setComposeMode(bool) → sets: {composeMode} selectThread(thread|null) → sets: {selectedThread, selectedThreadId, messages, drafts, selectedDraft, summary} RESETS: {composeMode: false, composeData: null, redraftOpen: false} setDraftGenerating(bool) → sets: {draftGenerating} ...

DANGEROUS RESETS (actions that clear state they don't own): selectThread → resets composeMode (owned by setComposeMode) reset → resets everything ```

### Step 2: Audit Each Touchpoint

For each button/toggle/form submit in the target area:

``` TOUCHPOINT: [Button label] in [Component:line] HANDLER: onClick → { call 1: functionA() → sets {X: true} call 2: functionB() → sets {Y: null} RESETS {X: false} ← CONFLICT } EXPECTED: User sees [description of what button label promises] ACTUAL: X is false because functionB reset it VERDICT: BUG — [description] ```

**Check each of these bug patterns:**

#### Pattern 1: Sequential Undo ``` handler() { setState_A(true) // sets X = true setState_B(null) // side effect: resets X = false } // Result: X is false. First call was pointless. ```

#### Pattern 2: Async Race ``` handler() { fetchA().then(() => setState({ loading: false })) fetchB().then(() => setState({ loading: true })) } // Result: final loading state depends on which resolves first ```

#### Pattern 3: Stale Closure ``` const [count, setCount] = useState(0) const handler = useCallback(() => { setCount(count + 1) // captures stale count setCount(count + 1) // same stale count — increments by 1, not 2 }, [count]) ```

#### Pattern 4: Missing State Transition ``` // Button says "Save" but handler only validates, never actually saves // Button says "Delete" but handler sets a flag without calling the API // Button says "Send" but the API endpoint is removed/broken ```

#### Pattern 5: Conditional Dead Path ``` handler() { if (someState) { // someState is ALWAYS false at this point doTheActualThing() // never reached } } ```

#### Pattern 6: useEffect Interference ``` // Button sets stateX = true // A useEffect watches stateX and resets it to false // User sees nothing happen ```

### Step 3: Report

For each bug found:

``` CLICK-PATH-NNN: [severity: CRITICAL/HIGH/MEDIUM/LOW] Touchpoint: [Button label] in [file:line] Pattern: [Sequential Undo / Async Race / Stale Closure / Missing Transition / Dead Path / useEffect Interference] Handler: [function name or inline] Trace: 1. [call] → sets {field: value} 2. [call] → RESETS {field: value} ← CONFLICT Expected: [what user expects] Actual: [what actually happens] Fix: [specific fix] ```

---

## Scope Control

This audit is expensive. Scope it appropriately:

- **Full app audit:** Use when launching or after major refactor. Launch parallel agents per page. - **Single page audit:** Use after building a new page or after a user reports a broken button. - **Store-focused audit:** Use after modifying a Zustand store — audit all consumers of the changed actions.

### Recommended agent split for full app:

``` Agent 1: Map ALL state stores (Step 1) — this is shared context for all other agents Agent 2: Dashboard (Tasks, Notes, Journal, Ideas) Agent 3: Chat (DanteChatColumn, JustChatPage) Agent 4: Emails (ThreadList, DraftArea, EmailsPage) Agent 5: Projects (ProjectsPage, ProjectOverviewTab, NewProjectWizard) Agent 6: CRM (all sub-tabs) Agent 7: Profile, Settings, Vault, Notifications Agent 8: Management Suite (all pages) ```

Agent 1 MUST complete first. Its output is input for all other agents.

---

## When to Use

- After systematic debugging finds "no bugs" but users report broken UI - After modifying any Zustand store action (check all callers) - After any refactor that touches shared state - Before release, on critical user flows - When a button "does nothing" — this is THE tool for that

## When NOT to Use

- For API-level bugs (wrong response shape, missing endpoint) — use systematic-debugging - For styling/layout issues — visual inspection - For performance issues — profiling tools

---

## Integration with Other Skills

- Run AFTER `/superpowers:systematic-debugging` (which finds the other 54 bug types) - Run BEFORE `/superpowers:verification-before-completion` (which verifies fixes work) - Feeds into `/superpowers:test-driven-development` — every bug found here should get a test

---

## Example: The Bug That Inspired This Skill

**ThreadList.tsx "New Email" button:** ``` onClick={() => { useEmailStore.getState().setComposeMode(true) // ✓ sets composeMode = true useEmailStore.getState().selectThread(null) // ✗ RESETS composeMode = false }} ```

Store definition: ``` selectThread: (thread) => set({ selectedThread: thread, selectedThreadId: thread?.id ?? null, messages: [], drafts: [], selectedDraft: null, summary: null, composeMode: false, // ← THIS silent reset killed the button composeData: null, redraftOpen: false, }) ```

**Systematic debugging missed it** because: - The button has an onClick handler (not dead) - Both functions exist (no missing wiring) - Neither function crashes (no runtime error) - The data types are correct (no type mismatch)

**Click-path audit catches it** because: - Step 1 maps `selectThread` resets `composeMode` - Step 2 traces the handler: call 1 sets true, call 2 resets false - Verdict: Sequential Undo — final state contradicts button intent

Intended uses

  • After systematic debugging finds "no bugs" but users report broken UI
  • After modifying any Zustand store action (check all callers)
  • After any refactor that touches shared state
  • Before release, on critical user flows
  • When a button "does nothing" — this is THE tool for that

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.