The hat
When several ways exist to solve a design problem, do not vibe-rank in chat. Run this loop and leave the artifacts in a living note (repo file, not a premature ADR).
Worked example of the shape (not the product decision): the living note from #1564 / #1570 (docs/to-json-schema-wiring.md on simplify-docs until that restructure lands on dev). Copy headings from NOTE-TEMPLATE.md.
If the problem itself is still mushy, grill first (grill-me / grill-with-docs), then come back here to score options.
Loop
- Name the problem — what must be true when we are done, not the first idea that showed up.
- Split composing layers if “solutions” are not the same kind of thing. Layers are dimensions that compose, not rivals in one list (how you type a callback vs where the wrapper lives). Do not flatten them into one false choice.
- Put every option in the hat, including already-rejected and out-of-scope ones, so they get scored instead of silently returning.
- Pick metrics that match the pain. Invent what fits (honesty, tax fairness, simplicity, DRY, composability, vendor neutrality, footguns, elegance, teachability, maintenance hell).
- Evaluate each hat item against those metrics in prose. A table is welcome for a close call; a vibe ranking with no scores is not.
- Tier list (S / A / B / C / D, plus E if needed). S is the default story. A is optional tuck-away or distribution, not a blocker. A complete answer may be a stack (one pick per layer), not a single winner.
- Show usage for S and A across each real use case so the ranking is not abstract.
- Keep a living note. New ideas get slotted; do not restart the write-up.
- Do not ship A-tier extras that are not needed to close the current change.
Living note
Write or update a repo file (typically docs/<topic>.md). Not chat-only. Not an ADR until the decision is hard to reverse, surprising without context, and the result of a real trade-off.
The note must contain:
- Problem statement
- Layer map — orthogonal dimensions; items on different layers compose
- The hat — numbered inventory of every option, grouped by layer (
A1, B1, …)
- Metrics — named, with the question each one asks
- Evaluation — each hat item scored in prose against the metrics
- Tier list — S through D (or E), including stacks where layers combine
- S/A usage — concrete code (or equivalent) per real use case
Layers vs a false choice
If two options are not substitutes, they are layers, not rivals.
False choice: “inline helper vs typed callback vs CLI recipe.”
Layers:
- Typing — what is the callback parameter?
- Placement — where does the wrapper live?
S can be a stack (one pick per layer). Rank stacks as answers to the whole problem.
Rules
- Rejected and out-of-scope options stay in the hat and get scored. Silent return is how bad ideas come back next week.
- S is what you ship now. A is optional. Do not block the change on A.
- Slot new ideas into the existing note. Do not rewrite from scratch.
- Do not copy a prior eval’s decision into a new problem. Copy the shape.
1---2name: the-hat3description: Compare design alternatives with a hat → metrics → tier-list loop, splitting composing layers and keeping a living note. Use when there are multiple ways to solve a design problem, the user says "throw it in the hat" or "/the-hat", asks for a tier list, design eval, or composing layers/dimensions, or when options look like they compose rather than compete — even if they have not named this skill.4---56# The hat78When several ways exist to solve a design problem, do not vibe-rank in chat. Run this loop and leave the artifacts in a **living note** (repo file, not a premature ADR).910Worked example of the *shape* (not the product decision): the living note from #1564 / #1570 (`docs/to-json-schema-wiring.md` on `simplify-docs` until that restructure lands on `dev`). Copy headings from [NOTE-TEMPLATE.md](NOTE-TEMPLATE.md).1112If the problem itself is still mushy, grill first (`grill-me` / `grill-with-docs`), then come back here to score options.1314## Loop15161. **Name the problem** — what must be true when we are done, not the first idea that showed up.172. **Split composing layers** if “solutions” are not the same kind of thing. Layers are **dimensions that compose**, not rivals in one list (how you type a callback vs where the wrapper lives). Do not flatten them into one false choice.183. **Put every option in the hat**, including already-rejected and out-of-scope ones, so they get scored instead of silently returning.194. **Pick metrics** that match the pain. Invent what fits (honesty, tax fairness, simplicity, DRY, composability, vendor neutrality, footguns, elegance, teachability, maintenance hell).205. **Evaluate each hat item** against those metrics in prose. A table is welcome for a close call; a vibe ranking with no scores is not.216. **Tier list** (S / A / B / C / D, plus E if needed). S is the default story. A is optional tuck-away or distribution, not a blocker. A complete answer may be a **stack** (one pick per layer), not a single winner.227. **Show usage for S and A** across each real use case so the ranking is not abstract.238. **Keep a living note.** New ideas get slotted; do not restart the write-up.249. **Do not ship A-tier extras** that are not needed to close the current change.2526## Living note2728Write or update a repo file (typically `docs/<topic>.md`). Not chat-only. Not an ADR until the decision is hard to reverse, surprising without context, and the result of a real trade-off.2930The note must contain:3132- **Problem statement**33- **Layer map** — orthogonal dimensions; items on different layers compose34- **The hat** — numbered inventory of every option, grouped by layer (`A1`, `B1`, …)35- **Metrics** — named, with the question each one asks36- **Evaluation** — each hat item scored in prose against the metrics37- **Tier list** — S through D (or E), including stacks where layers combine38- **S/A usage** — concrete code (or equivalent) per real use case3940## Layers vs a false choice4142If two options are not substitutes, they are layers, not rivals.4344False choice: “inline helper vs typed callback vs CLI recipe.”4546Layers:4748- **Typing** — what is the callback parameter?49- **Placement** — where does the wrapper live?5051S can be a stack (one pick per layer). Rank stacks as answers to the whole problem.5253## Rules5455- Rejected and out-of-scope options stay in the hat and get scored. Silent return is how bad ideas come back next week.56- S is what you ship now. A is optional. Do not block the change on A.57- Slot new ideas into the existing note. Do not rewrite from scratch.58- Do not copy a prior eval’s *decision* into a new problem. Copy the *shape*.
yamcodes