claude-unknowns

/unknowns — ask your agent what you're not seeing, and get answers, not warnings.

A Claude Code skill that runs a structured blind-spot hunt + war-table analysis on whatever you're about to build — and refuses to hand you a bare list of risks: every finding must ship with its fix.

you>  /unknowns   (against the spec you just wrote)

agent>
  CRITICAL
  1. Your installer assumes zsh — on CI and most Linux boxes /bin/sh is dash; the
     array syntax on line 12 silently no-ops there.
     → Fix: POSIX-only constructs; add a dash job to the test matrix.
  IMPORTANT
  2. Unknown known you're carrying: "config lives in ~/.config" — you set
     XDG_CONFIG_HOME globally on your machine; most users don't.
     → Fix: read XDG_CONFIG_HOME with a ~/.config fallback; test both.
  FEATURE IDEAS (opt-in)
  3. A --dry-run flag would let people trust the magic before enabling it. (low effort)

What it actually does

On /unknowns [topic] (alias /uu) the agent sweeps the four quadrants — weighted toward the two you can't sweep yourself:

Quadrant	What the agent does
Known knowns	spot-checks your load-bearing "facts" against the code/docs/platform
Known unknowns	answers the open questions it can, defaults the rest
Unknown knowns	surfaces tacit assumptions you carry without realizing — environment defaults, habits from another ecosystem, constraints you forgot to state
Unknown unknowns	war-games 10+ steps ahead: edge cases, failure modes, second-order effects, hostile inputs, what breaks at step 10 not step 1

Plus three hard rules baked into the doctrine:

• Mandatory "could this be bad?" pass — harms, footguns, irreversibility, said prominently, never buried.
• No bare lists — every finding ships with a solution, mitigation, or an explicit "accepted risk because X". Generic boilerplate ("consider security") is banned.
• The pseudo-oracle — with save, the report persists as UNKNOWNS.md in your project: a consult-first file so future sessions (even cheaper models) find the problems pre-solved instead of rediscovering them. Re-runs merge and retire entries, never duplicate.

Install

git clone https://github.com/fire17/claude-unknowns
cd claude-unknowns && ./install.sh

• ./install.sh --link — symlink into ~/.claude/skills so git pull updates it.
• CLAUDE_SKILLS_DIR=$HOME/.codex/skills ./install.sh — Codex ≥ 0.129 reads the same SKILL.md format.
• New Claude Code sessions pick it up automatically; no restart of anything else.

Safety design

Concern	Behavior
You already have a skill named unknowns	backed up to ~/.claude/skills.backups/unknowns.backup-<stamp> — outside the skills dir (so Claude Code doesn't register the backup as a skill), restore command printed at the moment it happens
Script/CI invocation	zero prompts, POSIX sh, set -eu
Undo	rm -rf ~/.claude/skills/unknowns ~/.claude/skills/uu (printed after every install)
Dependencies	none — one markdown file and one POSIX installer

Usage

/unknowns                    # analyze whatever plan/spec/diff the session is discussing
/unknowns the auth refactor  # analyze that
/unknowns save               # also write/merge the UNKNOWNS.md oracle in the project root
/uu                          # same skill, fewer keystrokes

FAQ

Isn't this just "think harder"? No — it's a forced sweep with a required output shape. The model must visit each quadrant, must answer "could this be bad?", and may not report a risk without its resolution. Unstructured "be careful" prompting reliably skips exactly the quadrants this forces.

What's the oracle file for? Planning happens at your moment of maximum context and model quality; execution often happens later, cheaper, or in a fresh session. UNKNOWNS.md moves the answers across that gap — the war-table's output becomes a file the next agent consults before re-solving anything.

Does output quality depend on the model? Yes, honestly: this is doctrine, not code. A stronger model finds subtler unknowns. The skill's value is that whatever model runs it cannot skip the sweep or hand you warnings without fixes.

Where did this come from? Distilled from repeated real asks ("tell me if there are any edge cases of possibilities i am not seeing… any unknown knowns or unknown unknowns i have now please bring up and address") and a vision doc's war-table mandate — turned into a skill so it never has to be typed again.

Test

python3 tests/test_skill.py   # dependency-free; validates doctrine contract + installer

License

MIT — see LICENSE.