research

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

research

研究

Produce a standalone research dossier — a multi-page deliverable published on the jackin' docs site — for an open question or roadmap topic. Brief-driven: author the brief, then execute it. Gathers and synthesizes evidence (web + codebase); does not make product design decisions.

Reference implementation:

docs/content/docs/research/token-optimization-research/

in the jackin' repo.

生成一份独立的研究档案——发布在jackin' docs站点上的多页交付物——用于解答开放性问题或路线图主题。基于需求驱动：先撰写需求说明，再执行。收集并综合证据（网络 + 代码库）；不做产品设计决策。

参考实现：jackin'仓库中的

docs/content/docs/research/token-optimization-research/

。

When to use

使用场景

Operator runs
```
/jackin-dev:research <slug>
```
for a substantial investigation.

当操作者运行
```
/jackin-dev:research <slug>
```
命令进行深入调研时。

When NOT to use

不适用场景

Design decisions on a roadmap item →
```
/jackin-dev:brainstorm
```
.
Quick lookup →
```
deep-research
```
or Explore directly, no dossier.

对路线图项进行设计决策 → 使用
```
/jackin-dev:brainstorm
```
。
快速查询 → 使用
```
deep-research
```
或直接Explore，无需生成档案。

Arguments

参数

```
--brief-only
```
— author
```
prompt.mdx
```
(the brief) and stop; execute later via
```
/goal Follow <brief>
```
.
```
--in-roadmap
```
— store findings inline in the roadmap item instead of a separate dossier (small research only).
```
--web-only
```
/
```
--codebase-only
```
— restrict gathering to one pass.

```
--brief-only
```
—— 撰写
```
prompt.mdx
```
（需求说明）后停止；后续可通过
```
/goal Follow <brief>
```
执行。
```
--in-roadmap
```
—— 将研究结果存储在路线图项内，而非单独的档案中（仅适用于小型研究）。
```
--web-only
```
/
```
--codebase-only
```
—— 限制仅从单一渠道收集证据。

Output layout (default: separate folder)

输出结构（默认：独立文件夹）

docs/content/docs/research/<slug>/
├── meta.json     # { title, defaultOpen:false, pages:[...] } — sidebar order
├── index.mdx     # dossier landing: headline numbers, how-to-read, tier list
├── prompt.mdx    # the brief that was run (the spec; carries the /goal run line)
├── NN-*.mdx      # numbered chapters (00 summary, 01.. foundations, 10-20 areas, 30+ synthesis)
└── tools/        # optional scripts + own meta.json + index.mdx

Also add

<slug>

to the parent

docs/content/docs/research/meta.json

pages

. Big research → own folder (default); small →

--in-roadmap

docs/content/docs/research/<slug>/
├── meta.json     # { title, defaultOpen:false, pages:[...] } —— 侧边栏顺序配置
├── index.mdx     # 档案首页：核心数据、阅读指南、层级列表
├── prompt.mdx    # 执行的需求说明（规范；包含/goal运行指令）
├── NN-*.mdx      # 编号章节（00 摘要、01.. 基础部分、10-20 研究领域、30+ 综合分析）
└── tools/        # 可选脚本 + 独立meta.json + index.mdx

同时需将

<slug>

添加到父目录

docs/content/docs/research/meta.json

的

pages

中。大型研究→使用独立文件夹（默认）；小型研究→使用

--in-roadmap

参数。

Process

流程

Scope / brief. From the topic (or roadmap item), draft or load
```
prompt.mdx
```
: mission, chapter list, evidence rules. With
```
--brief-only
```
, stop here.
Gather. Web via the built-in
```
deep-research
```
; codebase via Explore/grep. Every external claim carries a source URL; every local number carries its method.
Write.
```
index.mdx
```
(headline numbers + how-to-read + tier list) and the numbered chapters in a fixed per-technique record schema; bundle any reproduction scripts under
```
tools/
```
.
Wire the sidebar. Create/update the dossier
```
meta.json
```
and the parent
```
research/meta.json
```
.
Docs gate + commit. Run the
```
bun
```
docs gate (
```
build
```
,
```
check:repo-links
```
,
```
tsc --noEmit
```
,
```
test
```
) from
```
docs/
```
. Commit
```
docs(research):
```
; push.

范围界定/需求说明。根据主题（或路线图项），起草或加载
```
prompt.mdx
```
：任务目标、章节列表、证据规则。若使用
```
--brief-only
```
参数，在此步骤停止。
收集证据。通过内置的
```
deep-research
```
工具从网络收集；通过Explore/grep从代码库收集。所有外部引用需附带来源URL；所有本地数据需说明获取方法。
撰写内容。编写
```
index.mdx
```
（核心数据 + 阅读指南 + 层级列表）和采用固定技术记录格式的编号章节；将任何复现脚本整理至
```
tools/
```
目录下。
配置侧边栏。创建/更新档案的
```
meta.json
```
以及父目录
```
research/meta.json
```
。
文档检查 + 提交。在
```
docs/
```
目录下运行
```
bun
```
文档检查命令（
```
build
```
、
```
check:repo-links
```
、
```
tsc --noEmit
```
、
```
test
```
）。提交信息格式为
```
docs(research):
```
；推送代码。

Common mistakes

常见错误

Forcing a Problem/Why/Design shape — a dossier is free-form, not a roadmap item.
Making design decisions — that is
```
brainstorm
```
.
An unsourced external claim, or a local number without its method.
```
meta.json
```
```
pages
```
out of sync with the files on disk.

强行采用问题/原因/设计的结构——研究档案为自由格式，并非路线图项。
做出设计决策——这属于
```
brainstorm
```
的范畴。
外部引用无来源，或本地数据未说明获取方法。
```
meta.json
```
中的
```
pages
```
与磁盘上的文件不同步。

Tooling

工具支持

cargo xtask research scaffold <slug>

creates the folder +

meta.json

;

cargo xtask research check

validates

pages

against disk. Execution typically runs via the external

/goal Follow <brief>

cargo xtask research scaffold <slug>

用于创建文件夹和

meta.json

；

cargo xtask research check

用于验证

pages

与磁盘文件是否一致。执行过程通常通过外部命令

/goal Follow <brief>

完成。