Add Diagnose and X-ray, shared building habits, fresh-helper reviews, and a Bug fixed spec state

AI Assisted
This commit is contained in:
jparkerweb committed 2026-10-16 19:28:11 -07:00
1 parent 80ae3decdd
commit 33a0dbd34a
58 files changed
+3270 -236

No files matched your search

+83
View File
@@ -0,0 +1,83 @@
# Diagnose on the Web Console
Workflow notes for `diagnose`, part of the web console contract (`console.md`).
## 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`:
```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." }
]
}
```
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.
## 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:
```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)." }
]}]
```
- **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".
## The bug name
With the cause written, ask the folder name, posted with `--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." }
```
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).
## 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.
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`).
+1 -1
View File
@@ -12,7 +12,7 @@ know:
| 3, Implementation Summary | Written to `overview.md` as usual; mirror it as a doc (marked `saved`, as a `file` block on `overview.md`) so the page reader sees it land. |
| 4, Documentation Review | The proposed-updates table as a doc, and a `multi` naming the documents to update — every option ticked is "approve", unticked ones are skipped. A `review` works instead when the set is all-or-nothing. |
| 5, User Feedback | Optional items, `required: false`: the rating as a `choice` of 1 to 10 or a `text`, the three reasons as `text`. The submit-to-maintainer consent is a `confirm`. |
| 6, Spec Cleanup | A `confirm` before moving anything, the archive paths in `consequences`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). |
| 6, Spec Cleanup | A `review` item before moving anything (`doc`: Step 3's summary), verdicts `yes` ("Archive it"), `show` ("Show me it working", token `show me`) and `no`, the archive paths in `body`, and a line that the spec's remembered workspace folders are forgotten too (`console.mjs forget --spec specs/<feature>` after the move). On `show`, run it as `notes/implement.md` → Show me it working says (the summary line goes into `overview.md`'s Completion Summary), then reopen the card without `show`. |
Post `activity` as each step starts, before its doc or question lands — reading
the spec, running `specs.mjs status` or `archive --dry-run`, checking the
+17 -4
View File
@@ -64,13 +64,14 @@ only ever be offered once nothing could come of it:
]}],
"items": [{
"id": "signoff", "kind": "review", "title": "Approve this phase", "doc": "report",
"body": "Phase 3 is built. Read the report, try the checks, then approve it, review the code first, or say what to change.",
"body": "Phase 3 is built. Read the report, try the checks, then approve it, review the code first, see it running, or say what to change.",
"verdicts": [
{ "id": "review", "label": "Review the code first" },
{ "id": "show", "label": "Show me it working" },
{ "id": "approve", "label": "Approve this phase" },
{ "id": "changes", "label": "I want changes" }
],
"token": { "approve": "approved", "changes": "needs changes" },
"token": { "approve": "approved", "changes": "needs changes", "show": "show me" },
"nothingYet": "Nothing is marked complete until you approve.",
"gate": { "id": "signoff", "authoritative": true }
}]
@@ -83,7 +84,19 @@ change, treat it as "describe any issues": do the change first and ask again.
`changes` means exactly what it says: address it, update the report, and reopen
the item (`"status": "reopened"`) with a reply in its `thread`. `review` is the
person asking for the code review before they approve anything — read
`building-review.md`.
`building-review.md`. `show` is the terminal's `show me`: see below.
### Show me it working
On `show`, run the workflow's **Show me it working** paragraph (start the app,
look at the change, stop it, one summary line in `phase-X.md`). Save each
screenshot under the session's `shots/` folder, never under `specs/`, and post
them as image blocks in a `shown` doc (`console.md` → Documents), with what was
run in a `md` block above them; no browser tool means that block alone says
what the command printed. Then reopen the same card (`"status": "reopened"`)
without the `show` verdict, a `thread` reply naming what was seen. The same
holds on Finalize's card and the one `building-review.md` reopens; Quick
Task's card is settled instead (`notes/quick-task.md`).
`gate` marks the one approval that counts. The server refuses a second open
authoritative gate, which is what keeps a composed workflow from asking for
@@ -172,7 +185,7 @@ Stage 3 fixes, with no "Check the fixes" item: Stage 4 is the only gate. The
post that starts Stage 2's review carries `"run": { "event": "review", "id":
"review" }`: in this workflow it scores the review stage's 1 point on the meter
as it begins, and the phase's final `run` leaves that point out. Stage 4 is the
sign-off above **without the review verdict** — the phase was already reviewed
sign-off above (`show` included) **without the review verdict** — the phase was already reviewed
— with the review results and unresolved findings in the report doc, header
"Reviewed and ready for sign-off" in the item's `body`. The finish never
carries `review`, and its post carries `"run": { "event":
+15
View File
@@ -70,6 +70,21 @@ Workflow notes for `quick-task`, part of the web console contract
Check for a Quick question between steps, and do not call `wait` until the
build is done. Tick the Verify block's boxes too as the checks pass, in the
post that reports them.
- **See it running, before the finish:** a finished screen freezes every open
card, so ask first. Once the build is done, post a `review` item "See it
running" (`"doc": "plan"`, verdicts `show` ("Show me it working") and `fine`
("No need, finish up"), token `show me` / `no`) with `--wait`. On `show`, run
it as `notes/implement.md` → Show me it working says, its one line going into
the work summary (the finish's `body`); then, or on `fine`, settle the card in
the same post as the finish.
- **Archive a fixed bug, before the finish:** launched on a diagnosed folder
and now Fixed with nothing past the diagnosis, post a `confirm` card
"Archive this bug?" in the same post as "See it running": the dry run's
`files` in `body`, `yesLabel` "Archive it", `noLabel` "Keep it in specs/",
and `consequences` naming `specs--completed/<bug>/`. On yes, run
`node "<S>/specs.mjs" archive <spec>` (the skill file says where `<S>` is),
and say where it went in the finish's `body`. On no, the
dashboard lists the folder as "Bug fixed", never pre-selected.
- **The finish after the build:** `command` is the commit command, filled in,
in the project's commit format (AGENTS.md), with
`"where": "When you are happy with it, commit it from your terminal:"`, and
+73
View File
@@ -0,0 +1,73 @@
# X-ray on the Web Console
Workflow notes for `xray`, part of the web console contract (`console.md`).
## The mode question
A typed argument that names the mode and area skips it. Otherwise ask both in
one batch, posted with `--wait`:
```jsonc
{
"title": "Codebase X-ray",
"headline": { "stage": "Choosing", "cleared": 0, "total": 2 },
"items": [
{ "id": "mode", "kind": "choice", "title": "What you want to know", "allowOther": false,
"body": "Explain one area, or rank what makes this code hard to change.",
"options": [
{ "k": "1", "text": "Explain an area", "detail": "How it works and why it is that way, citing files and the commits behind it." },
{ "k": "2", "text": "Find the rough spots", "detail": "Ranked spots that make change hard. You pick the ones worth fixing; they become a brief for Pathfinder or Plan." }
] },
{ "id": "area", "kind": "text", "title": "Which area", "required": false,
"body": "A folder, file or feature. Needed to explain; leave it empty to survey the whole repository.",
"placeholder": "src/exporter, the code that builds the CSV reports" }
]
}
```
Explain picked with the area left empty: ask for it again as a required `text`
card. No recommendation on the mode: only the person knows what they came for.
## Explain mode
The answer is a doc, `id` `"answer"`, one block per section (`In one paragraph`,
`How it works`, `Why it is this way`, `Worth knowing`), with the `Sources:` line
at the top of the first. Then the save offer as a `confirm` card pointing at it:
```jsonc
{ "id": "keep", "kind": "confirm", "title": "Keep this answer", "doc": "answer",
"body": "Save it as `specs/exporter/XRAY-exporter-20261016.md`, as input for Pathfinder or Plan?",
"yesLabel": "Save it", "noLabel": "No, just reading" }
```
Ask the folder name in the same batch as a `text` card with `pattern`
`^[a-z0-9]+(-[a-z0-9]+)*$` when it is not obvious. Once written, re-send the doc
with `"saved": "specs/<name>/XRAY-<area-slug>-<date>.md"`.
## Rough-spots mode
The ranked list is a doc, `id` `"spots"`, one block per spot (its files, why it
hurts, the "to change X today" example). The pick is one `multi` card pointing
at it, posted with `--wait`:
```jsonc
{ "id": "pick", "kind": "multi", "title": "Worth fixing", "doc": "spots", "required": false,
"body": "Tick the spots worth fixing. Add a note for any of them in the box (\"1: the exporter part only\"). Only ticked spots go into the brief.",
"options": [
{ "k": "1", "text": "Exporter and its formatter always change together", "detail": "src/export.ts, src/format.ts: together in 14 of 16 commits." }
] }
```
Nothing ticked: nothing is written. Otherwise write the brief, then add it as a
second doc with `"saved": "specs/<name>/ARCHITECTURE-BRIEF-<date>.md"` and a
`file` block.
## The finish
`command` is `/plan2code-0-pathfinder` (big or unclear) or `/plan2code-1-plan`
(settled), never with a placeholder; leave it out when nothing was kept. `doc`
is the brief or the saved answer when there is one. `"dashboard": true`, then
keep waiting for the press (`console-finish.md`).
A stop before anything was written ends on a finish whose `body` says nothing
was kept, with `"command": "/plan2code-xray"` (`console-stop.md`).