about summary refs log tree commit diff
path: root/docs
diff options
context:
space:
mode:
authorPjotr <wrk@bosa.lan>2026-11-14 12:41:57 +0000
committerPjotr <wrk@bosa.lan>2026-11-14 12:41:57 +0000
commit56bb6214aef7aba1b3ad01d334553c8a62deacdf (patch)
tree2437b499370dbf46bc984098791ee858bbc0b766 /docs
parent7ff1543f8649b4e04d6ccfd012ae8d2403f2e0a7 (diff)
downloadgenenetwork4-56bb6214aef7aba1b3ad01d334553c8a62deacdf.tar.gz
docs: always offer one sentence of what to do next, unless disabled
The API already computes every reply's options -- `next` are GETs that answer
200, `actions` are the POSTs to run next -- and a caller that reads them
learned nothing extra from being told "you could now do X" in prose. What was
missing was the instruction: an answer that stops at the result leaves the
reader to work out the graph.

docs/www/SKILL.md gains "Always offer the next step": end every answer with
ONE sentence built from that reply's own next/actions -- after a compute run, a
lookup, a plot, an upload, a basket edit. Prefer the action href over a
hand-built call. A refusal is an answer too: its next or detail names the
alternative (bulklmm for a GEMMA permutation, /compute/gemma for a covariate
fit). Do not stack suggestions; one next plus at most one genuinely different
alternative. "Skip the suggestions" / "just the result" turns it off for the
session -- it is the sentence that is disabled, not the content. And never
propose a step the API cannot do: if nothing in next/actions fits, say so.

README states the same bargain where the next-link promise is described: the
server's half is that the suggestion is always reachable, the assistant's half
is that it is one sentence and it is a link the reply actually carries.
Diffstat (limited to 'docs')
-rw-r--r--docs/www/SKILL.md27
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