mirror of
https://github.com/jparkerweb/plan2code.git
synced 2026-11-16 20:45:33 -08:00
Add Diagnose and X-ray, shared building habits, fresh-helper reviews, and a Bug fixed spec state
AI Assisted
This commit is contained in:
1 parent
80ae3decdd
commit
33a0dbd34a
58 files changed
+3270
-236
No files matched your search
@@ -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`).
|
||||
@@ -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
|
||||
|
||||
@@ -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":
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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`).
|
||||
Reference in new issue
Block a user