| name | know-your-unknowns |
| description | Surface unknowns — the gap between the plan in your head and the territory of real code — as interactive, self-contained HTML artifacts the user reacts to instead of describing from scratch. Use when a feature request is ambiguous, the work touches unfamiliar code, the user lacks the domain vocabulary to ask precisely, a visual direction or UI behavior is still open, a known problem has no chosen intervention, external reference code is about to be ported, an implementation plan needs a review pass, mid-implementation reality deviates from the plan, finished work needs stakeholder buy-in, or a large change is about to merge. |
| license | MIT |
Know Your Unknowns
The map is not the territory. The map is the prompt, the plan, the mental model; the territory is the real code and the real requirement. The gap between them is your unknowns — cheapest to find before implementation, priciest after merge.
This skill closes the gap with one move: build a self-contained HTML artifact that makes the unknowns concrete — blindspot cards, clickable mocks, side-by-side directions, quizzes — so the user reacts (click, check, pick) instead of having to describe. Reacting to something concrete surfaces unknowns that abstract discussion never reaches.
Techniques adapted from Thariq (@trq212), "Know Your Unknowns": https://thariqs.github.io/html-effectiveness/unknowns/
Pick one technique
Diagnose the user's moment, pick ONE row, then read its reference file before generating anything. One artifact per run; if two rows genuinely fit, name both and ask.
Artifact rules (every technique)
- Self-contained — one
.html file, inline CSS/JS, zero external requests (no CDN, no frameworks, no web fonts). Must work opened directly from file://, offline.
- Grounded — every card, finding, question, and table row names a real file, symbol, commit, or measurement from THIS codebase; do the legwork (read code, grep,
git log) before writing the artifact. A claim you cannot ground gets deleted, not hedged. Invented data is allowed only inside mocks and demos, and must be obviously fake.
- Reply assembly — the defining interaction: chips / checkboxes / option buttons accumulate into a visible reply box with a 「複製回覆」 button (
navigator.clipboard.writeText), so the user's clicks become their next prompt verbatim. Any artifact that asks the user something must assemble the reply for them.
- Copyable prompts — every suggested prompt or template in the artifact carries its own 「複製」 button.
- Language — artifact prose in Taiwan Traditional Chinese with Taiwan terms (程式碼 not 代碼、資料 not 數據、元件 not 組件); identifiers, paths, and code stay verbatim. If the conversation isn't in Chinese, follow the conversation's language.
- Filename —
unknowns-<NN>-<slug>.html in the project root. It is a throwaway working page; tell the user they can delete it after replying.
Workflow
- Diagnose the moment → pick the technique from the table. Done when: exactly one row chosen, or a clarifying question naming the two candidate rows is sent.
- Read the technique's reference file. Done when: read in this run, not recalled from memory.
- Legwork — gather the real material the reference file demands (scan the code area, read the reference repo, walk
git log, restate the plan). Done when: every section the artifact will render has real content to hold.
- Build & deliver — write the artifact, report its absolute
file:// path plus one line on how to use it. Done when: the file exists and the path is in the reply.
- Act on the reply — the assembled reply the user pastes back is the refined prompt; continue the work from it directly.
