# adaptable-debug

Canonical page: https://www.adaptabletools.com/docs/getting-started-ai-skills-debug

- Diagnoses a Grid that is on screen and not doing what you expect
- Reads the running Grid before it changes any source

The `adaptable-debug` AI Skill works out why a running Grid is not doing what you expect.

The AI Skill can help you with:

- A feature (e.g. Layout, Format Column, Styled Column, Calculated Column, Alert etc.) that is not applied
- Wrong columns or rows displayed
- State that does not save, load or migrate
- What the Grid is doing right now
- A support case, or feedback on the Skills, when it cannot be fixed

- Do not use this for compile or type errors, or to add a feature (use `adaptable-dev`)
- Nor to add AdapTable for the first time (use `adaptable-setup`) or to upgrade (use `adaptable-upgrade`)

<AiSkill skill="adaptable-debug" embedded>

The Trades layout is in the dropdown but not applied at start-up — why?
<br/>
The Negative PnL Format Column is not showing in the browser — why?
<br/>
The Grid is blank and there is nothing in the console — what is wrong?
<br/>
Why are these rows missing from the Grid?

</AiSkill>

## How it Works

The running Grid is the evidence the Skill requires.

The agent reads your Grid before it touches your source.

The workflow is as follows:

- It confirms which app and page the Grid is on, and that the dev server is the one on screen
- It reads the page, then checks what it collected against your columns
- It compares the live State with the `initialState` in your source
- It fixes the source, never the saved State, then reloads and reads the page again

- The bug it finds most often is saved State sitting on top of a source edit
- A user, or an earlier session, saved a section, and every source edit since has merged underneath it
- The fix is a [Revision](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-updating-initial-state/index.md) on that section of `initialState`, which replaces just that section on the next load
- Clearing the store would discard the user's saved work

### What it reads from the page, and the files every Skill shares

