02-llm-editing-workflow/08-how-chatgpt-should-debug-using-vroq-mcp.md

How ChatGPT should debug using Vroq MCP

Use this file when debugging a running Vroq app through Vroq MCP client debug tools.

Main rule

When debugging with Vroq MCP, never guess.

Read the app structure, inspect the framework files if needed, use the connected client debug tools, and verify behavior through store state, actions, errors, network logs, and rendered HTML.

Required workflow after code changes

After changing app code and before testing behavior, ChatGPT must reload the app.

Use the client reload tool first, then run store, action, error, network, dispatch, replay, or HTML checks.

Rule:

after code changes
before testing
always reload the app

This avoids debugging stale code or stale store state.

Recommended debug workflow

1. identify the visible symptom 2. read the owning files in the app 3. if framework behavior is involved, list files in vroqjs/<version>/ and read the real framework files 4. if code was changed, reload the client before testing 5. get the current store snapshot 6. inspect recent action log entries 7. inspect runtime errors 8. inspect network log if remote calls are involved 9. dispatch allowed actions to verify behavior 10. inspect rendered HTML if the UI looks wrong 11. use replay or checkpoints if needed

Useful Vroq MCP client debug tools

Common tools include:

client_debug_capabilities
client_debug_reload
client_debug_get_store
client_debug_get_action_log
client_debug_get_errors
client_debug_get_network_log
client_debug_dispatch
client_debug_replay
client_debug_get_html

Use capabilities first when you need to learn what the connected app supports.

Reload rule

If ChatGPT patches app files and then immediately tests behavior without reloading the connected client, the results may reflect old code.

So the rule is strict:

change code → reload app → test behavior

Do not skip the reload step.

Store-first debugging

For state bugs, inspect the store first.

Questions to answer:

is the current state shape correct?
did the expected action fire?
did the reducer update the correct slice?
is the UI reading the expected state path?

HTML debugging

If store state is correct but the UI still looks wrong, inspect rendered HTML.

This helps distinguish:

state bugs
rendering bugs
stale UI assumptions
missing or incorrect DOM output

Error debugging

Always inspect runtime errors when behavior is broken.

An app may render partially while still failing in event handlers, effect-like code, or component imports.

Action schema definitions for debugging

For non‑production (development) apps, actions should include debugging metadata when created with the action() helper.

Example (simplest form recommended):

import { action } from "/vroqjs/system/store/action.js";

const increment = action("COUNTER_INCREMENT", {
  description: "Increment a counter instance by id.",
  payload: {
    id: {
      type: "string",
      required: true,
      description: "Counter instance id"
    }
  },
  examples: [{ id: "counterA" }]
});

The framework converts the payload object automatically into the full payloadSchema used by MCP debugging tools.

Why this matters:

MCP debugging tools expose these schemas through debug.capabilities.
This allows ChatGPT or other tools to know the required arguments for dispatching actions.
It prevents guessing payload shapes.

These definitions should exist for **development builds** (release=false).

In production releases (release=true) the debugging system may be disabled, so these schemas are mainly intended for debugging and development workflows.

Final rule

Use Vroq MCP debugging as a structured workflow:

read code → reload app → inspect store/actions/errors/html → verify root cause → patch the owning layer