unknowns-first-coding is a Codex skill for risky coding tasks where a wrong assumption would be expensive.
The main idea: before implementing, Codex should separate what is known from what is guessed. It should inspect the repo first, surface important unknowns, ask only questions that materially change the implementation, and proceed on low-risk reversible choices with assumptions clearly logged.
This is not a planning ceremony for every edit. Tiny deterministic changes should stay lightweight: inspect, edit, validate, summarize. The full workflow is for ambiguity with real reversal cost: architecture, public APIs, schemas, migrations, production data, security/privacy/auth/payments/compliance, large refactors, or risky UX semantics.
- Read local guidance, nearby code, tests, docs, and repo conventions before asking questions.
- Classify uncertainty into known knowns, known unknowns, unknown knowns, and unknown unknowns.
- Ask only when the answer changes architecture, data model, public API, security/privacy, migration, UX semantics, rollback risk, or cost.
- Make conservative assumptions for low-risk reversible choices and log the evidence.
- Use blindspot passes, reference mining, prototypes, interviews, and implementation plans as phases, not mandatory ceremony.
- Validate honestly: what ran, what passed, what failed, and what was not run.
- End risky changes with a reviewer explainer and, when useful, a merge-readiness quiz.
Download unknowns-first-coding-skill.zip from this gist. It contains the complete Codex skill folder:
unknowns-first-coding/
SKILL.md
agents/
openai.yaml
references/
blindspot-pass-template.md
implementation-notes-template.md
reviewer-explainer-template.md
workflow-guide.md
Unzip and copy the skill folder to:
$HOME/.agents/skills/unknowns-first-coding/
Example:
unzip unknowns-first-coding-skill.zip
mkdir -p "$HOME/.agents/skills"
cp -R unknowns-first-coding "$HOME/.agents/skills/"Prefer user-wide install unless the repo should intentionally share this skill.
unzip unknowns-first-coding-skill.zip
mkdir -p /path/to/repo/.agents/skills
cp -R unknowns-first-coding /path/to/repo/.agents/skills/If you install repo-local:
- Commit
.agents/skills/unknowns-first-coding/only when the team should inherit this workflow. - Otherwise keep it as local tooling and add the path to a local ignore mechanism.
Use $unknowns-first-coding.
Calibrate the workflow to the task. For tiny deterministic changes, keep it lightweight.
If ambiguity or reversal cost is meaningful, do a blindspot pass before implementing. Classify the important unknowns into known knowns, known unknowns, unknown knowns, and unknown unknowns.
Only ask me questions where my answer would materially change architecture, data model, public API, security/privacy, migration strategy, rollback risk, or user-facing behavior.
For lower-risk choices, inspect the repo, make the conservative assumption, continue, and log the assumption briefly.
After implementation, give me a reviewer explainer. Add a merge-readiness quiz only for complex or risky changes.
## Unknowns-first work
For high-ambiguity, high-reversal-cost coding tasks, or when explicitly requested, prefer the `unknowns-first-coding` skill.
First discover unknowns, then ask only high-impact questions. Keep tiny deterministic changes lightweight. Prototype only when user preference or UX/product semantics would otherwise be locked in too early. Keep implementation notes only when they help review. End with a reviewer explainer, validation summary, and optional merge-readiness quiz for complex or risky changes.