figure-it-out

name	figure-it-out
description	Explore and debate options with fresh documentation and research before committing. Use for a real decision with multiple plausible approaches — library/framework choice, architecture, API/schema design, algorithm selection, or a costly communication/strategy call. Enumerates research domains, checks current docs and evidence-based methods, and weighs options on correctness, elegance, and bloat. Do NOT use for divergent ideation (brainstorm), extracting user intent (elicit), or reviewing finished work (quality-review).
allowed-tools	*

Figure It Out: Evidence-Backed Option Weighing

No recommendation without current evidence. Training data is stale; verify before staking a position.

Stakes set depth. Investigate as if your recommendation ships unreviewed — a decision gets built on it with no second analysis pass. That standard, not "it's just advice," sets how hard you research. Before researching, write the investigation plan: the sub-questions each domain (Phase 3a) must answer, then work the list. Plan the investigation, not the answer — committing to a conclusion before the evidence is the failure this skill exists to prevent.

When to Use

A real decision with two or more plausible directions: library or framework choice, architecture, API or schema design, algorithm selection, communication strategy, policy call. User invokes /figure-it-out.

Skip for:

• Single obvious answer → just do it
• Need more options first → brainstorm
• Don't know what the user wants → elicit
• Reviewing existing code → quality-review

Workflow

Copy this checklist and track progress:

- [ ] Phase 1: Frame the decision in one sentence
- [ ] Phase 2: Generate 2-3 concrete options
- [ ] Phase 3a: Enumerate relevant research domains (multiple)
- [ ] Phase 3b: Research each named domain
- [ ] Phase 4: Debate, steelman both sides, commit to one

Phase 1: Frame

One sentence: what are we deciding, and what would make a choice wrong? If you can't write it, call /elicit — the option space is undefined.

Phase 2: Generate options

Two or three, concrete enough to debate. For each: what (one sentence), looks like (sketch — code, config, or example), smallest viable form. Two strong options beat five hedged ones.

Phase 3: Enumerate domains, then research

3a — Name the domains. Before searching, list every domain your decision touches — explicitly, in writing. A single-domain list means you haven't looked hard enough; decisions live at the intersection of multiple bodies of work.

Worked example — drafting a one-line block message for a CLI hook isn't just "writing copy." Domain list:

• Developer error-message UX research (Nielsen Norman, humanized-error patterns, name-the-gate-condition principle)
• Instructional design — state the rule, the violation, the next action
• High-frequency-interruption tone calibration (annoyance compounds across a session)
• Accessibility — screen readers, line length, no color-only signals
• Recovery ergonomics — can the user unblock themselves from this text alone?
• Observability — does the message give enough to file a useful bug or self-diagnose?

Most agents pattern-match "it's just an error string" and skip all six.

3b — Research each named domain. For every one:

• Library / API: Context7 for live docs and version status
• Established methods: web search the domain name plus "research," "method," or "evidence-based" — surface named approaches you didn't know existed
• Patterns and tradeoffs: recent postmortems, benchmarks, contested debates
• Boundary conditions: what breaks under scale, load, failure, or adversarial input

Model note. This research runs inline by default — no sub-agent. If your harness fans the domains out to sub-agents, treat them as discovery/producers, not reviewers: angle diversity is the lever (more domains, fresh interpretations), and cheaper or varied models are fine, because you synthesize and adversarially verify their findings in Phase 4. quality-review's no-weaker reviewer rule does not apply here — nothing is reviewing your own work yet.

The trap. "This is just taste / style / vibes" is the warning sign, not the exit. Your training data taught you which domains feel aesthetic — those are usually the ones with the most established research you haven't met. Run 3a anyway.

Only-valid skip. The domain list comes up genuinely empty after honest enumeration: no humans affected, no measurable outcome, reversible in seconds. State the skip and why.

Phase 4: Debate and commit

Argue both sides. Steelman the option you don't prefer first. For each, write:

• Correct: solves the actual problem, including edge cases?
• Elegant: readable, minimal, free of incidental complexity?
• Cost: lines, dependencies, abstractions, ongoing maintenance.

Then commit. Format:

Recommend X because [single load-bearing reason]. Y was close on Z but loses on W. Cite: [doc or research link].

Premortem: assume X has failed 6 months from now — the most likely cause is [Z]. If Z is plausible, mitigate it now or reconsider.

Next: [concrete action to take now — install, write, edit, ask].

The **Premortem:** line disconfirms your choice, not just the alternatives you steelmanned — the option you stop scrutinizing the moment you pick it is the one that bites. Keep it to one sentence.

Close with the **Next:** line — one imperative naming the file to edit, the command to run, or the question to ask (the stop hook reads it for the re-entry brief). A recommendation that doesn't say what to do now leaves the reader stranded.

If two options tie on correctness and elegance, the smaller one wins.

No hedging. If you genuinely can't pick, you're missing one input — name it and ask one question. "Either could work" is not an answer.

Voice: plainspoken and concise — write to be scanned.

Avoid bloat.