| name | decision-review-deck |
| description | Create a light, presentation-style markdown deck — ASCII diagrams, skimmable in under 2 minutes — that summarises the high-level decisions made in a piece of work for an async team review. Use when the user wants to present decisions to the team, prepare a review, make a decision walkthrough, or a lightweight "what I decided and why" summary. |
| license | personal |
| compatibility | all |
| metadata | {"audience":"developer"} |
Decision review deck
Turn a chunk of work into a 2-minute, skim-friendly deck a colleague reads async and immediately
"gets" — the decisions and the why, not the implementation.
Principles (what makes it land)
- The diagram is the argument. Each decision earns its slide with a
Before → After (or flow)
that shows the change visually; the bullets only annotate. If you can't draw it, you don't
understand it well enough yet.
- Name the fork, not just the choice. Every decision states the alternative you rejected and the
trade-off ("app-version gating is all-or-nothing"). A decision with no visible alternative reads
as a fact, not a decision.
- Headline every decision.
Decision · <punchy claim> — the reader should get the gist from the
titles alone.
- Coin a mantra. One short, memorable phrase per idea sticks better than a paragraph
("narrow, never widen", "B = A minus the token", "cheaper to change a decision than a diff").
- Frame the problem as tension. Open with two forces that pull apart (new apps want X; old apps
want not-X). The decisions are how you resolved the tension.
- One visual vocabulary. Reuse the same glyphs everywhere —
──▶ flow, [ ] decision point,
└ sub-note, ▲ inline callout — and align columns so it scans as a diagram, not text.
- Surface the non-obvious constraint. Call out the hidden invariant that makes the design safe
("same FHIR identity ⇒ history unaffected"). That's often the line a reviewer most needs.
- End with the map. Close on a sequencing diagram (parallel vs dependent) plus a done/next
status legend, so "where are we" is answered at a glance.
Output
- One markdown file, dated, in the relevant project dir:
<project>/<YYYY-MM-DD>-<topic>-review.md.
- First line marks it a temporary review artifact (delete after the review).
Hard rules (these keep it light)
- Slides, not prose. Separate each slide with
---. Aim for 6–9 slides total.
- One idea per slide. A title, a small ASCII diagram, and ≤3 bullets. If it needs more, split it.
- ASCII first. Prefer a diagram over a paragraph. Every decision slide gets a before→after or a flow.
- High level only. Decisions + trade-offs + sequencing. NO file names, function names, code, or test counts.
- 2-minute budget. If it can't be read in 2 minutes, cut slides. Front-load the punchline.
Slide skeleton
- Title + one-line context (what + why now).
- The problem — one ASCII diagram of the pain.
3.–N. One slide per decision:
Decision · <one line> + before→after ASCII + why (≤3 bullets, name the rejected alternative).
N+1. Delivery / sequencing — ASCII of the slices and their order + a tiny status legend.
ASCII patterns to reuse
Before / after:
Before: answer ──▶ [server logic decides] ──▶ reject
After: answer(+token) ──▶ [token present?] ──▶ reject / continue
Flow / negotiation:
client ──capabilities:[X]──▶ server ──picks──▶ variant
Sequencing (parallel + dependencies):
S1 ─┐
├─▶ S3 ─▶ S4 ─▶ S5 (S1 ∥ S2)
S2 ─┘
Process
- Pull decisions from the task file / proposal
decisions (the durable record), not from the diff.
- For each: write the one-liner + the alternative that was rejected.
- Draw the smallest ASCII that conveys it.
- Read top to bottom; if over ~9 slides or 2 minutes, cut.
- Tell the user the path and that it's a temp artifact.
When to use me
User wants to present / share / walk through decisions, prep a quick review, or a light deck/summary
for the team. Not for full proposals — those are long-form (see proposal docs).
