Explainer 0.4.1: what changes, and two faults to fix first
This change to the explainer, a skill (instructions and scripts that an AI agent loads) that turns a plain-text description into an interactive diagram page, is ready to merge after two small fixes.
Readers get a shorter card (the box that opens when they click a part of a diagram). In Gantt plans (tasks drawn as bars on a calendar), an arrow with a long way around now runs straight over the bars between. The first four chart colours keep away from the highlight colour that marks the author's main point. Decisions 1 and 2 are the two fixes.
Decisions
Progress of a phase in a Gantt plan. The card of a phase (a named group of tasks) now says "Done: 72% of its planned days". The number still counts only the tasks that report progress. In the sample plan, only 17% of the phase's days are done.
- ★ Put back the old words, "of the tracked days", before merge. One line.
- Count all the phase's days, so that the new words are true.
- Merge as is.
The page check no longer sees most relation lines. The page check (the command that tests a built page in a hidden browser) makes sure that each relation line on a card (a line that names a linked part, such as "pays ← Shopper") names only the other part, not the card's own part too. The card now shows a relation to one part in a new layout that the check does not look for. In the 42 example documents that ship with the explainer, it reads 252 of 660 relation lines. Before, it read 781 of 781.
- ★ Teach the check the new layout before merge, with a test. A few lines.
- Merge as is. A badly worded relation line passes unseen.
Link buttons that cards drop. A card shows each linked part as a small button that selects that part. When the bold value line under the card's title already names a part in plain text, the card now drops the button. 18 buttons are gone in the example documents. For example, the card of a foreign key (a column that points at a row of another table) no longer links to its two columns. See the scene.
- ★ Keep those buttons. Drop a button only when the same button is already on the card. A small change to the new rule and its test.
- Merge as is. The reader goes back to the diagram to reach the column.
Gantt arrows over bars. An arrow that went far around other bars now runs straight over them. In the sample, a click on the bar where the arrow crosses it selects the arrow, not the bar. The author gets no warning when this happens, and the test that failed on a crossing was deleted.
- ★ Merge, then fix in the next change: the bar takes the click, and the author gets a warning.
- Fix the click before merge.
- Go back to arrows that go around the bars.
Changes that nobody announced. In a box diagram (boxes joined by arrows), the legend (the key that says what each box and line style means) shows fewer keys. More numbered notes (the author's notes on a diagram) lose the line to their part. The commit message does not say so. Neither does the skill's listing entry (its paragraph in the repository's list of skills) or the format reference (the file that tells authors how to write a document). The format reference still says that the legend lists every box and line kind.
- ★ Update the format reference and the listing entry before merge.
- Merge as is.
System map
Parts
The card
The card is shorter. Each fact shows once, a link to one part takes one line, and a card under the diagram has no dot.
- Before
- In an example checkout diagram, a click on Storefront opened the card under the diagram. A black dot sat over Storefront and a second dot at the top of the card. The card said "Downstream 4 parts". Then came "pays ←" over a Shopper button, and a bare "→" over a Checkout button.
- After
- The same click opens the same card with no dots. It says "Leads on to 4 parts", then one line "pays ← Shopper" and one line "To Checkout". Other words also change: "Upstream" is now "Reached from", "Descendants" is now "Parts below it", and "Crossing edges" is now "Connectors across its border".
- Why
- A new reader reads each line once. The dot looked like a numbered note, so it was one more mark to learn.
- Risk
- Link buttons disappear when the value line names their part (decision 3). This happens 18 times in the example documents. The scene of the foreign key card is below.
- The rule that removes repeats guesses by matching words. In the example documents, it hides 71 facts. Most are true repeats, but some lose a number: "Allowed in: 1 of 3" goes, and the buttons under it do not say "of 3". An author's own document can lose a fact in the same way, and no test covers that.
- Under the diagram, only the selection ring (the dark outline around the selected part) and the card title now tell which part the card is about. On a tall diagram, that part can be off screen while the reader reads the card.
- Old code comments in three board diagrams still describe the removed dot. Readers do not see them.
Gantt plans
Arrows between tasks run straight over other bars, and the card of a phase states its progress in new words.
- Before
- In a sample plan with three tasks, the arrow from "Write spec" to "Test plan" went left, around the long "Build platform" bar. The card of the phase "Plan" said "Done: 72% of the tracked days".
- After
- The arrow runs straight down over "Build platform", on a thin strip of background colour. The phase card says "Done: 72% of its planned days". But only 13 of the phase's 78 planned days are done (17%), because "Build platform" (60 days) reports no progress.
- Why
- An arrow looked for a free column (a place on the time axis where no bar is in the way). Arrows that crossed the whole chart to find one were long, and they bunched together. Now, when the free column is more than 96 pixels away, the arrow goes straight.
- Risk
- The new progress words are wrong when some tasks in a phase report no progress (decision 1).
- A click on a bar where an arrow crosses it selects the arrow (decision 4). In the sample, the same click selected the bar before.
- The author is not told when an arrow crosses bars. The test that failed on such a crossing was deleted. The new test allows 296 pixels of sideways travel, not the 96 it names.
- A code comment over the code that picks an arrow's path still says that an arrow never crosses a bar.
Box diagrams
Arrows keep out of areas they do not belong to, labels keep away from other arrows, and the legend shows fewer keys.
- Before
- A box diagram can group boxes in a zone (a framed, named area). An arrow could take its shortest path through a zone that neither of its ends was in. An arrow label could sit as close to another arrow as to its own. The legend listed every box kind and line kind that the diagram used, the plain box ("service") too.
- After
- A path through a zone that neither end is in now costs more than a crossing. If it still happens, the lint (the explainer's text check before a build) warns. A label first looks for a spot 28 pixels from any parallel arrow. If it stays as close to another arrow as to its own, the lint warns. The legend leaves out the plain box. When the diagram uses only one line style, the legend leaves out lines. In the first card scene, "service" is gone from the legend.
- Why
- A line inside a zone looks like a part of it. A label between two lines can name the wrong one. A key that does not tell two looks apart takes room.
- Risk
- The legend change is not documented (decision 5). It changes the legend in 11 of the 42 example documents. When all arrows in a diagram use the same dashed style, nothing explains the dash. The explainer's own design rules say that dashes are explained in the legend.
- Documents that passed the lint before can now get the two new warnings. No example document does: the lint output is the same before and after.
- Labels and arrows in existing diagrams can move, so old screenshots no longer match a rebuild.
- A code comment says that the first label search keeps 28 pixels from zone borders too. The code keeps that distance only from parallel arrows.
Numbered notes
In the full view (the page mode that adds the author's text), more note boxes stand alone, without a line to their part.
- Before
- An author's note shows as a numbered circle on the diagram. In the full view, it also shows as a box with the note text. A thin line joined the box to its part, unless the line was too long or crossed a label or an arrow. In the example documents, 31 of 67 note boxes had a line.
- After
- The line is also left out when it would cross another box, bar or dot. Now 25 of 67 note boxes have a line. In the checkout diagram, note 2 loses its line to Receipts. The numbered circle also moves away from spots that are nearer to another part than to its own.
- Why
- A line through a part that the note is not about seems to point at that part.
- Risk
- The commit message and the docs do not mention it (decision 5). Six notes in six example documents lose their line. The reader then matches the box to its part by the number only.
Chart colours
In a chart, the second data series (one line, or one set of bars) is now green, not ochre. Every chart with two or more series changes colours.
- Before
- The series colours, in order: blue, ochre, green, purple, teal, rose, olive, slate. The second, ochre, was only 18° from the orange highlight colour on the colour wheel.
- After
- Blue, green, purple, teal, olive, slate, rose, ochre. The first four are 95° or more from the highlight colour. A new test keeps the first four 45° or more away.
- Why
- A series close to the highlight colour looks like the author's main point.
- Risk
- Every existing chart with two or more series changes colours when it is built again. Text that names a colour, such as "the ochre line", becomes wrong.
- Charts with five or more series still get colours near the highlight colour: series 5 at 41°, series 7 at 32° and series 8 at 18°. The new test checks only the first four.
The page check behaviour changed, code not
Readers see no change. The check of relation lines on cards now reads only some of them, and it still passes.
- Before
- The page check opens each card and reads its relation lines. It found them by the old card layout, and it read all of them.
- After
- The card shows a relation to one part as a single line, in a layout that the check does not search. On 234 cards, the check finds no relation line at all and skips the test.
- Why
- The card layout changed, and the check did not.
- Risk
- A relation line that repeats both parts, such as "Storefront pays Shopper", now passes unseen (decision 2).
| Example documents, every card opened | Before | After |
|---|---|---|
| Cards | 764 | 764 |
| Relation lines on the cards | 781 | 660 |
| Relation lines that the check reads | 781 | 252 |
| Cards with relation lines that the check does not see at all | 0 | 234 |
Version and listing
The skill's instructions say version 0.4.1. Its entry in the repository's list of skills adds "each fact said once and each relation on one line".
- Before
- Version 0.4.0.
- After
- Version 0.4.1. The description that tells an agent when to load the skill did not change. So the repository rule to run the skill's routing tests (prompts that should and should not load it) again does not apply.
- Why
- The repository rules ask for a new version number and a new listing entry when a skill's behaviour changes.
- Risk
- The entry names only the card change. The arrow, legend, note and colour changes are not in it (decision 5).
How this was checked
- The explainer's own tests, before and after: 742 pass before, 747 pass after, none fail.
- All 42 example documents built before and after, and the lint run on them: no problems either time.
- Every card of every example document compared, before against after: 205 of 764 cards differ.
- In a hidden browser: the note lines counted, the crossed bar clicked, every card opened to count what the page check reads, and the screenshots taken.
- A small sample Gantt plan, written for this report, gives the arrow and progress scenes.
Files
27 files, +299 −162, from 96b61c0 to 3e0cbc9, diffed from the merge base 96b61c0. No lockfiles and no generated files. Each file is listed once, under its main part; a hunk that serves another part carries that part's name.
The card
- Buttons dropped when the value line names the part:
skills/explainer/scripts/client/popover.tsline 123 (spelled), applied on line 124. - Facts hidden by word matching:
skills/explainer/scripts/client/popover.tslines 116–135 (told,listed,rels.has). - One-line relation rows, the layout the page check misses:
skills/explainer/scripts/client/popover.tslines 231–239. - Comments that still describe the removed dot:
skills/explainer/scripts/engine/plans/journey.tsline 237,skills/explainer/scripts/engine/plans/kanban.tslines 195 and 197,skills/explainer/scripts/engine/plans/storymap.tsline 189,skills/explainer/scripts/tests/plans-boards.test.tsline 160.
skills/explainer/scripts/client/popover.ts+68 −13, 7 hunks
skills/explainer/scripts/client/client.ts+10 −16, 6 hunks
skills/explainer/scripts/styles/base.css+6 −16, 3 hunks
skills/explainer/scripts/styles/blocks/plans-boards.css+3 −14, 2 hunks
skills/explainer/scripts/engine/figure/index.ts+10 −10, 6 hunks
skills/explainer/scripts/engine/structures/swimlane.ts+3 −2, 1 hunk
skills/explainer/scripts/engine/structures/uml.ts+1 −1, 1 hunk
skills/explainer/scripts/engine/plans/journey.ts+1 −1, 1 hunk
skills/explainer/scripts/engine/plans/kanban.ts+1 −1, 1 hunk
skills/explainer/scripts/engine/plans/storymap.ts+1 −1, 1 hunk
skills/explainer/references/interactions.md+4 −4, 2 hunks
skills/explainer/references/layouts.md+3 −3, 3 hunks
skills/explainer/scripts/tests/client.test.ts+29 −1, 2 hunks
skills/explainer/scripts/tests/plans-boards.test.ts+11 −11, 5 hunks
skills/explainer/scripts/tests/figure.test.ts+36 −10, 6 hunks
Gantt plans
- Progress words:
skills/explainer/scripts/engine/plans/gantt.tsline 819. The share is computed over tracked tasks only on lines 810–812. - Arrows drawn after the bars, each with its click strip:
skills/explainer/scripts/engine/plans/gantt.tslines 622 and 753. The strip is 12px wide and takes clicks:skills/explainer/scripts/styles/base.cssline 277 (unchanged). - No warning past
DETOUR_MAX:skills/explainer/scripts/engine/plans/gantt.tslines 599–604. Only the no-column case adds toblockedRoutes(line 597). - Loose test bound, 96 + 200:
skills/explainer/scripts/tests/plans-time.test.tsline 292. - Stale comment, "never crosses a bar":
skills/explainer/scripts/engine/plans/gantt.tsline 578.
skills/explainer/scripts/engine/plans/gantt.ts+13 −3, 5 hunks
skills/explainer/scripts/styles/blocks/plans-time.css+3 −0, 1 hunk
skills/explainer/references/blocks/plans-time.md+1 −1, 1 hunk
skills/explainer/scripts/tests/plans-time.test.ts+10 −29, 4 hunks
Box diagrams
- Legend filter:
skills/explainer/scripts/engine/figure/render.tslines 442–444. The reference that is now wrong:skills/explainer/references/format.mdline 192 (unchanged). The design rule on dashes:skills/explainer/references/design-law.mdline 95 (unchanged). - Comment and code disagree on borders in the first label search:
skills/explainer/scripts/engine/figure/render.tsline 390 against lines 423–425. - New warnings:
skills/explainer/scripts/engine/figure/route.tslines 262–264 (zone) andskills/explainer/scripts/engine/figure/render.tslines 169–171 (label).
skills/explainer/scripts/engine/figure/route.ts+16 −3, 5 hunks
skills/explainer/scripts/engine/figure/render.ts+25 −8, 5 hunks
Numbered notes
- A note line is dropped when it crosses any other part:
skills/explainer/scripts/client/client.tslines 1120–1132. Those two hunks are listed under The card, marked "Numbered notes". - Circle placement away from other parts:
skills/explainer/scripts/engine/kit.tslines 609–616 and 653–656.
skills/explainer/scripts/engine/kit.ts+13 −2, 2 hunks
Chart colours
- The new test checks only the first four series:
skills/explainer/scripts/tests/theme.test.tsline 303.
skills/explainer/themes/default.json+6 −6, 1 hunk
skills/explainer/scripts/tests/theme.test.ts+19 −0, 1 hunk
skills/explainer/scripts/tests/charts-grids.test.ts+4 −4, 2 hunks
The page check
- No changed files. The unchanged selector that misses the new rows:
skills/explainer/scripts/commands/audit.tsline 909,.x-pop-rel:not(.x-pop-mentions) [data-ref], .x-link-row[data-ref]. The new rows aredl.x-pop-facts.x-pop-rows(skills/explainer/scripts/client/popover.tsline 232).
Version and listing
- Version:
skills/explainer/SKILL.mdline 8. Listing entry:README.mdline 8.