miadi-orchestration-kit

Proposal visualization

Why this exists

On 2026-09-24 the owner approved the packaging of Miadi’s tide reply annotator from one page, and said of its before/after figure: “it really enabled me to approve this phase very rapidly”. The owner asked that the pattern be kept for every agent that shows its work visually, not only Claude Code. This skill is that pattern. The page it came from is reference/annotate-core-and-ui.html. Read it before building a new one.

Tracked in jgwill/miadi-orchestration-kit#53.

The page’s one job

A reader who has not followed the work sees what exists now, what will exist after, what they are being asked to decide, and can answer each decision by commenting on it. Everything on the page serves one of those four things.

Parts, in order

Leave out any part the proposal does not need. Keep the order of the ones you use.

  1. Header. A name for the proposal (two to four words), one sentence saying what will exist, a status chip (“Awaiting your go (D4)”), and one short card per package or unit being created or changed. Then a “How to respond” line: “Comment on a card or cite its code. A go on D4 starts the build.”
  2. Who gets what. One card per audience (the people using it, other apps or teams, the platform’s maintainers). Each card ends with a “Today:” line, so the difference is visible without reading further.
  3. Today → after. Two columns of facts. Today is current reality, with paths and numbers. After is written as things that will exist, never as problems removed.
  4. Before / after figure. Two panels drawn on the same grid. Draw the difference: the arrow that appears, the arrow that disappears, the arrow that changes direction. A caption states that change in one sentence. This is the figure the owner approved from. Do not skip it when the proposal changes structure.
  5. Ownership figures. A flow or loop where each step is coloured by who owns it (the new package vs the host app, for example), and a nesting figure when data or types split between layers. Say in the caption what the colours mean.
  6. Mechanism figure, only when a subtle behaviour is the value being preserved, for example a timeline of an iOS selection event and a grace window.
  7. Clickable wireframe. The real screen the change lands on, as it will look after the change, in the product’s own look. It runs the proposed behaviour where that is cheap. When a second host will use the same component, put a second frame beside the first in that host’s colours.
    • Build it from the product’s real content: its real page (the same breadcrumb, title and cards), its colour tokens, and real records from the work, such as the images, names and dates already in the folder. Mark what is example data “example”. Mark a real item placed where it is not yet placed “real, proposed placement”.
    • Why: on 2026-10-07 the owner said of the episode-images wireframe that it showed “the actual result that it would look like on the user interface”. He read the proposal from the screen he already knows, not from a diagram of it.
    • When more than one owner renders the screen, offer a toggle, on by default, that outlines each region and labels who renders or supplies it. It is suggested, not required. The owner called it an interesting experience because it put ownership on the screen itself.
  8. Reference. The public API or config as tabs, one per entry point.
  9. What review changed, when a reviewer or another agent corrected the draft: one coded card per correction with its evidence path.
  10. Build order. Numbered steps (a real sequence), each with the check that closes it, such as a test file, a verify script or a deploy.
  11. Risks, decisions, questions. Coded cards (below).
  12. Footer. Sources, who drafted and who reviewed, and the date the evidence was checked.

Coded cards

Figures

Contrast is computed, never judged by eye

Before publishing, compute every text colour against every surface it sits on, in both themes. Body text needs 4.5:1. Never dim text with opacity: it blends toward the background and can halve the ratio. Use a muted colour token instead.

const L = h => { const c = [0, 2, 4].map(i => parseInt(h.slice(i + 1, i + 3), 16) / 255)
  .map(v => v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
  return 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2] }
const ratio = (a, b) => { const x = L(a), y = L(b); return (Math.max(x, y) + 0.05) / (Math.min(x, y) + 0.05) }
// run ratio(text, surface) for every pair; anything under 4.5 changes before publishing

Evidence

Theme and layout

Revisions after comments

When the owner comments:

  1. Read every comment, including the threads your tools cannot reply to.
  2. Add a “Revision N” band under the header. It lists each comment and what it changed, by code (“D1 approved”, “Q4 answered: …”, “N1 added from your /chronicle comment”).
  3. Mark decided cards as decided and say who decided. Leave only open items in the Decide section.
  4. Republish to the same address, so the comments stay attached.

Publishing

Before you publish

🌸: A reader who sees exactly what changes can decide in minutes, and one who has to piece it together from prose often cannot decide at all.