← Studio library

Concept note, the format

Reference notes. Source retained; historical claims may need rechecking.

Studio reference illustration

Format: concept note (with its drawing)

The opening artifact of any development operation (standing procedure step 1; platform-change playbook step 0): what the ideal situation is and why, ending in numbered decisions for Frank. Text acceptable, a drawing is better — pre-verbal first: the idea must read before the words do.

The named exemplar (Frank: "It's a nice drawing", 2026-07-23)

Why it is good (copy these properties, not the pixels)

  1. The convergence is the picture. Seven scattered, tilted, two-colored boxes (today) funnel through one calm arrow into one aligned panel with two green question blocks (the ideal). Cover the text: the story survives — the 5-second test passes.
  2. The ideal is drawn as the product would show it — a simulated settings panel in the product's basic look (proposal mode), not an abstract diagram: the reader sees a screen they could touch, not a scheme they must decode.
  3. Busy vs calm is the argument. The left side is deliberately uncomfortable (tilt, scatter, two vocabularies); the right side is one box, two questions. The visual IS the case for the change.
  4. The note carries the decisions — numbered, few (5 max), each answerable with one word — and the mapping table (what each of today's things becomes), so the vision is checkable, not just inspiring.
  5. Made by the visual-concept-expert agent; house rules (light theme, tokens to audit 0, sentence case, no invented chrome).

How the note is written (the drafting law, Frank 2026-07-26/27, from the publishing concept)

Second named exemplar: 1 - Digital Government Platform/eRegistrations/publishing-time/concept-publishing-fast.md + its read view and drawing. Four rewrites produced these rules; apply them from the first draft.

Shape — one spine, never two. 1. Why the problem exists, then the steps that remove it, then decisions. Causes lettered, steps numbered, and every step names the causes it kills. Two overlapping lists in one note (five "accelerations" and four "phases") makes it unreadable even when both are correct. 2. Each step is one proposal, one build, one pull request, useful alone. Say which is done, which is being built, which is shelved and why. A shelved step stays visible with its reason. 3. Name a step by its real name ("micro-publish"), not by a description of it. 4. A finished step keeps its content inside itself — including its defects. Never float a section about step 1 at the end of the document. 5. Never raise a defect without its correction, side by side. Two columns: what is wrong · what we do about it.

Numbers — measure, do not infer. 6. Take the figure from the running system, not from reading the code. The publishing diagnostic ranked cost drivers structurally; one log read cleared three of them and moved the true cost elsewhere. Say plainly when measurement refutes an earlier document. 7. Whole first, then the split. Never headline a partial measure: "2 min 43 s to reach the workflow step" reads as the publish time and misleads every reader. The publish was 7 min 35 s. 8. Open every black box. A row holding most of the total is not an answer; decompose until nothing large is unexplained. 9. Mark derived figures as derived and say what is logged directly. Honesty about a number's provenance is part of the number. 10. Name where it was measured (instance, service, date, and the log line verbatim). 11. Each step carries its gain against that true total.

Words — every word earns its place or goes. Full law: memory feedback-titles-words-digits.md. 12. A heading is the idea, never its announcement. "The idea in five lines" → "Publishing should cost what the change costs". 13. Plain concrete word over category word; cut "the" and anything carrying nothing, in prose and in chrome (nav labels, captions, buttons). 14. No commas in titles or labels.

Decisions. 15. Name options by what the reader can do afterwards, never by the code they touch. An option described by its plumbing cannot be decided. 16. Recommendation inside the ask, marked, with one line of why. 17. Keep the document's own decision numbers everywhere, including in chat replies. 18. Settled decisions stay on the page, marked settled, with date and who decided.

The pages. 19. Every section collapsible, each step its own fold; some open on load, some closed, all foldable. Sub-sections too (Frank, 2026-07-27): if a block has bands, rows or groups inside it, each of those folds as well, not only the outer section. 19a. One switch at the top opens and closes everything (Frank, 2026-07-27, all documents). It lives in the top navigation bar, says what it will do next ("open all" / "close all"), and toggles every <details> on the page. A reader who wants the whole thing, or wants it out of the way, gets it in one click instead of ten. 20. A real top navigation bar, not a line of links — brand · current page · the operation's other pages · "More" for sources. Pattern: smartzones.world/filomy/ (.topbar + .here + nav + details.more). 20a. The head is exactly four things (Frank, 2026-07-27): title · a one-line qualifier that says something ("Five causes, five steps, four open decisions", not "concept note") · ONE provenance block · ONE row of index chips. Nothing else stands above the first real sentence. 20b. Never repeat the navigation bar as a line of links in the body. The old "workbook strip" is now the bar; two things saying the same means the lower one goes. 20c. No standalone status line. "Status / Origin / For X's verdict" folds into the first sentence of the provenance block. One block of provenance, never three lines of it. 20d. The index is ONE ROW OF SMALL PILL CHIPS — quiet grey, pill radius, ~12.8px, no box, no fold, no heading above it, wrapping on narrow screens. Never a boxed multi-column grid: on the publishing note that grid took more height than the sections it pointed to. (Same rule as /er-platform-change §3 "Index chips — ONE row of pill links"; the concept note inherits it.) Measure the fix: the first real sentence should visibly rise up the page. On the publishing note the head lost 183 px. 21. No link ever lands on a .md when an HTML view exists. 21a. Links everywhere, including inside the text of a cell (Frank, 2026-07-27). Not only the row's name and its obvious link column: the phrases inside every cell too. "2 risks found in an audit" links the audit. "Frank, on four things" links those four. A count like "14" links the list it counts. An action cell IS the link ("ask for the merge" opens that pull request). Nothing anywhere is named and left for the reader to find. 22. Verify the rendered page yourself before reporting it done — grep the file for the banned wording and stale links, read the headings back. A correction counts when it is true on the page, not in the source or in an agent's report.

Companions

The workbook palette (Frank: "a good palette", 2026-07-23)

One operation's pages share the concept's palette (OKLch, cool 250-255 hue family): --bg oklch(97% 0.008 250) paper · --ink oklch(27% 0.03 255) · --grey oklch(48% 0.015 250) secondary text (the concept's box-grey 62% is for shapes, not prose) · --line oklch(90% 0.008 250) · accent green family for the ideal/new: oklch(46-56% 0.10-0.11 155) + soft oklch(95% 0.035 155) · quiet blue for "new" chips oklch(50% 0.12 250) + soft. The concept sets the palette; every other artifact of the workbook inherits it.

Source previewDownload original source