refactor-research-code

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Refactor Research Code

重构研究代码

Take a research repo from "works on my machine" to a clean, documented, re-runnable public release — without changing a single number the paper reports. Research code accretes dead experiment branches, hardcoded paths, magic hyperparameters, an undocumented "run this file, then that one" ritual, and identifying breadcrumbs. This skill removes that cruft and gives the repo a sensible layout, but it treats result preservation as the prime directive: it classifies every proposed change as safe (mechanical, behavior-preserving) or ask-first (could move the numbers), and it never touches an ask-first item without the author's explicit say-so.

It is not generic refactoring (no perf rewrites, no "modernize the API," no restructuring for its own sake). The only goal is release readiness with identical behavior. When a "cleanup" would change what the code computes, the right move is to flag it and ask — not to make the repo prettier at the cost of the paper's claims.

将研究代码仓库从“仅在我的机器上运行”转变为整洁、文档完备、可重复运行的公开发布版本——且不会改变论文中报告的任何数值。研究代码通常会积累废弃实验分支、硬编码路径、魔法超参数、无文档说明的“先运行这个文件，再运行那个文件”操作流程，以及可识别身份的痕迹。本技能会清除这些冗余内容，为仓库提供合理的结构布局，但始终将结果保留作为首要准则：它会将每个拟议的变更归类为SAFE（安全）（机械性、不改变行为）或ASK-FIRST（需先确认）（可能改变数值），且在未获得作者明确许可的情况下，绝不会触碰任何需先确认的内容。

这不是通用重构（不涉及性能重写、“API现代化”或为重构而重构）。唯一目标是保持行为一致的发布就绪状态。当某项“清理操作”会改变代码的计算结果时，正确的做法是标记该操作并征求意见——而非以牺牲论文结论为代价来美化仓库。

When to use

适用场景

"Clean up / refactor my research code for release." / "It's a mess — get it publishable."
"Remove the dead experiment branches and commented-out code."
"Separate config from code." / "These hyperparameters are hardcoded everywhere."
"Make my runs deterministic / re-runnable." / "Document the entrypoint."
"Give the repo a clear layout." / "Strip my identity for double-blind."
Before
```
test-research-code
```
(which adds tests/seeds/env) and
```
prepare-artifacts
```
(which packages and hosts for a badge) — this is the structural cleanup that comes first.

“清理/重构我的研究代码以用于发布。” / “代码一团糟——让它达到可发布状态。”
“移除废弃实验分支和注释掉的代码。”
“将配置与代码分离。” / “这些超参数到处都是硬编码。”
“让我的运行可复现/可重复执行。” / “为入口点添加文档。”
“为仓库提供清晰的结构布局。” / “移除我的身份信息以用于双盲评审。”
在
```
test-research-code
```
（添加测试/随机种子/环境配置）和
```
prepare-artifacts
```
（打包并托管以生成徽章）之前使用——这是首先要完成的结构性清理步骤。

What this is NOT (route elsewhere)

不适用场景（请转向其他工具）

You want…	Use instead
Add smoke tests, pin seeds, capture the environment	`test-research-code`
Package + archival DOI/SWHID + badge taxonomy + appendix	`prepare-artifacts`
Deep double-blind sweep of the paper + reversible de-anon	`anonymize-paper`
Confirm the produced numbers match the paper's tables	`verify-results`
Reorganize the paper's sections/argument	`refactor-structure`

This skill flags seeding/env gaps and identity leaks and hands them off; it does the structural cleanup itself.

你需要…	请使用…
添加冒烟测试、固定随机种子、捕获环境信息	`test-research-code`
打包 + 归档DOI/SWHID + 徽章分类 + 附录	`prepare-artifacts`
对论文进行深度双盲扫描 + 可逆匿名化	`anonymize-paper`
确认生成的数值与论文表格匹配	`verify-results`
重新组织论文的章节/论证结构	`refactor-structure`

本技能会标记随机种子/环境配置漏洞和身份泄露问题，并将其移交给对应工具；它自身仅负责结构性清理。

Inputs

输入项

