structured-research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Structured Research

结构化研究（Structured Research）

Validate an explicit assumption against evidence before it becomes a planning input. Take the "thing the user still treats as an assumption", frame it as a falsifiable question, research it with a chosen methodology, and return a graded, evidence-backed verdict with a non-binding recommendation the maintainer may adopt, adapt, or replace.

Core principle: An assumption is not evidence. Evidence is not a verdict. A verdict is advisory, not a decree.

Violating the letter of this process is violating the spirit of structured research.

在明确假设成为规划输入之前，先用证据对其进行验证。将“用户仍视为假设的事项”转化为可证伪的问题，采用选定的方法进行研究，并返回一个有证据支撑的分级结论，同时附上维护者可以采纳、调整或替换的非约束性建议。

核心原则： 假设不是证据。证据不是结论。结论仅供参考，不是裁决。

违反此流程的字面要求，就是违背结构化研究的精神。

When to Use

何时使用

Trigger when:

A belief is still an assumption — "I think X works this way", "this library probably supports Y", "Z is the fast path"
An assumption is about to enter planning/development unvalidated and the cost of being wrong is real
The user says "validate this", "is it true that…", "research whether…", "verify my assumption"

Do NOT use:

To generate or explore ideas (→
```
pocket-pitching
```
/
```
pocket-grinding
```
— those diverge, this validates)
To fix a known defect (→
```
bug-hunting
```
)
When the claim is already settled and just needs implementing (→
```
hotfix
```
)

出现以下情况时触发：

某个看法仍属于假设——“我认为 X 是这样工作的”、“这个 library 可能支持 Y”、“Z 是最快的路径”
某个假设即将未经验证就进入规划或开发阶段，而判断错误的代价切实存在
用户说“验证这个”、“……是真的吗”、“研究一下……”、“验证我的假设”

不要在以下情况使用：

用于生成或探索想法（→
```
pocket-pitching
```
/
```
pocket-grinding
```
——这些用于发散，本流程用于验证）
用于修复已知缺陷（→
```
bug-hunting
```
）
当结论已经确定，只需要实施时（→
```
hotfix
```
）

Boundary with pitching / grinding

与 pitching / grinding 的边界

structured-research	pocket-pitching / pocket-grinding
Tests whether a stated assumption holds	Generates and explores ideas
Convergent — narrows to a verdict	Divergent — widens the option space
Output: graded verdict + evidence	Output: directions / spec
Single explicit assumption in	Vague problem in

structured-research	pocket-pitching / pocket-grinding
检验既定假设是否成立	生成并探索想法
收敛——聚焦于一个结论	发散——扩大选项空间
输出：分级结论 + 证据	输出：方向 / 规格
输入：单一明确假设	输入：模糊问题

The Three Iron Laws

三条铁律

LAW 1: NO VERDICT WITHOUT EVIDENCE
       A graded conclusion must cite the sources/observations behind it.

LAW 2: SEEK REFUTATION, NOT JUST CONFIRMATION
       At least one selected method must actively try to disprove the assumption.

LAW 3: THE VERDICT IS ADVISORY
       Output a recommendation, never a mandate. The maintainer decides.

LAW 1: NO VERDICT WITHOUT EVIDENCE
       A graded conclusion must cite the sources/observations behind it.

LAW 2: SEEK REFUTATION, NOT JUST CONFIRMATION
       At least one selected method must actively try to disprove the assumption.

LAW 3: THE VERDICT IS ADVISORY
       Output a recommendation, never a mandate. The maintainer decides.

Hard Gates

硬性关卡

GATE 0: PREFLIGHT MUST COMPLETE BEFORE GREETING.
        Scan project context silently. No output until greeting.

GATE 1: NO RESEARCH without a confirmed, operationalized assumption.
        Phase 1 ends with the user confirming the restated, falsifiable question.
        Silence or vague approval is not confirmation.

GATE 2: AT LEAST ONE REFUTATION METHOD selected (Law 2).
        A research run that only seeks confirmation is invalid.

GATE 3: CURATION GATE before grading.
        After evidence is gathered, run the curation pass (advisor) — see Phase 4.
        Do not grade straight from raw evidence.

GATE 4: VERDICT MUST BE GRADED + ADVISORY.
        Confirmed / Refuted / Inconclusive, with cited evidence, framed non-binding.

GATE 0: PREFLIGHT MUST COMPLETE BEFORE GREETING.
        Scan project context silently. No output until greeting.

GATE 1: NO RESEARCH without a confirmed, operationalized assumption.
        Phase 1 ends with the user confirming the restated, falsifiable question.
        Silence or vague approval is not confirmation.

