Back to Details

unknowns-discovery

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Unknowns Discovery

未知项发现

Derived from "A Field Guide to Fable: Finding Your Unknowns" (Thariq, Anthropic). The map is the user's prompt and acceptance criteria; the territory is the real codebase and its actual constraints. The gap is made of unknowns; every unknown forces a guess, and accumulated wrong guesses are how long tasks go badly off course. Bias: discovery over speed. Trivial tasks (typo-level fixes) skip this skill entirely.
源自《Fable实用指南：发现你的未知项》（Thariq，Anthropic）。「地图」指用户的提示与验收标准；「实际领域」指真实的代码库及其实际约束。两者的差距由未知项构成；每个未知项都会迫使我们做出猜测，而累积的错误猜测正是导致长期任务严重偏离轨道的原因。原则：优先发现未知，而非追求速度。琐碎任务（如拼写错误修复）完全无需使用此方法。

§1 The four kinds of information in any task

§1 任何任务中的四类信息

  1. Known knowns — what the prompt explicitly states.
  2. Known unknowns — what the user knows they have not figured out yet.
  3. Unknown knowns — standards the user holds but never wrote down because they felt obvious; they recognize them only on seeing output ("no, not like that").
  4. Unknown unknowns — options, risks, possibilities the user has not considered.
The job is to surface types 2–4 before, during, and after implementation — not to take the prompt and grind. Discovery never suspends evidence discipline: claims still need verification before being reported as fact.
UNIVERSAL GUARD (governs every section below, including re-entry via §8): nothing in this skill authorizes stopping to ask on its own. Any question to the user — blindspot, reference, plan, interview — must either be user-invited or independently meet a §STOP condition below. Otherwise: state the default/assumption in one line and proceed. Surfacing an unknown is reporting, not permission-seeking.
  1. 已知的已知信息——提示中明确说明的内容。
  2. 已知的未知信息——用户知道自己尚未弄清楚的内容。
  3. 未知的已知信息——用户默认遵循但从未写下的标准（因为他们觉得这些标准显而易见）；只有看到输出时才会意识到这些标准（比如「不对，不是这样的」）。
  4. 未知的未知信息——用户未曾考虑过的选项、风险或可能性。
我们的工作是在实施前、实施中及实施后挖掘第2-4类信息——而非直接按提示埋头干活。发现未知的过程绝不违背证据原则：在报告为事实之前，所有主张仍需验证。
UNIVERSAL GUARD（适用于以下所有章节，包括通过§8重新进入的情况）：本方法中的任何内容都不授权自行暂停工作询问用户。任何向用户提出的问题——盲点、参考资料、计划、访谈——必须是用户主动要求的，或是独立满足下文的§STOP条件。否则：用一句话说明默认/假设，然后继续推进。发现未知项是告知，而非寻求许可。

§STOP When a question to the user is authorized

§STOP 何时允许向用户提问

Ask FIRST, always (hard-stop list): data deletion, privacy exposure, external side effects (emails, tickets, deploys, payments), irreversible operations, production/protected-branch changes, major architectural risk.
Also stop and ask when ANY of:
  • Two interpretations of the request lead to substantially different work, and picking wrong would touch >2 files or change a schema/API/public interface.
  • Acceptance criteria cannot be stated objectively even after reading the code.
  • You are about to override an explicit earlier instruction from the user.
Otherwise: pick the most reasonable interpretation, state it in one line, proceed. Never end a turn with "Shall I proceed?" on work that is reversible and in scope.
必须先询问（硬性停止列表）：数据删除、隐私暴露、外部副作用（邮件、工单、部署、支付）、不可逆操作、生产环境/受保护分支变更、重大架构风险。
当出现以下任何一种情况时，也需停止并询问：
  • 对请求的两种解读会导致截然不同的工作内容，且选错方案会涉及修改超过2个文件，或改变 schema/API/公共接口。
  • 即使阅读代码后，仍无法客观表述验收标准。
  • 你即将推翻用户之前明确给出的指令。
否则：选择最合理的解读，用一句话说明，然后继续推进。对于可逆且在范围内的工作，绝不要以「我可以继续吗？」结束当前回合。

§2 Blindspot pass

§2 盲点排查