The research-code directory (the repo, or a subfolder holding the experiment scripts). This skill reads local files only; it does not clone.
Whether review is double-blind / single-blind / not blind (drives the identity scan), and any identifying terms to scan for (author names, institution, internal codenames).
Optionally
```
.paper-memory/profile.yml
```
(contribution type — a
```
system
```
or
```
dataset
```
paper is judged harder on code quality, leaning toward a Reusable release).
Optionally the target venue's artifact track, if the cleanup is in service of one — but badge rules are fetched live by
```
prepare-artifacts
```
, not here.

研究代码目录（代码仓库，或存放实验脚本的子文件夹）。本技能仅读取本地文件；不进行克隆操作。
评审类型为双盲/单盲/非盲（决定身份扫描的规则），以及需要扫描的身份识别术语（作者姓名、机构名称、内部代号）。
可选：
```
.paper-memory/profile.yml
```
（贡献类型——
```
system
```
或
```
dataset
```
类论文对代码质量要求更高，倾向于生成可复用的发布版本）。
可选：目标会议的** artifact track**（若清理是为了参与该赛道）——但徽章规则由
```
prepare-artifacts
```
实时获取，本技能不处理此内容。

Prime directive: preserve exact numerical behavior

首要准则：保留精确的数值行为

Every action this skill takes falls in one of three buckets. Treat the boundary between them as sacred.

