decisions

decisions — one clean ask, one tap back

Part of the shipwright method — see the shipwright skill for the work-loop this move fits into and when to invoke it.

The scarce resource in async work isn't your reasoning, it's the coworker's attention. A question that bundles ten asks, or names a ticket they don't remember, or forces them to compose a paragraph, burns that attention and stalls the work. This skill treats the ask itself as a produced artifact: framed, context carried, visual where it helps, answerable in one tap.

The shape, per decision:

SCOPE → FRAME → AID → POST → WATCH → CONFIRM → ACT
        the ask  the visual  one-tap-back

You own two things: the decision frame (decision.md, the contract for a single ask) and the grounded-aid renderer (matrix.html + render.mjs, HTML → screenshot). Both live in this plugin's templates/ dir — reference them as ${CLAUDE_PLUGIN_ROOT}/templates/<file> (they sit a level above skills/, not inside it, so a bare templates/… path won't resolve from here). render.mjs needs Playwright (npm i playwright once, or point CHROME_PATH at an existing Chrome — no API key, no network). Everything else you borrow:

Need	Borrow
A pictorial mockup / illustration / wireframe	an image model (gpt-image-2, gemini-3.1-flash-image) — only with a designated key, never a client's
A narrated screen-recording for a genuinely complex ask	fixer / walkabout's CDP recorder + ElevenLabs voice
A still of the real app / the actual issue	playwright-cli or the screenshot pipeline
Posting the ask + reading the answer	google-chat MCP (or whatever channel the person lives in)

The one rule above all others

One decision per ask — and pace the asks to the person's cognitive load and availability. The thing you're protecting is the human's attention, and it fails in two directions:

• Bundling — three decisions in one post. Now answering means composing a paragraph that disentangles which answer maps to which question. The load lands on them.
• Flooding — ten separate posts in a burst. Now they have to scroll back up the thread to reconstruct what's still open and what they've already answered. The load still lands on them, just relocated.

The goal sits between: draw the decisions out calmly, one at a time, paced so each lands when there's room for it. The target experience for the human is — glance at the options, see within seconds what's being decided, judge whether the proposed default looks right, 👍 (or say otherwise), and move on to their own next thing. No composing, no scrolling, no homework. If answering your ask requires any of those, you've offloaded your load onto them, which is the failure this skill exists to kill.

So: several questions are several asks, generally posted one at a time, the next following the previous answer — not fired as a barrage. Dependent decisions must sequence (you need the first answer to frame the second). Independent ones can follow in calm succession, but never bundled into one message and never dumped all at once. Read the room: someone heads-down or mid-meeting gets the ask spaced out, not stacked.

1 — SCOPE: is this even a question for a human?

Most "questions" are things you can resolve yourself: read the code, check the data, pick the obvious default and mention it. Only escalate to a human ask when the answer is genuinely theirs to give: a preference, a policy, a priority, a fact only they hold. If you could find it by looking, look. Then, name who owns the decision (the person who can actually answer), not just "the team".

2 — FRAME: the five parts (this is the whole craft)

Every ask answers these, in this order, and nothing else:

1. The decision — one, specific. ("Should the 'editor' role see every project, or only the ones they're assigned to?" not "how should roles work?")
2. Why it needs you — what only they can answer. Keeps it from feeling like homework you should have done.
3. The choices — concrete, mutually exclusive, named (A/B/1/2).
4. The recommendation + why — so the person can confirm instead of compose. A recommended default turns a paragraph-reply into a 👍.
5. What it unblocks — the stakes, so they know why their ten seconds matters.

Also judge: is it reversible? Not a sixth part of the ask — a posture-setter for how hard you confirm later. A reversible, low-stakes call leans to a lighter ask (or just do it and mention it). An irreversible / regulated / affects-others / multi-owner call earns the heavier CONFIRM (§6): a worded reply, a durable record, and — for multi-owner — every owner, not the first tap. (Examples here are domain-neutral on purpose: the method is the same whether the decision is about a SaaS role, a deploy, a layout, or a comms schedule — don't let one domain's flavour leak into a general skill.)

