eve-hub 0.16.59 → 0.16.63

package/brief/SKILL.md

@@ -29,6 +29,8 @@ Write it the way you would explain it to the human across a desk, in paragraphs,
 
 Explain, don't list. The reasoning lives in the words that join sentences (because, so, but, which means, the catch is), so keep them. A run of short flat statements makes the human rebuild the argument themselves. Join two facts only when one causes or qualifies the other, and stop the sentence there, because a sentence that carries four facts is as hard to follow as four that carry none of the reasoning. Use a bullet list only for items that are parallel, such as three PRs or four steps they must take, and a table only for numbers to compare. A page this short needs no section headings.
 
+A brief opens in the side pane, which draws blocks beside the paragraphs (shapes in the `forms` skill). A block replaces sentences and never repeats them, and it earns its place only when the reader would otherwise rebuild numbers or structure from prose. Use `figures` for up to three numbers, each with its value today, which is where the measured impact goes. Use a table with an italic line after it as its caption for events in order or things to compare. Use `compare` for the one change the brief is about, today beside proposed. Use `ask` for the decision, with your recommended option first, and `flow`, `sequence` or `chart` for steps in order or numbers to compare. Skip a block when one sentence says it. The 500-word cap counts paragraphs only, not the labels and cells inside blocks.
+
 Say what a thing does before you say what it is called. Write "the check that runs before every deploy (`validateMemory`)", not "`validateMemory` runs first". Add the identifier in parentheses only when the human might search for it. In the brief a file, function or flag is never the subject of a sentence.
 
 Name options, steps and parts by what they do, every time, in the document, the post and the ask buttons. "Sign the app" and "the PR that refuses a status post with no tracker row" can be read cold. "Option B", "step 3", "gate G0b" and "the refusal PR" cannot.

package/forms/SKILL.md

@@ -34,6 +34,25 @@ Three candidate looks for a theme. Miss: a prose list of concepts. Instead: a re
 - Each top-level code fence is a card with a copy button; a table is a table card; a link is a chip showing its label; an attached image is its own tile.
 - A fenced form becomes an interactive figure the human can step through.
 
+## How a document shows it
+
+A markdown file a bot shares (a brief, a report) opens in the app's side pane, where `flow`, `sequence`, `chart` and `ask` are drawn too, without the stepping and the notes on hover. A flow and a sequence are drawn as diagrams with their `note` and `ref` listed under them, a `bar` chart as bars, and the other chart types as a table of points under the title. An `ask` is drawn as its options with the first marked Recommended, and the line "Answer in the thread", because the pane can't send a reply. Put the option you recommend first.
+
+Three blocks exist only in documents. Each is a fenced block with a JSON body, and one that doesn't parse is drawn as "Diagram didn't render" with the reason.
+
+- `figures`: `items`, 1 to 3, each with `label` (up to 40 characters), `value` (up to 24) and an optional `today` (up to 40; what the number is now).
+- `compare`: `today` and `proposed`, each with a `title` (up to 40 characters) and a `line` (up to 160). Use it for the one change the document is about.
+- A table followed by a paragraph that is only italic text draws that line as the table's caption.
+
+```figures
+{"items": [{"label": "Rows lost when a second bot writes", "value": "0", "today": "Today 6 of 6 in the last write"}]}
+```
+
+```compare
+{"today": {"title": "A write replaces the whole list", "line": "Rows the bot didn't send are deleted."},
+ "proposed": {"title": "A write changes only the rows it names", "line": "Every other row stays."}}
+```
+
 ## Form syntax
 
 - Claim first: a sentence that says what the form shows comes before it. A chart's `title` is its claim.