The Skill reads the page through the [DevTools In-page API](https://www.adaptabletools.com/docs/dev-guide-support-devtools-api/index.md) (`window.__ADAPTABLE_DEVTOOLS__`).

It saves each result to a scratch file:

1. `listInstances()` — when a page has several Grids, it asks which one
2. `getGridInfo(id)`, with the licence key stripped before the file is shown
3. `getLogs(id, { level: ['error', 'warn'] })`
4. `getRecentActions(id)`
5. `getColumns(id)`, saved as `columns.json`
6. Only the State section in question, with `getState(id, '<Section>')`
7. `getPersistentState(id)` when saving or loading is the question

Without a browser tool it asks you to paste these three calls into the browser console and paste the results back:

```js
__ADAPTABLE_DEVTOOLS__.getPersistentState();
__ADAPTABLE_DEVTOOLS__.getColumns();
__ADAPTABLE_DEVTOOLS__.getLogs(undefined, {level: ['error', 'warn']});
```

The `_shared` folder is the same in every Skill:

| Shared reference     | What it holds                                                                       |
| -------------------- | ----------------------------------------------------------------------------------- |
| `grounding.md`       | Find what is installed first; the freshness check; hand-over to AG Grid's Skills    |
| `docs-protocol.md`   | The lookup order for the docs of the detected version                               |
| `validation-loop.md` | What gets checked, the three-round fix loop, where column lists come from           |
| `conversation.md`    | What _tell_ and _ask_ mean; files before the next phase; no State dumps in the chat |
| `guards.md`          | Licence keys, saved State, planning phases that never edit                          |
| `capabilities.md`    | Every CLI command and its MCP tool, generated from the CLI                          |
| `agents-snippet.md`  | The AGENTS.md block                                                                 |

|                     |                                                                                                                                                                                                                                                                                                                                                                                  |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What the agent asks | <ul><li>It does not ask on every step</li><li>It asks only when a choice is hard to undo, and then carries on</li><li>Which Grid, when a page has several</li><li>Before it restores State or discards saved State, and it says what that discards</li><li>Before it includes any row values in a support case, and whether the row field names are sensitive</li></ul>          |
| What it writes      | <ul><li>Scratch files with what it read: the columns, the State and the logs</li><li>`ADAPTABLE_SUPPORT_CASE.md` for a support ticket, scrubbed unless you say otherwise</li><li>`ADAPTABLE_FEEDBACK.md` for feedback on the Skills and the CLI</li><li>You review the file and send it. The Skill never sends anything</li></ul>                                                |
| What it runs        | <ul><li>You do not run these — the agent does: `detect`, `check state --kind persistent`, `check expression`, `check setup` and `anonymise`</li><li>With the app running, it reads the page through the DevTools API</li><li>If it cannot open the page, it asks you to paste `getPersistentState()`, `getColumns()` and `getLogs()` into the browser console and paste the results back</li></ul> |
| When it is finished | <ul><li>The cause is stated, with the evidence that proves it</li><li>A fix in the source is applied or proposed</li><li>It reloads and checks, or hands that check to you</li><li>Or a support case or feedback file is ready for you to review and send</li></ul>                                                                                                              |

### Taking a look inside the Skill

After you install the Skill, `adaptable-debug` looks like this:

```text
adaptable-debug/
├── SKILL.md                  # description + procedure
├── VERSION.md                # the version checked against /.well-known/skills/VERSION
└── references/
    ├── devtools-api.md       # the DevTools In-page API calls it may use
    ├── symptoms.md           # the triage table: symptom → where to look → causes → docs
    ├── ticket-template.md    # ADAPTABLE_SUPPORT_CASE.md
    ├── feedback-template.md  # ADAPTABLE_FEEDBACK.md
    └── _shared/              # the same in every Skill
        ├── grounding.md
        ├── docs-protocol.md
        ├── validation-loop.md
        ├── conversation.md
        ├── guards.md
        ├── capabilities.md
        └── agents-snippet.md
```

## Examples

### Fix a running Grid

<SkillSteps title="A Layout that does not apply" defaultExpanded="true" narrow="true">

<AiSkill skill="adaptable-debug" embedded>

The Trades layout is in the dropdown but not applied at start-up — why?

</AiSkill>

1. Confirms which app and page the Grid is on, and that it is running
2. Reads the running Grid through the [DevTools In-page API](https://www.adaptabletools.com/docs/dev-guide-support-devtools-api/index.md) with its browser tool (or asks you to paste three lines into the browser console): errors and warnings, recent actions, the columns, and the Layout part of State
3. Checks the State it read against your columns
4. Compares it with the `initialState` in your source: a Layout saved in the browser from an earlier session is loading **on top of** your edit
5. Proposes the fix at the source — a `Revision` on the Layout section, so your change replaces the saved one on the next load — instead of clearing the browser storage, which would wipe users' saved work

The cause, the evidence that proves it (the saved Layout next to the one in your source), and a one-line change to the source.

After the change, the agent reloads the page and reads the Layout again: it matches the source and the logs are clean.

</SkillSteps>

<SkillSteps title="A Format Column that does not show" narrow="true">

<AiSkill skill="adaptable-debug" embedded>

The Negative PnL Format Column is not showing in the browser — why?

</AiSkill>

Reads that Format Column from the running Grid and checks its rule.

The cause — often a scope that excludes the column, a rule of the wrong kind, or another rule winning — and the fix. A typical run:

<AiRun skill="adaptable-debug">

- Grid: one instance, `trades-blotter`, the installed AdapTable and AG Grid versions (Grid Info saved with the licence key removed)
- `getState(id, 'FormatColumn')`: the live "Negative PnL" Rule is `[pnl] < 0 && [status] == "Open"`; the one in `src/adaptableOptions.ts` is `[pnl] < 0 AND [status] = "Open"`
- `check state persistent.json --kind persistent --columns columns.json`: 1 error, `aql/syntax` on `FormatColumn.FormatColumns[0].Rule` — JavaScript-style operators are not AdapTableQL
- Cause: the Format Column section saved in this browser was written before the rule was fixed. Saved State merges over `initialState`, so the corrected rule in the source never loads
- Proposed fix, not yet applied: add `Revision: 2` to the `FormatColumn` section of `initialState`. On the next load it replaces that one saved section and leaves the rest of the user's State alone
- To confirm: reload, then `getState(id, 'FormatColumn')` should show the rule from the source

</AiRun>

</SkillSteps>

<SkillSteps title="Layouts and filters lost on reload" narrow="true">

<AiSkill skill="adaptable-debug" embedded>

Our Layouts and filters are lost on every reload

</AiSkill>

Reads what the Grid saved and its logs.

The reason — typically a changed state key or user name, or a failing persistence hook — and where to fix it.

</SkillSteps>

<SkillSteps title="What changed recently" narrow="true">

<AiSkill skill="adaptable-debug" embedded>

What changed in the Grid in the last few minutes?

</AiSkill>

Reads the Grid's recent actions.

A plain list of what changed — Layout, filters, edits — in order.

</SkillSteps>

### Get help

<SkillSteps title="An anonymised support case" narrow="true">

<AiSkill skill="adaptable-debug" embedded>

I cannot fix this — prepare an anonymised support case

</AiSkill>

1. Gathers the evidence from the running Grid: the symptom, what you expected and what happened, the relevant part of State, the columns, the Adaptable Options with the licence keys taken out, and the logs
2. Asks before including any row data. By default it scrubs everything with the CLI's `anonymise`: names, column ids and Expressions are kept; licence keys and user names are removed; row values become placeholders of the same shape
3. Tries to reproduce the problem in the public support template first
4. Writes `ADAPTABLE_SUPPORT_CASE.md` in your project and stops

A file you read, then send yourself through a [support ticket](https://www.adaptabletools.com/support/adaptable-support-ticket). The agent never sends anything.

What leaves your machine is what you read. Grid Info keeps the versions and options, with the licence key removed. Row values, if you agreed to include them, become placeholders:

```json
{
  "userName": "<redacted:userName>",
  "licenseKey": "<redacted:licenseKey>",
  "rows": [
    {
      "field1": 1000,
      "field2": "Xxxxxxx Xxxxx",
      "field3": 1000000,
      "field4": -1000.5
    }
  ]
}
```

This is the [Stays on your machine](https://www.adaptabletools.com/docs/getting-started-ai/index.md#stays-on-your-machine) promise in practice: the file is written locally, scrubbed by default, and only you send it.

</SkillSteps>

<SkillSteps title="Feedback on a Skill" narrow="true">

<AiSkill skill="adaptable-debug" embedded>

Write an ADAPTABLE_FEEDBACK.md for what just went wrong with the adaptable-dev skill

</AiSkill>

Records which Skill and version, what it did, what you corrected and the docs page that would have prevented it — no code, keys or row data.

A file you review and send.

</SkillSteps>