Know Your Unknowns

Find the thing you were about to learn the hard way.

know-your-unknowns is a portable agent skill for surfacing hidden assumptions, edge cases, reviewer objections, product ambiguity, implementation traps, and cheap validation probes before you commit to a plan. It works as a SKILL.md skill for agents that support Claude/OpenClaw/Codex/opencode-style skill folders, and includes adapters for AGENTS.md and opencode subagents.

What am I missing?

Where could this go wrong?

帮我找出这个需求里我还不知道的东西。

No method jargon required. The agent chooses the right discovery depth and output shape internally.

Why This Exists

Most project failures do not come from the things already on the checklist. They come from the assumptions nobody noticed, the legacy convention nobody mentioned, the OAuth redirect nobody tested, the reviewer objection that should have been answered yesterday, or the edge case hiding behind "just add a field".

This skill helps an agent pause at the right moments and ask: what does the current map fail to include?

Methodology Source

This skill is inspired by Thariq Shihipar's Know your unknowns examples in the HTML effectiveness project:

• Know your unknowns - examples
• HTML effectiveness examples

Thariq's examples show how self-contained HTML artifacts can make unclear work inspectable before, during, and after implementation. This repository adapts that unknown-discovery workflow into a reusable agent skill.

The skill also borrows the practical shape of the examples:

• Before implementation: find blindspots, learn missing vocabulary, compare design directions, mock before wiring, interview for high-impact decisions, study references, and build tweakable plans.
• During implementation: keep notes on where reality diverges from the plan.
• After implementation: prepare reviewer buy-in and quiz the implementer before merge.

How It Works

The skill turns a vague request into a risk-discovery artifact:

1. It names the territory: goal, users, constraints, and current plan.
2. It separates known knowns, known unknowns, hidden context, and plausible unknown unknowns.
3. It chooses a depth:
   • Shallow for quick planning and ordinary reviews.
   • Deep when stakes are high, the request is broad, or the first pass finds conflicting assumptions.
4. It uses Evidence before confidence:
   • observed: supported by inspected artifacts, commands, tests, docs, logs, screenshots, or user answers.
   • inferred: likely from context but not directly proven.
   • assumption: a working guess.
   • unverified: must be checked before relying on it.
5. It ends with cheap probes: the smallest checks that can collapse uncertainty.

What It Produces

Depending on the task, the skill can produce:

• Risk cards with evidence basis.
• Decision tables for high-variance choices.
• Question queues sorted by blast radius.
• Tweakable implementation plans.
• Prototype or mock-before-build checklists.
• Implementation deviation logs.
• Reviewer buy-in docs.
• Merge-readiness quizzes.

Compatibility

This repository is intentionally not Codex-only.

Surface	Status	How to use
Claude Code / Claude Skills	Native	Install the repo as a skill folder. It contains SKILL.md with name and description frontmatter.
OpenClaw	Native-style	Install the repo as a skill folder if your OpenClaw setup supports SKILL.md skills.
Codex	Native	Install into your Codex skills directory. agents/openai.yaml provides UI metadata.
opencode	Native + adapter	Install as an opencode SKILL.md skill, or copy the optional adapters/opencode/agent/know-your-unknowns.md subagent.
AGENTS.md-compatible tools	Adapter	Use the root AGENTS.md as project-level agent guidance.

Anthropic's Agent Skills format is a folder with a SKILL.md file whose YAML frontmatter includes name and description; this repo keeps that root format so the same folder can be reused by multiple skill-aware agents. opencode also discovers reusable SKILL.md definitions from .opencode/skills/<name>/SKILL.md, ~/.config/opencode/skills/<name>/SKILL.md, .claude/skills/<name>/SKILL.md, and .agents/skills/<name>/SKILL.md. For project-wide rules, opencode reads AGENTS.md; for manually invokable agents, opencode supports markdown agents that can be called with @agent-name.

Install

Claude Code / Claude Skills / OpenClaw-style skill folders

Clone this repository into your agent's skills directory. For Claude Code personal skills:

git clone https://github.com/NimaChu/know-your-unknowns ~/.claude/skills/know-your-unknowns

For a project-scoped Claude/OpenClaw-style install, place it under your project's skill folder if supported:

git clone https://github.com/NimaChu/know-your-unknowns .claude/skills/know-your-unknowns

Codex

git clone https://github.com/NimaChu/know-your-unknowns "$env:USERPROFILE\.codex\skills\know-your-unknowns"

opencode native skill

Global install:

git clone https://github.com/NimaChu/know-your-unknowns ~/.config/opencode/skills/know-your-unknowns

Project install:

git clone https://github.com/NimaChu/know-your-unknowns .opencode/skills/know-your-unknowns

Claude-compatible opencode install:

git clone https://github.com/NimaChu/know-your-unknowns ~/.claude/skills/know-your-unknowns

opencode adapters

Use either project-level instructions:

cp AGENTS.md /path/to/your/project/AGENTS.md

Or install the opencode subagent adapter:

mkdir -p /path/to/your/project/.opencode/agent
cp adapters/opencode/agent/know-your-unknowns.md /path/to/your/project/.opencode/agent/know-your-unknowns.md

Try It

Use $know-your-unknowns.

I am about to add team invitations to an existing SaaS app. Admins enter an email, the system sends an invite link, and the invited person joins the right workspace after sign-up or login. The app already has normal login, Google OAuth, workspace switching, and RBAC.

Before implementation, help me find what I am missing. Where could this go wrong? What should I verify first?

Expected style of output:

• Concrete risks, not generic warnings.
• Evidence labels for important claims.
• A short list of highest-leverage unknowns.
• Cheap checks before implementation.
• A plan that separates high-variance decisions from mechanical work.

For opencode, invoke the subagent if installed:

@know-your-unknowns

I am about to add team invitations to an existing SaaS app...
Before implementation, help me find what I am missing.

Repository Contents

• SKILL.md: Portable skill instructions and trigger description for SKILL.md-compatible agents.
• AGENTS.md: Project-level instructions for AGENTS.md-compatible coding agents.
• agents/openai.yaml: Codex UI metadata.
• adapters/opencode/agent/know-your-unknowns.md: opencode subagent adapter.
• references/prompt-patterns.md: Optional reusable prompt patterns and artifact templates.

License And Attribution

This repository is an adaptation of a public methodology, not a copy of Thariq's HTML artifacts. Please credit the original inspiration when reusing the workflow:

Inspired by Thariq Shihipar's Know your unknowns examples in the HTML effectiveness project.