Know Your Unknowns

Purpose

Expose hidden assumptions before they become implementation mistakes. Treat artifacts as decision instruments: they should reveal uncertainty, let the human react, and turn that reaction into a better prompt, plan, sign-off, or implementation constraint.

This skill routes to the relevant leaf skill. If the user explicitly names one of the leaf skills, load that skill directly.

Decision Tree

Use the smallest workflow that resolves the unknown:

• Unfamiliar code/module, risky change, "what am I missing": use unknowns-blindspot-pass.
• Unfamiliar domain or weak vocabulary: use unknowns-domain-bootstrap.
• User cannot specify taste or wants options to react to: use unknowns-design-directions.
• UI/interaction is unclear and should be felt before wiring: use unknowns-mock-before-wire.
• Problem is known but intervention space is not: use unknowns-intervention-brainstorm.
• Requirements are ambiguous: use unknowns-spec-interview.
• Existing implementation/reference must be ported or matched: use unknowns-reference-map.
• User wants a plan but mostly needs to inspect judgment calls: use unknowns-tweakable-plan.
• Implementation is underway and surprises/deviations must be preserved: use unknowns-implementation-notes.
• Work is done but buy-in/sign-off is uncertain: use unknowns-buy-in-doc.
• User wants to prove they understand a diff/change before merge: use unknowns-merge-quiz.

If more than one applies, sequence by phase: pre-implementation discovery, during-implementation logging, post-implementation buy-in/comprehension.

Universal Contract

Every unknowns artifact must include:

• The user's original ask, reframed as the unknown being tested.
• Evidence gathered, with clear separation between fact, inference, and assumption.
• The hidden decisions or blindspots that matter.
• A human action: choose, veto, answer, confirm, correct, sign off, or pass a quiz.
• A copyable next prompt, decision summary, or implementation constraint.
• A stop condition: what must be true before implementation/merge/sign-off proceeds.

Do not create decorative artifacts. If HTML is used, it must make review easier through layout, comparison, controls, state, or copy-back loops.

Artifact Mode

When an interactive review artifact is useful, prefer a single self-contained HTML file with no build step. Use it for side-by-side alternatives, selectable chips, toggles, quizzes, timelines, semantic maps, decision tables, or copyable follow-up prompts.

Read references/artifact-output-contracts.md for required sections by artifact type. Read references/html-artifact-guidelines.md before creating HTML.

Optional scaffold:

python3 ~/.codex/skills/know-your-unknowns/scripts/scaffold_unknowns_artifact.py --kind blindspot-pass --title "Auth SSO blindspot pass" --output /tmp/auth-blindspots.html

Source Map

This pack is modeled on Thariq Shihipar's "Know your unknowns" examples. For the page-by-page mapping, read references/corpus-map.md.