GATE 2: AT LEAST ONE REFUTATION METHOD selected (Law 2).
        A research run that only seeks confirmation is invalid.

GATE 3: CURATION GATE before grading.
        After evidence is gathered, run the curation pass (advisor) — see Phase 4.
        Do not grade straight from raw evidence.

GATE 4: VERDICT MUST BE GRADED + ADVISORY.
        Confirmed / Refuted / Inconclusive, with cited evidence, framed non-binding.

Phase 0: Preflight

Phase 0：预检

Goal: Understand context silently before greeting.

Scan (silent — no output yet):

Stack: detect from root files (package.json, Cargo.toml, requirements.txt, go.mod, pom.xml)
Whether the assumption touches a library/API present in the project (so a code/version check is possible)
Recent commits:
```
git log --oneline -10
```
(the assumption may already be answered in history)

Then greet:

Project: [name] · Stack: [detected]
What assumption would you like to validate?

目标： 在问候之前静默了解上下文。

扫描（静默执行——暂不输出）：

技术栈：从根目录文件检测（package.json、Cargo.toml、requirements.txt、go.mod、pom.xml）
假设是否涉及项目中已有的 library/API（以便检查代码或版本）
最近的提交：
```
git log --oneline -10
```
（历史记录中可能已经回答了该假设）

然后问候：

Project: [name] · Stack: [detected]
What assumption would you like to validate?

Phase 1: Assumption Intake

Phase 1：假设收集与界定

Goal: Turn a fuzzy belief into one confirmed, falsifiable question.

Process:

User states the assumption.
Operationalize it — restate as a precise, testable claim (use the
```
Operationalization
```
method from the catalog). Strip vague terms; name the measurable condition.

Confirm:

Assumption under test: [precise, falsifiable restatement]
What would make it FALSE: [the disconfirming observation]
Is this the right question before I research?

Rules:

Max 2 clarifying questions. This is intake, not interrogation.
If the assumption bundles several claims, ask which ONE to validate this session (one assumption per run).

HARD GATE: User must explicitly confirm the restatement. Do not proceed on silence.

目标： 将模糊看法转化为一个经过确认、可证伪的问题。

流程：

用户陈述假设。
操作化——将其复述为精确、可测试的主张（使用目录中的
```
Operationalization
```
方法）。去除模糊表述；明确可衡量的条件。

确认：

Assumption under test: [precise, falsifiable restatement]
What would make it FALSE: [the disconfirming observation]
Is this the right question before I research?

规则：

最多提出 2 个澄清问题。这是信息收集，不是审问。
如果假设包含多个主张，询问本次要验证哪一个（每次运行仅验证一个假设）。

硬性关卡： 用户必须明确确认复述后的内容。不得在用户沉默的情况下继续。

Phase 2: Method Selection

Phase 2：方法选择

Goal: Recommend 1–3 research methods (non-binding) for this assumption.