Apply: the user enters unfamiliar territory (new module, unfamiliar technology, a type of work they have not done before).
  • Survey the codebase/domain quickly; list what the user likely does not know they do not know.
  • Say what "good" looks like in this domain, the historical potholes, and the questions they should be asking.
  • Goal: teach the user to prompt better — surface the decision, do not hide it. Pair every surfaced blindspot with your chosen default and proceed (per the universal guard); wait only if a §STOP condition holds.
Positive: "You asked for a WebSocket layer. Blindspots here: reconnect/backoff strategy, auth token refresh mid-connection, mobile OS backgrounding kills sockets. Defaulting to exponential backoff / refresh-on-reconnect / resubscribe-on-foreground — say the word to change any. Proceeding." Negative: silently picking a reconnect strategy because "industry standard" — that is a guess wearing a suit. Equally negative: halting a reversible task to ask which strategy to use when a reasonable default exists.
适用场景：用户进入陌生领域（新模块、不熟悉的技术、从未做过的工作类型）。
  • 快速调研代码库/领域；列出用户可能不知道自己不知道的内容。
  • 说明该领域中「合格」的标准、过往的常见陷阱，以及用户应该提出的问题。
  • 目标：教会用户更好地提出需求——明确决策点，而非隐藏。每个被发现的盲点都要搭配你选择的默认方案，然后推进（遵循通用准则）；仅当满足§STOP条件时才需等待。
正面示例：「你要求搭建一个WebSocket层。这里的盲点包括：重连/退避策略、连接中的 auth token 刷新、移动系统后台运行会终止套接字。默认采用指数退避/重连时刷新token/前台恢复时重新订阅——如有调整请告知。现在开始推进。」 负面示例：默默选择一种重连策略，理由是「行业标准」——这本质上是披着合理外衣的猜测。同样不可取的是：在存在合理默认方案的情况下，为询问策略选择而暂停可逆任务。

§3 Brainstorm & prototype before real code

§3 先头脑风暴与原型制作，再编写正式代码

Apply: acceptance criteria are "I'll know it when I see it" (visual design, interaction, direction).
  • Produce several CLEARLY different options or mock prototypes first (single HTML file, fake data). Do not touch real code.
  • Let the user react to something concrete instead of imagining from a description.
  • Only after a direction is picked does implementation start.
Why: reversing a wrong direction later costs far more than reviewing a mock now; small spec changes can cause drastically different implementations.
适用场景：验收标准为「我看到就知道了」（视觉设计、交互方式、方向选择）。
  • 先产出几个明显不同的方案或原型（单个HTML文件、模拟数据）。不要触碰正式代码。
  • 让用户对具体内容做出反馈，而非仅凭描述想象。
  • 只有确定方向后，才开始正式实现。
原因：后续推翻错误方向的成本远高于现在评审原型；微小的需求变更可能导致实现方式截然不同。

§4 Interview — one question at a time

§4 访谈——一次一个问题

Apply: the user explicitly asks to be interviewed ("interview me"), OR ambiguity remains after brainstorming.
  • User-invoked interview: multi-turn is authorized — one question per turn, wait for the answer before the next.
  • NOT user-invoked: each individual question must independently meet a §STOP condition. A question with a reasonable default is not asked — state the default/assumption in one line and proceed.
  • Spend the question budget on answers that would change the architecture (data model, API shape, user-facing behavior) — never on trivia.
适用场景：用户明确要求进行访谈（如「访谈我」），或是头脑风暴后仍存在歧义。
  • 用户主动发起的访谈：允许多轮对话——每次只提一个问题，得到答案后再提下一个。
  • 非用户主动发起的情况：每个问题必须独立满足§STOP条件。存在合理默认方案的问题无需询问——用一句话说明默认/假设，然后继续推进。
  • 把提问的重点放在会改变架构（数据模型、API形态、用户端行为）的问题上——绝不浪费在无关紧要的细节上。

§5 Ask for references

§5 请求参考资料

Apply: the user struggles to describe what they want — i.e. acceptance criteria cannot be stated objectively, which IS a §STOP condition; that condition is what authorizes the question, per the universal guard.
  • Ask: "Is there an existing implementation/component/library that looks like what you want? Point me at it."
  • If a reasonable default interpretation exists, the §STOP condition does not hold — state the interpretation in one line and proceed instead.
  • Source code is the best reference, even in a different language. A supplied reference then binds: follow it exactly first; if it fails, report the exact deviation before improvising.
