Click-Path State Auditor

Обнаружение скрытых UI-багов, состояний гонки и побочных эффектов состояний с помощью навыка «Click-Path Audit» для Claude Code. Идеально подходит для систематической отладки фронтенда.

Безопасность и тестирование ★ 172,008 GitHub (172,008 ★)

Навык аудита цепочки кликов — это специализированный диагностический инструмент для Claude Code, предназначенный для обнаружения трудноуловимых логических ошибок в сложных потоках состояний пользовательского интерфейса. Систематически отслеживая обработчики кнопок и отображая побочные эффекты в хранилищах состояний, таких как Zustand или Redux, он выявляет шаблоны, при которых действия непреднамеренно отменяют друг друга или оставляют интерфейс в несогласованном состоянии. Он особенно эффективен после крупных рефакторингов или когда традиционная отладка не может объяснить, почему элемент интерфейса «ничего не делает», несмотря на правильное подключение и отсутствие ошибок во время выполнения.

Ключевые особенности

01172,008 звёзд на GitHub

02Обнаружение состояний гонки: Определяет асинхронные вызовы, которые могут разрешиться в неправильном порядке и повредить состояние.

03Стандартизированная отчётность: Генерирует подробные журналы аудита, классифицируя ошибки по типу, серьёзности и конкретным рекомендациям по исправлению.

04Анализ устаревших замыканий: Выявляет хуки React и колбэки, захватывающие устаревшие значения состояния.

05Карта хранилища состояний: Автоматически строит карту побочных эффектов для Zustand, Redux и React Context.

06Последовательный трассировочный анализ: Прослеживает каждый вызов функции в обработчиках UI для обнаружения переопределений и шаблонов «последовательной отмены».

Варианты использования

01Отладка кнопок или компонентов UI, которые «не выдают ошибок» без консольных ошибок или сбоев.

02Проверка целостности общего состояния после рефакторинга глобальных действий хранилища или логики управления состоянием.

03Аудит критических пользовательских сценариев (оформление заказа, регистрация, сложные формы) перед крупным производственным релизом.

name	click-path-audit
description	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.
origin	community

/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

Что это 🧩

Click-Path State Auditor — это инструмент для поиска «багов второго порядка» в интерактивных интерфейсах. Статический анализ и юнит-тесты обычно проверяют, существует ли функция, не падает ли она, правильный ли тип возвращает. Но они не ловят ситуацию, когда две рабочие функции, вызванные последовательно, отменяют друг друга, или состояние UI после клика не соответствует обещанию на кнопке. Навык построчно трассирует реакции на каждое пользовательское действие (клик, отправка формы, переключение) и проверяет, не возникает ли Sequential Undo, Async Race, Stale Closure, Missing State Transition, Conditional Dead Path или useEffect Interference.

Реальный пример из практики: кнопка «New Email» вызывала setComposeMode(true), а затем selectThread(null). Обе функции работали, но внутри selectThread был прописан сброс composeMode: false. Кнопка ничего не делала. 54 ошибки были найдены обычным дебаггингом — эту пропустили.

Как работает 🔍

Аудит проходит в три этапа.

1. Составление карты сторов (Step 1)

Перед разбором каждого touchpoint нужно задокументировать все побочные эффекты каждого экшена Zustand / React Context:

Какие поля он устанавливает?
Какие поля он сбрасывает (часто не свои)?
Например: selectThread(thread|null) → устанавливает selectedThread, messages, но сбрасывает composeMode, composeData, redraftOpen.

Этот шаг — критическая база. Без него не увидеть, что функция «украла» чужое состояние.

Пример вывода:

STORE: emailStore
  setComposeMode(bool) → sets: {composeMode}
  selectThread(thread|null) → sets: {...} RESETS: {composeMode: false, ...}

DANGEROUS RESETS:
  selectThread → resets composeMode (owned by setComposeMode)

2. Аудит каждого touchpoint (Step 2)

Для каждой интерактивной точки (кнопка, переключатель, сабмит) в целевой области выполняется трассировка:

TOUCHPOINT: [Button label] in [Component:line]
  HANDLER: onClick → {
    call 1: functionA() → sets {X: true}
    call 2: functionB() → RESETS {X: false}  ← CONFLICT
  }
  EXPECTED: …
  ACTUAL: X is false
  VERDICT: BUG — Sequential Undo

Проверяются 6 паттернов:

Sequential Undo 🌀 — первый вызов ставит флаг, второй его сбрасывает.
Async Race 🏁 — загрузка из двух асинхронных вызовов, итоговое состояние зависит от порядка разрешения.
Stale Closure 📦 — замыкание «запоминает» устаревшее значение (например, два setCount(count+1) с одним и тем же count).
Missing Transition 🚫 — кнопка «Save» только валидирует, но не сохраняет, или «Delete» не вызывает API.
Conditional Dead Path 🧟 — условие всегда ложно, нужный код никогда не выполняется.
useEffect Interference 👻 — useEffect смотрит на установленное состояние и сбрасывает его обратно.

3. Формат отчёта (Step 3)

Каждый найденный баг получает ID CLICK-PATH-NNN, уровень серьёзности (CRITICAL/HIGH/MEDIUM/LOW), описание touchpoint, шаблон ошибки, полную трассировку, ожидаемое и фактическое поведение и конкретное предложение по исправлению.

CLICK-PATH-001: HIGH
  Touchpoint: "New Email" button in ThreadList.tsx:23
  Pattern: Sequential Undo
  Trace:
    1. setComposeMode(true) → sets {composeMode: true}
    2. selectThread(null) → RESETS {composeMode: false}  ← CONFLICT
  Expected: composeMode = true
  Actual: composeMode = false
  Fix: Remove reset of composeMode from selectThread, or reorder calls

4. Контроль области видимости 🎯

Аудит может быть дорогим. Рекомендуется:

Полный аудит приложения — перед релизом или после крупного рефакторинга. Запускать параллельных агентов по страницам.
Аудит одной страницы — после добавления новой функциональности или по репорту пользователя.
Store-focused аудит — после изменения Zustand-стора, проверить всех потребителей изменённых экшенов.

Для полного аудита предлагается разделение: Agent 1 составляет карту сторов, Agents 2–8 поочерёдно разбирают страницы (Dashboard, Chat, Emails, Projects, CRM, Profile, Management Suite).

Когда использовать 🎯

После этапа систематического дебаггинга (который нашёл 54 других типа багов) — Click-Path State Auditor ловит то, что пропустил статический анализ.
После любого изменения в общем состоянии (например, Zustand store) — проверить все места, где он используется.
После рефакторинга, затрагивающего общие сторы.
Перед релизом на критических пользовательских сценариях.
Когда пользователи сообщают «кнопка не работает» — это основной инструмент для такого симптома.

Не использовать для:

Багов на уровне API (неверный ответ, отсутствующий endpoint) — для этого есть systematic-debugging.
Стилей и вёрстки — используйте визуальный осмотр.
Производительности — профилирование.

Важно знать 🛠️

Аудит встраивается в пайплайн: запускается после /superpowers:systematic-debugging и до /superpowers:verification-before-completion.
Каждый найденный баг рекомендуется обернуть в тест (интеграция с /superpowers:test-driven-development).
Карта сторов (Step 1) — единый источник истины для всех параллельных агентов. Она должна быть составлена первой.
Инструмент особенно эффективен для приложений на Zustand или Redux, где экшены имеют скрытые побочные эффекты.

Установите одной командой.

npx skillfish add affaan-m/everything-claude-code click-path-audit

Источник: https://mcpmarket.com/tools/skills/click-path-state-auditor