Carry the context to them. Never make them go look up "#618" or "that GH issue." Bring the relevant thing into the ask: a screenshot of the issue, the line of code, the current state, the before-picture. The person should be able to decide without opening another tab.

Redact what you carry in (a hard gate, not a nicety). A real screenshot pulled into an ask is a publish surface — it lands in a chat channel and may be seen, forwarded, or logged. Before posting any real capture (still / annotated / GIF / video):

• Strip sensitive data — PII (personal data, health records), personal names, client names, account numbers, secrets/tokens (including any in a visible URL). Crop or box them out. When in doubt, use seeded/dummy data for the capture instead of a real record.
• Crop for confidentiality, not just attention — the same tight crop that keeps the aid glanceable also keeps the off-topic sensitive stuff out of frame. Two birds.
• Check the channel's audience — is this a DM, an internal room, or a client-shared space? An aid that's fine in a private dev thread can be a leak in a channel the client reads. Match the data's sensitivity to who can see the post.

This is the same discipline as the fleet's strip-EXIF and no-client-names rules, applied at the moment of the ask. A perfectly-framed decision that leaks someone's record is a net loss.

templates/decision.md is the fill-in-the-blanks version. Filling all five fields is the quality check — if you can't name the recommendation, you don't understand the choice well enough to ask yet.

3 — AID: match the medium to the complexity (gate ruthlessly)

Over-production is a failure mode too. A 90-second narrated video for a yes/no wastes more attention than a text question. Default to the lightest medium that works:

The decision is…	Use
A yes/no or pick-one, self-evident	text + the five-part frame. Stop here. Most asks.
Spatial / "what would it look like"	one screenshot of the real surface, or a wireframe image
About a specific spot on a real screen ("what should THIS do?", "is THIS the right place?")	an annotated screenshot — the real screen with numbered pins on the spot(s) + a legend (annotated.html). Carries the actual pixels into the ask; grounded by construction. Keep to 1-3 pins or it's several decisions.
A change only visible in motion — a transition, an interaction, a before↔after	a short silent GIF (autoplay-loops in chat); a narrated video only if it's long / multi-screen / the why needs a voice. See Real captures below.
A comparison across options × dimensions	a decision matrix (grounded HTML → screenshot, see below)
Two genuine approaches, decided by 2-3 trade-offs	a compare card — A vs B, trade-offs as the rows (compare.html)
Approving a set of changes (a batch / deploy go-no-go)	a manifest — one row per item, short risk tag, one go/no-go (manifest.html)
A precedence / classification branch ("what order do the rules fire?")	a tree — first-match-wins ladder, contested rule highlighted (tree.html; pure HTML/CSS, no network — for a large graph use graphviz dot -Tpng instead)
A flow / sequence you must walk through	a mermaid or graphviz diagram generated from the real code
Genuinely complex, multi-branch, needs walking through	a narrated screen-recording (borrow fixer/walkabout) — the rare exception

Real captures: crop tight, then pick still / GIF / video by what the decision hinges on

The real-app aids — a screenshot, an annotated screenshot, a GIF, a video — are all grounded by construction: real pixels, nothing invented. They're one family, distinct from the structural aids (matrix/tree = HTML render) and the pictorial ones (wireframe = image model, which invents). Within the real-capture family, fidelity is its own axis — and the rule is the same as everywhere else: the lightest thing that shows the property you're deciding on.

The decision turns on…	Capture	Why
a static property — where a thing is, what a label says, a layout, which of two states	a cropped still (pin it if needed)	one frame holds the whole answer; absorbed at a glance
something only visible in motion / over a sequence — a transition, a janky interaction, "what happens when you click"	a short silent GIF	a still literally can't show it; autoplay-loops in chat, no controls to fight
a before↔after where the delta is subtle or spatial	an A/B toggle GIF (loops before→after→before)	the toggle makes the change pop; two side-by-side stills make the eye hunt for the difference
a property that needs narration while you watch, or is long / multi-screen	a narrated video (borrow fixer/walkabout)	the rare, heaviest case; a click-to-play friction cost, so earn it