SAFE — apply freely (with the author's nod): add a README / LICENSE /
```
.gitignore
```
; move files into a
```
src/
```
/package layout (then fix imports); delete pure junk (
```
__pycache__
```
,
```
*.pyc
```
,
```
.DS_Store
```
, editor swap files); document the existing entrypoint; reformat whitespace/comments only. These cannot change what the code computes.
ASK-FIRST — never touch without explicit confirmation: delete a code path (a backup file, a commented-out block, an
```
if False:
```
branch — it may be a toggled experiment or silently shadow the live version); extract a hardcoded hyperparameter or path into config (the value must be preserved exactly); change anything touching seeding, RNG, thread/worker count, dtype/precision, or evaluation order (these define the numbers). For each, present the finding, the proposed change, and why it might change results, then wait.
IDENTITY — scrub before any blind upload: emails, home paths, author names,
```
.git
```
history. Surface them here; hand the deep sweep to
```
anonymize-paper
```
.

If you cannot tell whether a change is safe, it is ask-first by default. A prettier repo that reports different numbers is a failure, not a success.

本技能执行的每一项操作都属于以下三类之一。请严格遵守三类操作之间的界限。

SAFE（安全）——经作者点头后可自由执行：添加README/LICENSE/.gitignore；将文件移入
```
src/
```
/包结构（然后修复导入路径）；删除纯冗余内容（
```
__pycache__
```
、
```
*.pyc
```
、
```
.DS_Store
```
、编辑器交换文件）；为现有入口点添加文档；仅格式化空格/注释。这些操作不会改变代码的计算结果。
ASK-FIRST（需先确认）——未经明确确认绝不动手：删除代码路径（备份文件、注释块、
```
if False:
```
分支——它可能是一个可切换的实验或静默覆盖当前版本）；将硬编码的超参数或路径提取到配置中（必须精确保留原始值）；更改任何涉及随机种子、随机数生成器、线程/工作进程数量、数据类型/精度或评估顺序的内容（这些因素定义了最终数值）。对于每一项此类操作，需说明发现的问题、拟议的变更以及为何可能改变结果，然后等待作者确认。
IDENTITY（身份信息）——盲审上传前需彻底清除：邮箱、本地路径、作者姓名、
```
.git
```
历史。在此处标记这些信息；将深度扫描任务移交
```
anonymize-paper
```
处理。

若无法判断某项变更是否安全，则默认归为ASK-FIRST（需先确认）。一个更美观但报告数值不同的仓库是失败的，而非成功。

Process

操作流程

This follows plan → confirm → apply-safe → ask-on-risk, with the plan grounded in an external, measurable signal — the static audit, not the model's sense that the repo "looks clean." Name assumptions, show competing readings, and keep the author in control.

Read memory first. Read
```
.paper-memory/lessons.md
```
(and
```
profile.yml
```
if present) so you skip what the author already fixed and lead with their
```
recurring
```
habits (e.g. "you tend to ship
```
.git
```
and hardcoded
```
/home
```
paths"). See
```
paper-memory-convention.md
```
.
Confirm scope and blind level. Ask whether review is double-blind and what the release is for (a public GitHub release, a blind-review supplement, an artifact track). Don't anonymize a single-blind/non-blind release — it mangles a fine repo. Get the identifying terms to scan for if blind.
Run the static release-refactor audit (deterministic). Do not hand-grep:
```
python3 scripts/release_audit.py <code-dir> \
    --blind <none|single|double> --names "Jane Doe,Example University"
# machine-readable:
python3 scripts/release_audit.py <code-dir> --blind double --json
```
It walks the repo (read-only, no execution, no network, no writes) and emits findings tagged by category (dead-code, config, entrypoint, layout, determinism, identity, hygiene) and, critically, by risk:
```
SAFE
```
,
```
ASK-FIRST
```
(behavior-risk), or
```
IDENTITY
```
. Flags:
```
--strict
```
(any finding fails),
```
--max-files N
```
,
```
--max-bytes N
```
(in-tree blob threshold). Exit codes: 0 no ask-first/identity findings, 1 ask-first or identity findings present, 2 usage error. This is the signal the plan is built on (an external check, not self-judgment); the audit maps opportunities — it does not prove the repo reproduces.
Present a refactor plan the author approves BEFORE any edit. Group the findings into the three buckets, ordered SAFE → ASK-FIRST → IDENTITY. For each ask-first item, state the change and the result-risk ("deleting this
```
if False:
```
block is safe only if it is unreachable in every config — confirm?"). The author approves or vetoes per item. Categories and the safe refactor recipes are in references/release-refactor-catalog.md.
Apply SAFE refactors (with the author's go-ahead), in this order — each maps to an audit category:
- Layout — add README (entrypoint, the exact reproduce command per result, deps, the directory map), LICENSE,
```
.gitignore
```
  ; move a flat dump of scripts into a
```
src/
```
  /package layout and fix the imports.
- Entrypoint — document (or wire) one obvious command that runs the pipeline end to end (
```
make reproduce
```
  /
```
run.sh
```
  /
```
python -m pkg
```
  ).
- Hygiene — remove
```
__pycache__
```
  ,
```
*.pyc
```
  ,
```
.DS_Store
```
  , editor swaps from the release copy; move large in-tree data/model blobs to a download script / archival host (this last one is ask-first — confirm the blob isn't needed at runtime).
Walk ASK-FIRST items one at a time, never in bulk. For each approved change: make the minimal edit, then verify behavior is preserved by an external check — re-run the pipeline (or the smoke test) and diff the output, not by eyeballing the diff. Behavior preservation is confirmed by re-running, which is
```
test-research-code
```
/
```
verify-results
```
territory; this skill flags and coordinates, and stops to ask when a change is genuinely risky. Escalation is a feature. In particular:
- dead-code — only after confirming nothing imports/reaches it.
- config — extract the literal into config/CLI with the identical value; a typo here silently changes results.
- determinism — set/record seeds and pin order in coordination with the author, then re-run to re-confirm the paper's numbers. Adding a seed changes an unseeded run — this is the highest-risk edit. Hand the seed/env mechanics to
```
test-research-code
```
  .
Handle IDENTITY leaks for blind review. Surface emails, home paths, names, and
```
.git
```
history; hand the deep sweep (commit history, notebook metadata, self-citation phrasing, anonymized mirror) to
```
anonymize-paper
```
. Never expose the author through the repo on a blind upload.
Re-run the audit until SAFE-clean, with an explicit stop condition. Loop audit → fix → audit until no SAFE/layout/hygiene findings remain and every ask-first item is resolved or consciously deferred — not open-endedly. Hard cap ~3 passes; if the audit still flags the same ask-first item, that is a judgment call to escalate, not to keep editing.
Write the refactor plan + change log to
```
paper-workspace/submission/refactor-research-code-plan.md
```
and append a line to
```
paper-workspace/INDEX.md
```
. Lead with what was done (safe), then the ask-first decisions (applied / vetoed / deferred, each with the result-risk noted), then the identity handoff. Cite each item's audit finding.

遵循规划→确认→执行安全操作→针对风险项征求意见的流程，且规划基于外部可衡量的信号——静态审计，而非模型对仓库“看起来整洁”的主观判断。明确说明假设，展示不同解读，并始终让作者掌控流程。

先读取记忆信息。读取
```
.paper-memory/lessons.md
```
（若存在则同时读取
```
profile.yml
```
），跳过作者已修复的问题，并优先处理他们的
```
recurring
```
（经常性）习惯（例如：“你通常会提交
```
.git
```
和硬编码的
```
/home
```
路径”）。详见
```
paper-memory-convention.md
```
。
确认范围和盲审级别。询问评审是否为双盲，以及发布目的（公开GitHub版本、盲审补充材料、artifact track）。不要对单盲/非盲版本进行匿名化——这会破坏原本良好的仓库结构。若为盲审，获取需要扫描的身份识别术语。
运行静态发布重构审计（确定性）。请勿手动 grep：
```
python3 scripts/release_audit.py <code-dir> \
    --blind <none|single|double> --names "Jane Doe,Example University"
# 机器可读格式：
python3 scripts/release_audit.py <code-dir> --blind double --json
```
该脚本会遍历仓库（只读，不执行，不联网，不写入），并输出带有类别（废弃代码、配置、入口点、布局、确定性、身份信息、卫生性）和关键风险等级：
```
SAFE
```
、
```
ASK-FIRST
```
（行为风险）或
```
IDENTITY
```
的检测结果。可选参数：
```
--strict
```
（任何检测结果都视为失败）、
```
--max-files N
```
、
```
--max-bytes N
```
（树内 blob 阈值）。退出码：0 无ASK-FIRST/IDENTITY检测结果，1 存在ASK-FIRST或IDENTITY检测结果，2 使用错误。这是规划的基础信号（外部检查，而非自我判断）；审计仅指出优化机会——不证明仓库可复现。
在进行任何编辑前，提交一份经作者批准的重构规划。将检测结果分为三类，顺序为SAFE→ASK-FIRST→IDENTITY。对于每个ASK-FIRST项，说明变更内容以及结果风险（例如：“仅当在所有配置下都无法访问时，删除此
```
if False:
```
分支才是安全的——是否确认？”）。作者可逐项批准或否决。类别和安全重构方案详见references/release-refactor-catalog.md。
执行SAFE（安全）重构操作（需经作者同意），按以下顺序执行——每项操作对应一个审计类别：
- 布局——添加README（入口点、每个结果对应的精确复现命令、依赖项、目录结构）、LICENSE、
```
.gitignore
```
  ；将零散的脚本移入
```
src/
```
  /包结构并修复导入路径。
- 入口点——记录（或配置）一个可端到端运行流水线的明确命令（
```
make reproduce
```
  /
```
run.sh
```
  /
```
python -m pkg
```
  ）。
- 卫生性——从发布副本中移除
```
__pycache__
```
  、
```
*.pyc
```
  、
```
.DS_Store
```
  、编辑器交换文件；将树内的大型数据/模型 blob 移至下载脚本/归档主机（最后一项属于ASK-FIRST——需确认blob是否为运行时必需）。
逐个处理ASK-FIRST（需先确认）项，绝不批量处理。对于每个已批准的变更：进行最小化编辑，然后通过外部检查验证行为是否保留——重新运行流水线（或冒烟测试）并对比输出结果，而非仅查看代码差异。行为保留需通过重新运行确认，这属于
```
test-research-code
```
/
```
verify-results
```
的职责范围；本技能仅标记并协调，当变更确实存在风险时会停止操作并征求意见。升级处理是一项特性。具体而言：
- 废弃代码——仅在确认没有任何代码导入/访问它之后才可删除。
- 配置——将字面量提取到配置/CLI中，并保证数值完全一致；此处的拼写错误会悄然改变结果。
- 确定性——与作者协作设置/记录随机种子并固定顺序，然后重新运行以再次确认论文数值。为未设置种子的运行添加种子会改变结果——这是最高风险的编辑操作。将种子/环境相关操作移交
```
test-research-code
```
  处理。
处理盲审的身份泄露问题。标记邮箱、本地路径、姓名和
```
.git
```
历史；将深度扫描（提交历史、笔记本元数据、自引用措辞、匿名镜像）任务移交
```
anonymize-paper
```
处理。绝不在盲审上传时通过仓库暴露作者身份。
重新运行审计直至SAFE（安全）清理完成，设置明确的停止条件。循环执行审计→修复→审计，直到没有SAFE/布局/卫生性检测结果，且每个ASK-FIRST项都已解决或主动推迟——而非无限循环。最多约3次循环；若审计仍标记同一ASK-FIRST项，则需升级处理，而非继续编辑。
将重构规划+变更日志写入
```
paper-workspace/submission/refactor-research-code-plan.md
```
，并在
```
paper-workspace/INDEX.md
```
中添加一行记录。首先说明已完成的（安全）操作，然后说明ASK-FIRST项的决策（已执行/已否决/已推迟，每项都需注明结果风险），最后说明身份信息移交情况。引用每个项对应的审计检测结果。

Output

输出结果

A refactor plan (SAFE / ASK-FIRST / IDENTITY buckets, each finding with
```
category
```
+
```
risk
```
+
```
file[:line]
```
) plus a change log of what was applied, vetoed, or deferred — written to
```
paper-workspace/submission/
```
.
The edited repo files (only with per-item approval): README / LICENSE /
```
.gitignore
```
, a
```
src/
```
/package layout, a documented entrypoint, junk removed, and any ask-first edits the author confirmed.
A clear handoff list: seeds/env/tests →
```
test-research-code
```
; packaging/DOI/ badge →
```
prepare-artifacts
```
; deep anonymization →
```
anonymize-paper
```
; number-vs-paper check →
```
verify-results
```
.

重构规划（SAFE/ASK-FIRST/IDENTITY三类，每个检测结果包含
```
category
```
+
```
risk
```
+
```
file[:line]
```
）以及变更日志（记录已执行、已否决或已推迟的操作）——写入
```
paper-workspace/submission/
```
目录。
编辑后的仓库文件（仅在逐项批准后进行）：README/LICENSE/.gitignore、
```
src/
```
/包结构、带文档的入口点、已移除的冗余内容，以及作者确认的任何ASK-FIRST编辑操作。
清晰的移交清单：种子/环境/测试 →
```
test-research-code
```
；打包/DOI/徽章 →
```
prepare-artifacts
```
；深度匿名化 →
```
anonymize-paper
```
；数值与论文一致性检查 →
```
verify-results
```
。

Adapt to your discipline

适配不同学科

The audit reads a directory, not a discipline, so the layout/dead-code/identity checks apply broadly. For non-Python stacks, the determinism and config patterns differ (R

set.seed

, Julia

Random.seed!

, a

renv.lock

Manifest.toml

for the env) — the script already knows several; extend the pattern tables in

scripts/release_audit.py

for your language. The result-preservation contract is universal: clean the repo, keep the numbers.

审计仅读取目录，不针对特定学科，因此布局/废弃代码/身份信息检查广泛适用。对于非Python栈，确定性和配置模式有所不同（R语言的

set.seed

、Julia语言的

Random.seed!

、用于环境的

renv.lock

Manifest.toml

）——脚本已支持多种语言；可在

scripts/release_audit.py

中扩展模式表以适配你的语言。结果保留规则是通用的：清理仓库，保留数值。

Guardrails

约束规则

Preserve exact numerical behavior — this is the whole point. Never apply an ask-first change (delete code, extract a constant, touch seeding/threading/ dtype/order) without explicit author approval, and verify preservation by re-running, never by reading the diff (self-reflection validates its own mistakes — the verification must be external).
When unsure whether a change is safe, it is ask-first. A prettier repo that reports different numbers is a failure.
Run nothing destructive and nothing untrusted.
```
release_audit.py
```
is static, read-only, no network. Re-running the pipeline to verify behavior is the author's call and may need a sandbox/GPU.
Anonymization-aware: for blind review, never expose identity through the repo or
```
.git
```
history; hand the deep sweep to
```
anonymize-paper
```
.
Stay in your lane. Don't add tests/seeds/env (that's
```
test-research-code
```
), mint a DOI or package an artifact (that's
```
prepare-artifacts
```
), or claim the results reproduce (that's
```
verify-results
```
, and "reproduce" is never bit-exact and never this skill's call).
Copilot, not pilot: it plans, asks, and edits on approval; it never submits, deposits, or pushes on the author's behalf.
```
references/
```
files stay one level deep; keep this file under 500 lines.

保留精确的数值行为——这是核心目标。未经作者明确批准，绝不要执行ASK-FIRST变更（删除代码、提取常量、修改随机种子/线程/数据类型/顺序），并通过重新运行验证行为是否保留，绝不要仅通过查看代码差异确认（自我反思会验证自身错误——验证必须是外部的）。
若不确定变更是否安全，则归为ASK-FIRST。一个更美观但报告数值不同的仓库是失败的。
绝不执行破坏性或不可信操作。
```
release_audit.py
```
是静态、只读、不联网的。重新运行流水线以验证行为需由作者决定，且可能需要沙箱/GPU环境。
支持匿名化：对于盲审，绝不要通过仓库或
```
.git
```
历史暴露身份信息；将深度扫描任务移交
```
anonymize-paper
```
处理。
坚守职责范围。不要添加测试/种子/环境配置（这是
```
test-research-code
```
的职责）、生成DOI或打包artifact（这是
```
prepare-artifacts
```
的职责），或声称结果可复现（这是
```
verify-results
```
的职责，且“可复现”绝非完全精确匹配，也绝不是本技能的判断范围）。
协作而非主导：它负责规划、征求意见和经批准后编辑；绝不代表作者提交、存储或推送代码。
```
references/
```
目录下的文件保持一级深度；本文件长度控制在500行以内。

Memory

记忆机制

Uses the shared

.paper-memory/

convention (full spec:

paper-memory-convention.md

At start: read
```
lessons.md
```
to skip already-fixed cleanups and lead with
```
recurring
```
release habits (e.g. "you ship hardcoded
```
/home/<you>
```
paths every repo"); read
```
profile.yml
```
for the contribution type.

At end: append one dated entry per recurring habit, in the canonical format, via

reflect-and-improve

reflect_log.py

python3 ../reflect-and-improve/scripts/reflect_log.py append \
    --memory .paper-memory --skill refactor-research-code --scope recurring \
    --issue "hyperparameters hardcoded across scripts, no config file" \
    --rec "extract to config.yaml/CLI with identical values every release"

Create
```
.paper-memory/
```
on demand and offer to add it to
```
.gitignore
```
; local-only, never uploaded, never copied into this repo.

使用共享的

.paper-memory/

约定（完整规范：

paper-memory-convention.md

）。

开始时：读取
```
lessons.md
```
以跳过已修复的清理项，并优先处理
```
recurring
```
（经常性）发布习惯（例如：“你每个仓库都会提交硬编码的
```
/home/<you>
```
路径”）；读取
```
profile.yml
```
以了解贡献类型。

结束时：通过

reflect-and-improve

的

reflect_log.py

，为每个经常性习惯添加一条带日期的记录，格式遵循规范：

python3 ../reflect-and-improve/scripts/reflect_log.py append \
    --memory .paper-memory --skill refactor-research-code --scope recurring \
    --issue "hyperparameters hardcoded across scripts, no config file" \
    --rec "extract to config.yaml/CLI with identical values every release"

按需创建
```
.paper-memory/
```
目录，并提议将其添加到
```
.gitignore
```
中；仅本地存储，绝不上传或复制到本仓库。