Event Debugging

A TRAE skill for progressive, grill-style interactive debugging of every clickable element on a frontend page.

What It Does

This skill systematically debugs frontend pages by cataloging every interactive element (buttons, selects, links, modals, uploads, etc.), then interrogating each one through 8 layers of progressive Socratic questioning. It never fabricates logic -- it first reads the full event graph from the code, then asks you what the behavior should be.

Core principle: Never fabricate. Never assume. Always read first, then question.

Quick Start

npx event-debugging@latest

This scaffolds a TRAE skill at .trae/skills/event-debugging/SKILL.md and a template at template/event-debug-record-template.md into your project.

Then tell your agent:

"Debug the interaction logic on src/views/config/index.vue"

The skill activates and guides you through a rigorous 6-phase debugging process.

Install

npm install event-debugging --save-dev

Or manually:

git clone https://github.com/Xstly1014/event-debugging.git
cp event-debugging/SKILL.md your-project/.trae/skills/event-debugging/SKILL.md

Workflow (6 Phases)

| Phase | Description | |:---|:---| | Phase 0: Scope | User specifies the exact page file path. Never debug without a concrete path. | | Phase 1: Catalog | Deep-read the page and its imported components. List every interactive element across 7 categories: data-mutating buttons, data-querying controls, selection controls, navigation triggers, display toggles, UI-only interactions, and mixed triggers. | | Phase 2: Rank | Prioritize by risk: P0 (destructive mutations like delete) down to P5 (cosmetic interactions like tooltips). | | Phase 3: Deep Context | For each element, trace the full event graph: handler function body, state dependencies, state mutations, API calls, UI side effects, and related elements. Build a visual event graph showing every connection. | | Phase 4: Interrogate | 8-layer progressive Socratic questioning per element. Each layer presents the current code behavior as option A plus contextually relevant alternatives. User makes every decision. | | Phase 5: Record | Write confirmed behavior to a persistent debug record file (docs/event-debug-record.md). Track every confirmed and pending item. | | Phase 6: Verify | For mismatches between desired and actual behavior, propose exact code changes in diff format. User signs off before any edits are made. |

The 8 Questioning Layers

Each interactive element goes through progressively deeper questioning:

| Layer | Question | Focus | |:---|:---|:---| | L1: Trigger conditions | When should this be clickable? | Disabled states, visibility conditions, permission gates | | L2: Pre-action guards | What should happen before the action? | Confirmation dialogs, validation, unsaved-changes warnings | | L3: Core behavior | What should the click actually do? | API call, state mutation, exact endpoint and payload | | L4: Success path | What should happen when it succeeds? | Toast, refresh, navigation, clear state, notify parents | | L5: Failure path | What should happen when it fails? | Error messages, retry, rollback, logging, error classification | | L6: Side effects | What else should change? | Cascading UI updates, cross-component state, hidden dependencies | | L7: Edge cases | What about unusual situations? | Double-click, navigation-away, concurrency, empty states | | L8: Acceptance | Complete specification check | Final sign-off gate before moving to next element |

Each layer follows a strict protocol:

• Option A is always the current code behavior (what the skill found by reading the code)
• Options B-D are contextually relevant alternatives derived from code analysis
• The last option is always a custom free-text field
• The user cannot be asked an open-ended "what do you want?" question without being shown what the code currently does

Example: Debugging a Delete Button

---- Delete Button -- Layer 1: Trigger Conditions ----

In the code, the disabled condition is:
  :disabled="selectedRows.length === 0"

This means: the button is only clickable when at least one row is selected.

I also noticed the following potentially relevant state:
  - selectedRows: current selected row array
  - tableData: total table data count
  - userRole: current user role (in store.user.role, currently not wired to this button)

Please confirm / choose:
A) [OK] Current logic is correct: clickable when selectedRows.length >= 1
B) [ADD] Additional condition: only when user role is admin
C) [ADD] Additional condition: only when data status is "draft"
D) [CUSTOM] I'll write my own: [please fill in]

This continues through all 8 layers, each building on the previous. By Layer 6, the skill surfaces hidden dependencies the user may not have considered (closing the detail drawer, pagination fallback, tab badge updates). By Layer 8, the user has a complete verified specification for the element.

Element Categories

The skill classifies every interactive element into one of these categories during cataloging:

| Category | Risk | Examples | |:---|:---|:---| | Data-mutating buttons | P0 | Create, Delete, Edit, Save, Submit, Batch delete, Import | | Batch operations | P1 | Batch actions, Form submissions | | Selection controls | P2 | Checkbox, Radio, Switch, Select, Tree select, Date picker | | Data-querying controls | P3 | Search, Filter, Refresh, Export, Download, Pagination | | Navigation triggers | P4 | Link, Breadcrumb, Tab, Sidebar, Menu, Back button | | Display toggles | P4 | Expand/Collapse, Modal, Drawer, Detail panel | | UI-only interactions | P5 | Sort, Drag, Resize, Copy, Tooltip, Context menu |

Debug Record

The skill maintains a docs/event-debug-record.md file in your project, creating a persistent audit trail:

• Every confirmed decision is recorded per element
• Pending items stay marked as unresolved
• Each element gets an acceptance status: CONFIRMED, PARTIAL, or PENDING
• The record serves as living documentation of your page's interaction logic

Key Design Decisions

Why 8 layers? Each layer isolates a specific concern. This prevents scope creep -- the user is never asked about failure handling before confirming what the button even does. Layer 6 (side effects) is the most valuable: it surfaces cascading effects the user probably hasn't thought about.

Why always show current code as option A? Because users often don't know what their own code does. The skill reads the handler, builds the event graph, and presents reality first. The user then decides whether reality matches intent.

Why one element at a time? Because debugging an entire page at once produces shallow analysis. The 8-layer protocol forces depth per element. Skipping means missed edge cases and hidden bugs.

Why a persistent debug record? Because interaction logic is knowledge that decays. Six months later, the debug record tells you why a button behaves the way it does, with full traceability back to the original debugging session.

Repository Structure

event-debugging/
├── SKILL.md                              # Core skill definition
├── README.md                             # This file
├── LICENSE                               # MIT
├── package.json                          # npm package config
└── template/
    └── event-debug-record-template.md     # Debug record template

License

MIT