Two rules that do most of the work:

• Crop to the decision. The default still is a partial screenshot — just the region in question — not the whole page. Full-page only when the cross-page spatial relationship is itself the thing being decided ("should this section sit above that one"). Everything the decider doesn't weigh is noise, same as a crammed table.
• Escalate only when the lighter medium genuinely can't show it. Still < GIF < video in both production cost and the decider's attention. A GIF of something a still would've shown is worse than the still — it makes them wait for the loop to come back to the frame that mattered. That's over-production, one tier up. Motion is for properties that only exist in motion.

(The GIF/video capture itself is fixer's / walkabout's CDP recorder — decisions borrows it, same as a narrated recording. This section is only about when to reach for each.)

Keep the aid glanceable — prose inside it is the failure

A visual exists to be glanced at in seconds, not read. The moment the decider has to read sentences inside it, it's text wearing a table's clothes — and it costs more attention than plain text would, because they came to it expecting a glance. The coworker's attention is the scarce resource (the whole premise); a crammed visual spends it twice and breeds the decision-fatigue that makes people defer the ask.

So the structure carries the argument and words are labels, not sentences:

• No full sentences inside the card. Title ≤ ~6 words; cell values are symbols or short labels; option chips ≤ ~6 words.
• No explanatory paragraph, no reassurance text. "Grounded / nothing invented / read from the live config" reassures you, the author — it serves your anxiety, not their decision. If it must be said at all, it goes in the one chat message, never in the aid.
• The delete test: strike every word that isn't load-bearing. If the decision still reads from the structure alone, those words were tax.
• The tell: if a matrix needs a sentence to be understood, the columns are wrong — fix the structure, don't annotate it. (Two cells that contradict — "in the menu ✓ / can open ✕" — say "broken" with no prose at all.)
• The exception — naming labels, not explaining prose. Some aids legitimately carry a short label that names a part: the annotated screenshot's pin legend (1 → "the date field") and the tree's ordering hint ("first match wins") are labels, not explanations. They're allowed. What's banned is the explanatory sentence and the reassurance paragraph — the line that argues, justifies, or soothes. Label the parts; never explain the decision inside the card. (So the "delete test" trims sentences, not the legend that makes annotated legible.)

The best aid is the one where the structure does so much work that almost no words are left. If you can't get there, that's the signal the decision is better as plain text — the lightest medium — than as a visual at all.

Ground the visuals, or they mislead

A generated flowchart or matrix that's subtly wrong is worse than none — it anchors the person on a false model of the choice. So split the visual job by tool:

