investigation-first

Investigation

"No investigation, no right to speak." — Oppose Book Worship

Investigation is the entry point for implementing "seeking truth from facts": it is not about finding material for a predetermined conclusion, but about letting facts determine judgment.

Use / Do not use

Use:

A decision needs to be made, but the actual situation is not understood well enough
Facing an unfamiliar codebase, system, or domain
Someone else's solution sounds reasonable, but you are unclear about its applicability conditions
You notice you are answering with "should be" or "generally speaking"

Do not use:

Investigation has already been done, and now it is the execution phase
The user has already provided complete context and the basis for the decision
The answer can be directly verified by running it; running is faster than checking

Operating procedure

Write the purpose of the investigation in one sentence: "What I need to figure out is: ...". An investigation without a purpose is wandering.
List an investigation outline(checkbox), covering four aspects:
- Current state: what it is like now (read source code, configuration, and data, not just documentation)
- History: why it became this way (git log, blame, change records)
- Relationships: what constraints are involved (interfaces, dependencies, callers, deployment environment)
- Multiple parties: what different accounts exist (documentation vs code vs runtime results vs user description)
Personally engage with first-hand material: read directly, run directly, look at logs directly. Second-hand summaries can only serve as clues, not as evidence.
Record while investigating, in three columns: mark the source of each finding; separate "what was seen" from "what was inferred."
Output the investigation conclusion(see the template below). The conclusion must precede any action plan; do not give a plan while still investigating.
When facts do not match expectations, change the judgment, not the facts. For what cannot be clarified, honestly write "unknown."

Output template

调查目的：……
调查范围：读了 …… / 跑了 …… / 问了 ……

已核实的事实（附来源）：
- ……（来源：文件:行 / 命令输出 / 日志）
合理推断（说明推理链）：
- ……（因为 …… 所以 ……）
未知 / 存疑：
- ……（需要 …… 才能确认）

调查结论：
- 现状是：……
- 关键约束是：……
- 我原来不知道、现在知道的是：……
- 基于以上，我的判断是：……（置信度：高 / 中 / 低）

Discipline

It is forbidden to draw a conclusion when the "unknown" column is non-empty and relevant to the conclusion: either investigate further, or write the uncertainty into the conclusion.
It is forbidden to do a superficial pass: summarizing after only looking at the directory structure and README does not count as investigation.
Investigation has a budget: first write an outline, and stop once the outline has been investigated; if a new major problem is discovered, start another round rather than expanding indefinitely.

Handoff

The investigation reveals multiple contradictions and no clear focus → contradiction-analysis
The conclusion has been formed and needs verification → practice-cognition
The scope is large and can be investigated separately → dispatch investigator sub-agents to investigate in parallel, with the main thread only aggregating the three columns

Original text basis:original-texts.md