the-hat

Files (2)

• NOTE-TEMPLATE.md
• SKILL.md

SKILL.md (first lines)

# 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 a hat loop later promoted to an ADR: [#1564](https://github.com/yamcodes/arkenv/issues/1564) / [#1570](https://github.com/yamcodes/arkenv/pull/1570) became [ADR 0025](../../docs/adr/0025-to-json-schema-escape-hatch.md). Copy headings from [NOTE-TEMPLATE.md](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

1. **Name the problem** — what must be true when we are done, not the first idea that showed up.
2. **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.
3. **Put every option in the hat**, including already-rejected and out-of-scope ones, so they get scored instead of silently returning.
4. **Pick metrics** that match the pain. Invent what fits (honesty, tax fairness, simplicity, DRY, composability, vendor neutrality, footguns, elegance, teachability, maintenance hell).
5. **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.
6. **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.
7. **Show usage for S and A** across each real use case so the ranking is not abstract.
8. **Keep a living note.** New ideas get slotted; do not restart the write-up.
9. **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*.

From yamcodes/arkenv, MIT.

More from yamcodes/arkenv