diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/www/SKILL.md | 27 |
1 files changed, 27 insertions, 0 deletions
diff --git a/docs/www/SKILL.md b/docs/www/SKILL.md index a4fee90..8cd2ee9 100644 --- a/docs/www/SKILL.md +++ b/docs/www/SKILL.md @@ -94,6 +94,33 @@ Every JSON reply is `{"data","meta","notes","next"}` and sometimes `"actions"`. * Do not join an `href` to the current URL's directory: that double-prefixes it (`.../gn4/gn4/...`). +### Always offer the next step + +**End every answer with one sentence saying what to do next**, built from that +reply's own `next`/`actions` — never from an idea of what a mapping pipeline +"usually" does. The server already computed the options; the sentence is you +relaying them. + +* **One sentence, after every job** — a compute run, a lookup, a plot, an + upload, a basket edit. Not a list, not a section: *"Next: plot that scan + (`POST /plot/rqtl` with the reply) or look at the PheWAS at rsm10000000888 + (`GET /groups/BXD/phewas?locus=rsm10000000888`)."* +* **Prefer the reply's `actions` href** over a hand-built call, and say which + one you are offering, so the user can paste it or ask for it. +* **A refusal is an answer too.** When the reply is an error, its `next` or its + detail names the alternative (`/compute/bulklmm` for a GEMMA permutation, + `/compute/gemma` for a covariate fit): offer that as the sentence. +* **Do not stack suggestions.** One `next`, plus one alternative at most, and + only if they lead somewhere genuinely different. +* **The user can switch it off.** "Skip the suggestions", "just the result", + "no next steps" — then stop offering them for the rest of the session (or + until they say otherwise), and give the answer alone. Do not re-add a + suggestion in later sentences; it is the sentence that is disabled, not the + content. +* **Never invent a step the API cannot do.** If nothing in `next`/`actions` + fits, say so ("nothing further from this reply") rather than proposing a + path that does not exist. + ## 2. Workflow: map a trait and plot it ```sh |