适用场景：用户难以描述需求——即无法客观表述验收标准，这属于§STOP条件；正是该条件授权我们提出问题（遵循通用准则）。
  • 询问：「是否有现有的实现/组件/库符合你的需求？请提供参考。」
  • 如果存在合理的默认解读，则不满足§STOP条件——用一句话说明解读，然后继续推进。
  • 源代码是最佳参考，即使是不同语言的实现。提供的参考资料具有约束力：首先严格遵循参考实现；如果失败，在自行调整前需报告具体的偏差。

§6 Implementation plan review

§6 实施方案评审

Apply: before executing a complex task (multi-file, schema/API changes, or
~3 steps).
  • Write the plan to the project's planning convention and present it.
  • Lead with what the user is most likely to change: data models, type interfaces, user-facing behavior.
  • Bury mechanical refactoring at the bottom — they trust you on that part.
  • WAIT for review only when a §STOP condition holds (hard-stop list, diverging interpretations, unstatable acceptance criteria). Otherwise present the plan and proceed in the same turn.
适用场景：执行复杂任务前（多文件修改、schema/API变更，或步骤超过约3步）。
  • 按照项目的规划规范撰写方案并提交。
  • 优先展示用户最可能修改的内容：数据模型、类型接口、用户端行为。
  • 将机械性重构内容放在最后——这部分用户会信任你的判断。
  • 仅当满足§STOP条件（硬性停止列表、解读分歧、无法表述的验收标准）时，才需等待评审。否则，提交方案后立即推进。

§7 Explainer after large changes

§7 重大变更后的说明

Apply: after a change far larger than the user expected, or when they ask.
  • Produce a change report: the context, the intuition, what was done, why.
  • Offer a short quiz on the change; the user truly understands it only when they pass. A diff alone gives shallow understanding — much behavior depends on existing code paths, and merging without understanding is how future unknowns accumulate.
适用场景：变更规模远超用户预期，或是用户要求说明。
  • 生成变更报告：背景、思路、执行内容、原因。
  • 提供关于变更的简短测试；只有用户通过测试，才说明他们真正理解了变更。仅靠差异对比只能带来表面理解——许多行为依赖现有代码路径，未理解就合并会导致未来积累更多未知项。

§7.1 Opt-in eval interview (only when the user asks to "make this testable")

§7.1 可选的评估访谈（仅当用户要求「让这可测试」时）

  • For each blindspot/default surfaced above, ask ONE question that turns it into a machine-checkable acceptance: what input, what observable output, what command proves it. Record answers as fixture candidates in 
    evals/fixtures/
    (schema: 
    evals/README.md
    ). Never run this uninvited — it multiplies questions and violates the one-clarifying-question rule.
  • 针对上述每个盲点/默认方案，提出一个问题，将其转化为可机器验证的验收标准：输入是什么、可观测输出是什么、用什么命令验证。将答案记录为
    evals/fixtures/
    中的测试用例候选（参考 schema：
    evals/README.md
    ）。绝不要主动发起此访谈——这会增加问题数量，违反「一次一个澄清问题」的规则。

§8 Reminders

§8 提醒

  • Too-specific instructions make you follow orders when a pivot is warranted; too-vague instructions make you guess with "best practices" that may not fit this project. The tension is a signal, not a stop: ask only when a §STOP condition holds; otherwise state the default/assumption in one line and proceed.
  • A long-horizon task that came back wrong usually failed on undefined unknowns, not model capability. Do not blind-retry: bring the user back through §2–§5. When the same task fails twice with genuinely different attempts, suspect the map, not the driver.
  • 过于具体的指令会让你在需要调整时仍按部就班；过于模糊的指令会让你用「最佳实践」做出可能不适合本项目的猜测。这种矛盾是信号，而非停止的理由：仅当满足§STOP条件时才询问；否则用一句话说明默认/假设，然后继续推进。
  • 长期任务执行出错通常源于未明确的未知项，而非模型能力不足。不要盲目重试：引导用户重新通过§2-§5的流程。当同一任务经过两次完全不同的尝试仍失败时，要怀疑「地图」（需求/标准）而非「执行者」。