A research project spans several months, dozens of experiment cycles, and multiple agent sessions. **Agents have no cross-session memory, and humans forget too.** Without a single source of truth, every takeover requires re-doing the archaeology: Why was this topic chosen in the first place? Why did this experiment fail? What was supposed to be done next?
This skill establishes and maintains that source of truth. There is only one core convention:
PROJECT.mdis the sole entry point. When taking over any project, read it first; after completing any round of work, write back to it.
Three red lines that must not be crossed
When taking over someone else's project, you are facing aworkspace you do not understand but that matters to the user.
- Do not delete anything. The tools of this skill have no delete operation at all.
Things judged useless are moved into
archive/, with the reason attached, and can be moved back at any time. Your judgment that "this file is useless" may be wrong, and the cost is asymmetric. - Do not move any file before obtaining explicit consent. Investigate first, report first, ask first. The user may be running a script that depends on the current path.
- Ensure rollback is possible. Before acting, first bring the workspace into a clean git state; migration tools default to dry-run, and after execution generate an undo script.
Tools
SK=<这个 skill 的目录>
# 新建项目
python3 $SK/scripts/init_project.py <path> --name "<一句话主题>" \
[--deadline 2026-11-14] [--venue "CVPR 2027"] [--force]
# 探查一个陌生项目（只读，不改动任何文件）
python3 $SK/scripts/explore_project.py <path> [--json] [--stale-days 60]
# 执行用户已确认的整理方案（默认 dry-run，--apply 才动手；只移动和归档，无删除）
python3 $SK/scripts/migrate.py <path> --plan plan.json [--apply]
# 审计（初始化与否都能跑）
python3 $SK/scripts/project_status.py <path> [--json]
init_project.py is idempotent—files that already exist are skipped by default and listed.
--force resets the template, butdoes not directly overwrite: the original is first moved into archive/<日期>/ and recorded in
archive/MANIFEST.md, then the new template is written.
Submission scheduling is managed by this skill. When the user gives a deadline, directly generate a schedule with real dates;
do not restate the cadence in the conversation:--deadline will write out, according to the methodology's four-week cadence,
docs/writing/schedule.md(each line with a specific date + a checkbox), and afterwards project_status.py
continuously compares the countdown and chapter progress. How the writing itself is done is the job of paper-writing .
What project_status.py checks
It does not merely list files; it executes the criteria in the methodology:
| What it checks | Why this item is worth checking automatically |
|---|---|
| Which of the four situations the topic falls into | Situation 1/2 = a well-established solution already exists. Continuing further at this point is pure waste, and the earlier you stop the loss the better, so it reports blocking rather than a warning |
| How long PROJECT.md has not been updated | >14 days means the person taking over will get stale status, which is more dangerous than no status |
| Days until deadline vs chapter progress | The methodology requires starting writing one month before the deadline. If the countdown enters 30 days while all chapters are empty → blocking |
| How many entries in the experiment log do not state the "essential technical reason" | These cycles did not obtain a gradient, so the next change is random. This isthe number one killer of project speed, more fatal than doing experiments slowly |
| How long ago the most recent experiment record was | >7 days indicates the cycle frequency has dropped, and the cause must be found |
| Whether §6 Next Step is empty | A project without a clear next action will silently stall |
Which process to follow
| Situation | Flow |
|---|---|
| New project | Flow A(below, one command + fill in §1 §2) |
| An existing messy project that the user wants to organize | Flow B: five-stage multi-turn dialogue, full text see references/takeover.md |
| The project already has this structure | Agent handoff protocol(below) |
| The user wants to do something else, and the project happens to be very messy | Do the work first, and at the end mention that it can be organized,do not take it upon yourself to move files midway |
The last line is deliberate: organizing is something that requires the user's attention, and doing it when they are not ready will only cause trouble.
Flow A: Create a new project
python3 $SK/scripts/init_project.py ~/work/sparse4d \
--name "稀疏视角下的动态场景重建" --deadline 2026-11-14 --venue "CVPR 2027"
Thenfirst fill in only §1 and §2 of PROJECT.md, together with research-ideation。
The "four-case determination" in §2 is the gate: if it is determined to be case 1 or 2, stop and switch to a failure case,
do not start writing code. Spending half a day on this step can save half a year. After the determination, run project_status.py
once to confirm there are no blockers, then proceed to §3.
Flow B: Take over an existing messy project
What the user hands over is a folder that has been running for several monthsand was not established according to this structure. This is a multi-turn dialogue, not a single command——five stages, and at the end of each stage stop and wait for the user:
1 探查（只读，一个文件都不动） → explore_project.py
2 汇报画像，问要不要整理 → 先证明你看懂了，再提整理；给 A/B/C 三档
3 拟迁移方案，逐条对齐（多轮） → migrate.py dry-run，用户几乎一定会改几条
4 执行，然后补骨架 → migrate.py --apply，再 init_project.py 补空缺
5 考古式回填 PROJECT.md → 找不到的留空，留空比编造好
Before starting stage 1, first read references/takeover.md:
the wording for each stage, the to semantics of the migration plan, the--apply safety guarantees, and thearchive/ conventions are all there.
There are two sequence traps that you will step into if you do not read it:migrate first, then build the skeleton(if reversed, the user's real notes.md
will not be migrated into docs/topic.md), and before starting, first make git enter a clean state.
File format
Directory structure,PROJECT.md when each of the six sections should be written back, and the acceptance criteria for one experiment log record
(including an unqualified→qualified rewriting example):references/files.md。
Read it when you need to create directories, write back PROJECT.md, or judge whether an experiment record is qualified.
One criterion is worth knowing in advance:the purpose of the experiment log is not to record what was done, but to record what gradient was obtained——
a record that stops at the "surface reason" is unqualified, andproject_status.py will raise an alarm.
Agent handoff protocol
When the project already has this structure:
project_status.py <path>—— get the global status and blockers in 30 seconds- Read
PROJECT.md—— complete context - Only when needed, according to the next step in §6, go deeper into the corresponding
docs/orexperiments/ - After finishing the workwrite back §4/§5/§6 and the "last updated" date, then end the session
Do not start modifying code or writing a paper without reading PROJECT.md—— you will repeat paths the project has already ruled out, and this is exactly the meaning of the experiment log.
**When the project is not in this structure:** follow Flow B, start from explore_project.py ,
understand first, then report, then ask, then act.
Relationship with other skills
This skill managesstate and structure, and how to do each specific step is elsewhere:
| Sections of PROJECT.md | Which skill to read when stuck |
|---|---|
| §2 Topic status | research-ideation |
| §3 Technical approach | research-ideation |
| §4 Experiment status | research-experiment |
| §5 Paper status | paper-writing → paper-revision → paper-self-review |
docs/literature/ |
research-ideation/references/literature-tree.md; use for retrieval literature-review, use for reading papers pdf-explore |
paper/figures/ |
figure-style → figure-composer → paper-narrative |
See the overall flowchart in research-methodology。