Update the web console server, screens, help, prefs and loop setup, with matching page and logic suites

AI Assisted
This commit is contained in:
jparkerweb committed 2026-11-02 12:00:12 -08:00
1 parent 2468027a5a
commit 8e34bf1005
119 files changed
+9957 -3728

No files matched your search

+13 -58
View File
@@ -1,83 +1,38 @@
# Diagnose on the Web Console
Workflow notes for `diagnose`, part of the web console contract (`console.md`).
# Diagnose
## The bug
A typed argument that already describes the bug skips the cards it answers.
Otherwise ask in one batch (at most three open), posted with `--wait`:
An argument that already describes the bug skips the cards it answers. Otherwise one `--wait` batch, no `templates`:
```jsonc
{
"title": "Diagnose a bug",
"headline": { "stage": "The bug", "cleared": 0, "total": 3 },
"items": [
{ "id": "bug", "kind": "text", "title": "What is wrong",
"body": "The bug, in a sentence or two.",
"placeholder": "The CSV export drops the last row when the report has more than 100 rows." },
{ "id": "expected", "kind": "text", "title": "Expected and actual",
"body": "What should happen, and what happens instead.",
"placeholder": "Expected 150 rows in the file; it has 149, and the last order is missing." },
{ "id": "see-it", "kind": "text", "title": "How to see it",
"body": "The steps, command, page or input that shows it, and since when if you know.",
"placeholder": "Run npm run export -- --month 2026-09 and count the rows. It worked last month." }
]
}
{"title":"Diagnose a bug","headline":{"stage":"The bug","cleared":0,"total":3},"items":[{"id":"bug","kind":"text","title":"What is wrong","body":"The bug, in a sentence or two."},{"id":"expected","kind":"text","title":"Expected and actual","body":"What should happen, and what happens instead."},{"id":"see-it","kind":"text","title":"How to see it","body":"The steps, command, page or input that shows it, and since when if known."}]}
```
No `"templates"` on these cards: the starter templates are for a fresh idea,
and a bug report is not one. A follow-up the answers leave open is a new card
with a new id.
A follow-up the answers leave open is a new card with a new id.
## The cause
Post the cause as a doc, `id` `"cause"`, as soon as there is something to show,
and grow it as evidence lands, with `"agent": { "status": "working",
"activity": "..." }` while you reproduce and narrow:
Doc `cause`, posted as soon as there is something to show and grown as evidence lands, with `agent` `working` while you reproduce:
```jsonc
"docs": [{ "id": "cause", "title": "The cause", "note": "Reproduced; narrowing", "blocks": [
{ "id": "repro", "state": "settled", "md": "## Reproduction\n\n`node scripts/export-check.mjs` fails: 149 rows, expected 150." },
{ "id": "found", "state": "settled", "md": "## The cause\n\n`src/export.ts` `writeRows()`: the loop stops at `rows.length - 1`. **Proven** by the reproduction." },
{ "id": "fix", "state": "settled", "md": "## Suggested fix\n\nLoop to `rows.length`. **Size:** Small (Quick Task)." }
]}]
{"docs":[{"id":"cause","title":"The cause","note":"Reproduced; narrowing","blocks":[{"id":"repro","state":"settled","md":"## Reproduction\n\n..."},{"id":"found","state":"settled","md":"## The cause\n\n..."},{"id":"fix","state":"settled","md":"## Suggested fix\n\n... **Size:** Small (Quick Task)."}]}]}
```
- **Unproven** guesses are `assumed` blocks, one per guess, ranked, each with
its evidence and what would confirm it. A guess the evidence proves becomes
`settled`; one it rules out is removed (`"_delete": true`).
- Keeping a failing test inside the project is a `confirm` card pointing at
the doc (`"doc": "cause"`), `yesLabel` "Keep it", `noLabel` "Throw it away".
- Unproven guesses are `assumed` blocks, ranked, each with its evidence and what would confirm it. Proven: `settled`. Ruled out: `"_delete":true`.
- Keeping a failing test in the project: `confirm` with `"doc":"cause"`, `yesLabel` "Keep it", `noLabel` "Throw it away".
## The bug name
With the cause written, ask the folder name, posted with `--wait`:
After the cause, `--wait`:
```jsonc
{ "id": "name", "kind": "text", "title": "Name for the write-up", "doc": "cause",
"body": "The diagnosis is saved as `specs/<name>/DIAGNOSIS-<date>.md`. Lowercase words joined by dashes.",
"placeholder": "csv-export-drops-rows",
"pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
"patternHint": "Lowercase letters, numbers and dashes, like csv-export-drops-rows." }
{"id":"name","kind":"text","title":"Name for the write-up","doc":"cause","body":"Saved as `specs/<name>/DIAGNOSIS-<date>.md`. Lowercase words joined by dashes.","placeholder":"csv-export-drops-rows","pattern":"^[a-z0-9]+(-[a-z0-9]+)*$","patternHint":"Lowercase letters, numbers and dashes."}
```
Once written, re-send the doc with
`"saved": "specs/<name>/DIAGNOSIS-<date>.md"` and its blocks replaced by one
`file` block for that path (delete the old ids).
Once written, re-send `cause` with `"saved":"specs/<name>/DIAGNOSIS-<date>.md"` and one `file` block for that path (delete the old block ids).
## The finish
`command` is `/plan2code-quick-task specs/<name>` (small fix) or
`/plan2code-1-plan specs/<name>` (big fix) with the real folder filled in
(`/plan2code-quick-task specs/csv-export-drops-rows`), never a placeholder: a
copied command must reach the diagnosis. `body` names the cause, how sure, and that the
next step reads the diagnosis first. `doc` is `"cause"`. `"dashboard": true`,
then keep waiting for the press (`console-finish.md`): back on the dashboard
the folder shows as "Bug diagnosed", with that card lit.
`command` is `/plan2code-quick-task specs/<name>` (small fix) or `/plan2code-1-plan specs/<name>` (big fix), real folder filled in. `body`: the cause, how sure, and that the next step reads the diagnosis first. `"doc":"cause"`, `"dashboard":true`. Nothing kept (did not reproduce, no guess held): no `command`, say so in `body`.
Nothing kept (the bug did not reproduce and no guess held up): leave
`command` out and say so in `body`.
A stop before the file is written ends on a finish whose `body` says nothing
was kept (and names any throwaway script or kept test you wrote), with
`"command": "/plan2code-diagnose"` (`console-stop.md`).
A stop before the file is written: `body` says nothing was kept (and names any throwaway script or kept test), `"command":"/plan2code-diagnose"`.