• Structure (matrices, flows, decision trees, tables): render from the real facts with HTML / mermaid / graphviz, then screenshot. No hallucination at render — the screenshot is exactly the HTML you wrote, so no model invents a cell. (That's the guarantee; it does not make the content true — you still have to put correct facts in. Deterministic ≠ accurate.) No key, fast. This is the default and it carries most asks. (templates/matrix.html + render.mjs.)
• Pictorial (wireframes, "what the screen feels like", illustrations): an image model (gpt-image-2, gemini-3.1-flash-image) is the right tool — but it invents detail, so:
  • Client-facing decisions get the grounded structural aid, not a generated image, OR a generated image with a clear "illustrative only" caption.
  • Internal asks can use generated images freely.
  • Use a DESIGNATED key allocated for this (a fleet image-gen key in the host's secret store with explicit agent access). Never scavenge a client's or a project's key for a cross-purpose ask — that's a credential-context violation. If there's no designated key, fall back to the HTML aid and say so.

4 — POST: one context message, each choice its own message

Post the framed ask, then each choice as its own separate message in the person's channel. The grounded visual rides on the context message. The per-choice split is what makes the answer one tap: the person 👍 the message for the option they want, or replies with its number. No composing required.

[context msg + visual]  "One decision to unblock X. <frame>. Two options below —
                         just 👍 or reply the number. Or tell me if I've framed it wrong."
[choice msg 1]          "1️⃣ <option A> (recommended). <one line why>. 👍 or reply 1."
[choice msg 2]          "2️⃣ <option B>. <one line why>. 👍 or reply 2."

The footer "or tell me if I've framed it wrong" is the escape hatch — it costs a clause and saves the worst case (a clean answer to the wrong question). Honour it in CONFIRM (§6).

Always carry a text fallback: if the channel can't surface reactions, the person replies "1". Never make answering require watching a video or parsing an image.

5 — WATCH: poll for the tap

Watch the thread for a 👍 on a choice message or a one-word reply. Treat the worded reply as the primary signal and the 👍 as the nice-to-have — many chat APIs read reactions unreliably (some never surface them at all), so don't hang the whole loop on seeing a 👍 you might miss. A reply naming the option is unambiguous and always readable.

If it goes quiet past a sensible window, a single gentle nudge on the same thread — never a re-post of the whole question. If the nudge also goes silent: for a reversible call you may proceed on the recommended default and say so ("going with 1 unless you say otherwise"); for an irreversible / regulated one, escalate to the owner directly or hold — never silently assume the default.

6 — CONFIRM: read it back before you act

The ask was a produced artifact; the answer deserves the same care. Don't treat a tap as a clean, final, correct instruction — close the loop:

• Read back the consequence, not just receipt. Not "got it, option 1" but one line restating what that choice means and does next: "Got it — editors see every project; I'll wire role-enforcement to that, live next deploy." This catches a mis-tapped reaction or a misread before any work starts. One line — don't re-open the decision.
• Leave an escape open, and honour it. Every ask carries an implicit "none of these / not quite / I've mis-framed it" path (a footer line: "…or tell me if I've framed it wrong"). A "yes, but…" or "actually…" reply is a reframe signal, not noise — pause, don't proceed on the recommendation, fold in what they said and re-ask. This is the recovery SCOPE can't give once the ask is already out.
• Match the confirmation to the stakes (set in FRAME):
  • Reversible / low-stakes → the tap is enough; the read-back is a courtesy. Proceed.
  • Irreversible, regulated, money, affects others, multi-owner → require an explicit worded reply (not a bare reaction), and write a one-line durable record where the work is tracked — who decided / what / when / on what evidence. A reaction that scrolls out of the thread is not an audit trail.
• Multi-owner → don't treat one tap as consensus. If the decision needs two people (FRAME named them), get both; if they conflict, surface the conflict and let them resolve it — never pick for them.

7 — ACT

Do the thing. Then, if the decision changed course, close the loop wherever the work is tracked.

Quality gates (these are the point)

Gate	Why
One decision per ask, paced to their load	bundling and flooding both dump the load back on the human
Real captures redacted + channel-checked before posting	an aid is a publish surface; a leaked personal or client record outweighs a perfect frame
All five frame fields filled, including a recommendation	no recommendation means you don't understand the choice well enough to ask
Context carried into the ask	"go look up #X" offloads your work onto the busy person
Answerable in one tap	a 👍 beats a composed paragraph; if it needs a paragraph, the frame isn't done
Structural visuals grounded, not generated	a wrong diagram anchors a wrong decision
Generated images use a designated key, never a client's	credential-context is non-negotiable
Medium matched to complexity	a video for a yes/no wastes more attention than text would
The answer is read back before you act on it	a tap is not a verified instruction — a mis-tap or misread caught after the work is the expensive one
An escape hatch on every ask, honoured	a clean answer to the wrong question is the costliest outcome the frame can't prevent
Irreversible / regulated / multi-owner → worded reply + durable record, every owner	a 👍 that scrolls away can't answer "who approved this, and when?"; one tap isn't consensus

The earned-place test: if a clarifying question went out as a wall of asks, or made the person go look something up, or forced a paragraph when a 👍 would do, decisions wasn't used.