→ Read
references/research-methods.csv
— the methodology catalog (

category,technique_name,description

Selection heuristic (lean — no separate selection doc):

Always include ≥1
adversarial
method (Falsification, Counterexample Hunt, Pre-Mortem…) — satisfies Law 2 / Gate 2.
Pick the evidence-gathering method that fits the claim's type:
- Library/API/version behavior →
```
empirical
```
  (Technical Spike, Reproduction Test) +
```
triangulation
```
  (Documentation vs Reality Check).
- Factual/published claim →
```
triangulation
```
  (Source Triangulation, Citation Chaining).
- Open-ended / "what are the possibilities" →
```
elicitation
```
  (Verbalized Sampling to surface a distribution of candidate truths with likelihoods, then narrow).
- Reasoning/causal claim →
```
analytical
```
  (First-Principles Decomposition, Five Whys).
For a calibrated final confidence, optionally add a
```
probabilistic
```
method (Bayesian Updating).
1 method if the claim is simple; 3 max — past 3, synthesis blurs.

State the recommendation (non-binding):

Recommended methods (you may pick, drop, or combine):
1. [Method] ([category]) — because [1-line reason]
2. [Method] ([category]) — because [reason]   ← refutation method (required)

Let the user adjust before gathering evidence.

目标： 针对该假设推荐 1–3 种研究方法（不具约束力）。

→ 读取
references/research-methods.csv
——方法目录（

category,technique_name,description

）。

选择启发式（精简——不另设选择文档）：

始终包含至少 1 个
adversarial
方法（Falsification、Counterexample Hunt、Pre-Mortem 等）——满足 Law 2 / Gate 2。
根据主张的类型选择适合的证据收集方法：
- library/API/版本行为 →
```
empirical
```
  （Technical Spike、Reproduction Test）+
```
triangulation
```
  （Documentation vs Reality Check）
- 事实性/已发表主张 →
```
triangulation
```
  （Source Triangulation、Citation Chaining）
- 开放式问题 / “有哪些可能性” →
```
elicitation
```
  （Verbalized Sampling，用于呈现候选真相及其似然分布，然后逐步收窄）
- 推理/因果主张 →
```
analytical
```
  （First-Principles Decomposition、Five Whys）
如需校准最终置信度，可选加入
```
probabilistic
```
方法（Bayesian Updating）。
简单主张使用 1 种方法；最多 3 种——超过 3 种后，综合判断会变得模糊。

陈述推荐结果（不具约束力）：

Recommended methods (you may pick, drop, or combine):
1. [Method] ([category]) — because [1-line reason]
2. [Method] ([category]) — because [reason]   ← refutation method (required)

在收集证据前，让用户调整推荐方法。

Phase 3: Evidence Gathering

Phase 3：证据收集

Goal: Apply the selected methods and collect cited evidence.

Use the right tool per method: Context7 (library docs / API behavior — preferred for any library claim), Tavily / WebSearch (published facts, recency), code scan / Technical Spike (project-internal or reproducible behavior).
For each method, record: what was checked, what was found, and the source (URL, doc, file:line, or spike output). No source → not evidence (Law 1).
Run the refutation method honestly — go looking for the disconfirming case, not around it.
One unknown blocking the rest? Resolve it with a focused spike before continuing.

Output evidence to the conversation, grouped by method, before the curation gate.

目标： 应用选定的方法并收集带有来源的证据。

根据每种方法选用合适的工具：Context7（library 文档 / API 行为——任何 library 主张均优先使用）、Tavily / WebSearch（公开事实、时效性）、代码扫描 / Technical Spike（项目内部行为或可复现行为）。
对于每种方法，记录：检查了什么、发现了什么，以及来源（URL、文档、file:line 或 spike 输出）。没有来源就不构成证据（Law 1）。
诚实执行反证方法——主动寻找使假设不成立的案例，而不是刻意回避。
如果某个未知项阻碍其余调查？继续之前，先通过聚焦的 spike 解决它。

在进入策展关卡之前，按方法分组将证据输出到对话中。

Phase 4: Curation Gate

Phase 4：策展关卡

Goal: Pressure-test the evidence before grading. (GATE 3)

After ALL evidence is output, run a curation pass with

advisor()

— it reads the full conversation (evidence included) and returns: which evidence is strong vs weak, contradictions, and what is still missing.

Fallback (advisor unavailable — e.g. Claude Code without the Pi extension): do the curation pass inline as the main agent — re-read every piece of evidence adversarially, list the strongest support, the strongest counter-evidence, and any gap — and say explicitly that the inline fallback was used. The gate is never skipped; only its executor changes.

目标： 在评级之前对证据进行压力测试。（GATE 3）

输出全部证据后，运行一次

advisor()

策展环节——它会读取完整对话（包含证据），并返回：哪些证据较强、哪些较弱、存在哪些矛盾，以及仍缺少什么。

回退方案（advisor 不可用时，例如未安装 Pi extension 的 Claude Code）： 由主 Agent 以内联方式执行策展环节——以对抗性思维重新审视每一项证据，列出最有力的支持、最有力的反证以及任何缺口——并明确说明已使用内联回退方式。此关卡绝不跳过；改变的只是执行者。

Phase 5: Graded Verdict + Recommendation

Phase 5：分级结论与建议

Goal: A graded, evidence-backed, advisory conclusion.

→ Load
references/verdict-format.md
for the grading rubric and report template.

Present:

undefined

目标： 给出有证据支撑且仅供参考的分级结论。

→ 加载
references/verdict-format.md
，获取评分规则和报告模板。

呈现：

undefined

Verdict: [Confirmed | Refuted | Inconclusive] (confidence: [low/medium/high])

Assumption tested: [the operationalized question]

Why: [2-4 sentences tying the verdict to the cited evidence]

Key evidence:

[finding] — [source]
[counter-evidence, if any] — [source]

Recommendation (non-binding): [what the maintainer might do — adopt / adapt / investigate further] What would change this verdict: [the evidence that would flip it]


**Save report to:**

docs/pocket/research/YYYY-MM-DD-kebab-slug/research-report.md


**Handoff (explicit, advisory):**

Research report written to: docs/pocket/research/[path]

This verdict is advisory. What next?

Adopt the recommendation as-is
Validate a related assumption (new run)
Carry this into pocket-grinding / pocket-planning as a confirmed input
Save and stop here

---