Reentry

重新進入工作狀態

這個 skill 要解決的問題

人與 AI agent 工作了一整天，隔天或幾天後再回來接手時，失去的往往不只是「我忘了做到哪裡」「接下來要做什麼」。

真正需要重建的資訊可以分成四類，而且每一類遺失的方式、恢復的方法都不同：

前三項描述的是任務本身的狀態，最後一項描述的是人對任務的理解狀態。

最關鍵的是最後一項。在還沒真正理解前就讓任務往下推進，後續工作會建立在不完整的 理解上，之後補回來的成本愈來愈高。這類尚未補足的理解稱為理解債。

所以交接紀錄要完整到隔一段時間之後，只靠它就能重新理解當時的工作狀況，不能只當 提示用。每條規則的研究依據見 references/evidence.md。

環境

以下 $SKILL_DIR 指本 skill 的安裝目錄，依你的環境代入實際路徑。腳本一律用 python3 呼叫，不依賴執行位元、PATH 或任何特定 agent 的機制。只用 Python 3 標準函式庫。

資料放在 $REENTRY_ROOT（預設 ~/reentry），按專案拆資料夾：

~/reentry/
├── orders-api/
│   ├── handoff.md      # 工作接續紀錄，每次重新建立
│   ├── artifacts.md    # 任務狀態，腳本與 agent 合寫，每次重新建立
│   ├── debt.md         # 理解債（以為自己懂但沒懂），保留尚未理解的項目
│   ├── open-questions.md  # 待確認（知道自己不知道），保留尚未查清的問題
│   └── decisions/      # 決策紀錄，逐筆保留
└── billing-service/

只有已登記的專案才納入管理。沒有對應資料夾的專案視為未登記，刪除資料夾等於取消登記。不要自動建立或恢復資料夾。

格式規範在 references/file-formats.md，寫任何一個檔案之前先讀它。

先判斷目前處於哪個階段

• 使用者隔了一段時間回來，準備繼續先前的工作 → 回來階段，參考下方「回來時」
• 使用者準備結束這次工作，或剛檢視完 agent 的一批產出 → 收工階段，參考下方「收工時」

回來時

這個階段不需要重新分析或整理內容，只要執行腳本，並將結果原樣提供給使用者。

如果使用者尚未指定專案，先執行索引腳本，列出可接續的專案供他選擇：

python3 "$SKILL_DIR"/scripts/reentry_index.py

指定專案之後：

python3 "$SKILL_DIR"/scripts/reentry_read.py <專案名>

腳本輸出的內容必須完整保留，不要改寫、摘要或重新排版。

使用者自己的用詞是他最好的回憶線索，換句話說等於把線索抽掉；而每次輸出長得一樣， 他才建立得起「打開就知道哪裡看什麼」的習慣。

輸出順序固定如下：

警告（若有）→ 上次叫它做什麼、做到哪裡 → 上次的決定（若有）→ 欠債 → 待確認（若有）→ 下一步

下一步壓在最後是刻意的——避免還沒掌握前因後果就直接繼續往下做。

「上次的決定」只在上次收工真的寫了 decisions/ 才顯示。永遠留一個空欄位會退化成 每次略過的噪音。

腳本最後會顯示一句：「先用自己的話說一次下一步，再開始動手」。

這句只是提醒。不要追問、不要要求他打字、不要確認他有沒有做——他回來時已經準備 動手了，這時候加摩擦只會讓他關掉整套流程。

收工時

整個收工流程大約五分鐘，並直接整合進使用者原本的 review 流程。

這個數字是建議不是上限。它要擋的是兩件事：拖太久，以及卡在回想上出不來。 如果使用者對今天做的事很有想法、想寫得詳細，那不是問題——紀錄詳細本身沒有壞處， 不要因為時間到了就催他收尾。

第一階段 — 請使用者關閉工作畫面，憑記憶整理

請使用者先離開目前的工作畫面，再憑記憶寫下四項內容。寫進 handoff.md 時的標題必須逐字用這四個——腳本靠標題原文解析，改了字就讀不到，而且不會報錯：

## 我叫它做什麼，做到哪裡
## 下一步
## 關鍵詞
## 不確定的地方

第一項的提問方式很重要。

不要問「這次做了什麼」，因為實際執行工作的是 agent，而使用者主要負責提出需求、檢視結果與做出判斷。若要求他描述具體實作內容，很容易變成憑印象推測 agent 實際修改了什麼。

相較之下，使用者比較容易記得的是：自己原本要求 agent 完成什麼，以及 agent 最後交付了什麼結果。從這兩個角度提問，才能準確喚回他真正保留下來的工作脈絡，而不是要求他回想自己沒有直接執行的細節。

同樣地，如果過程中曾做出重要決策，也應在收工時一併記錄到 decisions/（見下方「決策紀錄」）。

關鍵是他要在不查看工作畫面的情況下完成。判斷時看得到答案，延遲效應幾乎完全消失——看著 diff 評估自己懂不懂，等於沒評估。

不要問他「你懂了嗎」。這裡沒有任何自評動作。人在疲倦時會傾向點頭同意，而收工正是疲倦的時候。改成請他憑記憶產出東西——哪些地方能清楚說明、哪些地方說不出來**，本身就是理解程度的訊號**，比任何自評都準。

下一步只保留一項

一次留下多個下一步會增加重新接手時的判斷成本，所以只留一個。

寫到什麼程度分三層，不是通過或不通過：

最好    具體對象 ＋ 怎麼算做完
        把 refunds 的 retry 上限調成 60 秒，改完跑 tests/test_retry_utils.py

可接受  只有具體對象
        調 refunds 的 retry 上限

不行    沒有對象
        繼續做 retry ／ 弄一下那個

中間層明顯比較弱，但不是沒用——回來時仍然知道從哪裡切入。底線是連對象都沒有， 那等於沒寫。

中間層直接收下，不要催他補齊。收工時人已經累了，為了補一格把流程拉長， 下次他就不寫了。

只有掉到底線時問一句：「這個要怎麼算做完？」問一句就好，不要要求重寫。 這跟代號展開是同一種處理——agent 問、使用者答，不是 agent 代寫。

所有代號都要補上實際內容

像是「T-3」「那個 bug」「上次那個問題」這類寫法，都高度依賴當下的工作脈絡。隔了一段時間之後，使用者往往還得重新查文件，才能知道這些代號實際指的是什麼。

因此代號本身不足以成為有效的回憶線索。它只能指向某個已知內容，但前提是使用者仍然記得那段脈絡——而這套流程要處理的，正是工作中斷後脈絡已經變得模糊的情況。

好： T-3（把訂單重試邏輯抽成獨立的 retry-utils 模組）
壞： T-3

或直接寫出完整的任務內容。

使用者寫下的內容不要代為潤飾，也不要自行補充。這些文字的價值在於保留他當下實際記得與理解的內容，因此應盡量維持原貌。

唯一的例外是代號展開。補上代號的實際含義不是為了讓文字更漂亮，而是避免只有當下的使用者看得懂、隔一段時間後卻失去辨識依據。看到這類代號時，只需要追問一句：「這個代號具體指的是什麼？」

第二階段 — 校驗

由目前這個 agent 直接校驗，不要另開 subagent。

另開一個乾淨脈絡的 agent 要重讀 diff、重讀檔案，慢。而整個收工流程只有五分鐘的預算， 慢下來的每一分鐘都在增加使用者下次直接跳過的機率。流程被跳過的損失大於偏誤本身。

代價是你已經參與整個過程，使用者的描述只要沾到邊，你就會自動補完缺的部分然後判他 答對。知道答案的人測不出別人答了多少——所以判斷標準必須外部化，靠下面三條規則， 不能靠你覺得他寫得對不對：

1. 不問「他寫的對不對」，問「這句話單獨拿給一個沒參與的人看，指得出具體對象嗎」。 前者你會用脈絡補完，後者不會。
2. 要指出對不上，必須引他寫的那一句原文，加上 diff 裡對應的位置。 不准拿對話裡 講過、但他沒寫進紀錄的東西，當作他記得。
3. 他沒寫的就是沒寫。 你知道他其實懂，不算數——三天後的他只有紙上那幾行。

需要更嚴的校驗時才走 references/verifier-prompt.md：開一個乾淨脈絡的 agent，或請 使用者另開對話。那是選用路徑，不是預設。 什麼時候值得付那個時間：這次改動特別大、 或者你發現自己一直在替他補完。

校驗分成兩類，處理方式不同：

• 事實資訊：例如修改了哪些檔案、執行了哪些測試、結果如何。這類內容可以直接與實際紀錄比對，若有落差，可以明確指出「這裡與紀錄不一致」。
• 理解內容：例如某個機制為什麼這樣設計、各元件之間如何運作。這類判斷只能表達為 「agent 認為」，不能當成絕對結論。

理解那類不要寫成「你理解錯了」。寫成判決他會照單全收，留成意見他才會反駁—— 而反駁的過程本身就是在確認他懂多少。

校驗結果最多三項，由校驗者自己排序。十項他會整批略過，三項才會真的讀。

此外，校驗時再從既有的理解債中挑選一項舊問題讓使用者回答，詳見下方「還債」。

第三階段 — 根據校驗結果修正紀錄

使用者完成修正後，原始版本仍然要保留，寫入 handoff.md 的 ## 我當初記錯的。

原始與修正版之間的差異就是理解債清單，自動產生，不需要他自評或動手標記。

如果對不上的比例很高，在 frontmatter 加一則 warning，讓他下次回來優先看到。 它只保留到下一次收工，不是永久紀錄。

第四階段 — 整理任務狀態與理解債

python3 "$SKILL_DIR"/scripts/reentry_artifacts.py <專案名> <專案工作目錄>

腳本會把可以直接取得的客觀資訊（路徑、增減行數、測試結果）寫進 ## 明細 與 ## 驗證。其中 ## 改了什麼 那節要你自己寫——腳本不知道 store/migration.py 是「migration runner」，那需要理解。

寫功能層：

好： 修改 2 個設定載入檔與 1 個 CLI 進入點，新增 3 個測試檔驗證分層契約
壞： 改了 6 個檔（+412 −0）

如果改動涉及專案核心的檔案要特別標出來。必須從 ## 明細 推，不能憑印象編—— 你剛做完這些事，很容易寫出「應該有做」而不是「確實做了」。

把使用者打的東西如實寫進 handoff.md，不改寫、不美化（代號展開是唯一例外）。他寫的句子是他的檢索線索。

把 ## 不確定的地方 升級成 open-questions.md 的條目（已經在這次解掉的就不用）。 handoff.md 每次整份覆寫，不升級的話那些疑問下次收工就消失了。

待確認與理解債不共用檔案，兩者的還法不同（見 references/file-formats.md）。

然後把記錯裡屬於理解問題的那些升級成 debt.md 的條目：

• 對「為什麼必須這樣設計」理解錯誤 → 屬於理解債
• 記錯檔名、行數、測試數量 → 不屬於，那是記憶誤差

每一條都寫成問題並附上對應的 commit SHA，不要附答案。答案留在 diff 裡， 他得自己走一趟才拿得到，那趟路就是還債本身。

還債

理解債不另外安排處理流程，整合到下一次收工時的校驗階段。

• 校驗者除了檢查本次工作的內容之外，再從既有的理解債中挑選一項提問。如果使用者能正確回答，就把該項目的 - [ ] 改成 - [x]。
• 每次只處理一項。
• 優先選擇與目前「下一步」相關的理解債；如果沒有直接相關的項目，再從其他尚未解決的挑選。
• 是否已經理解，由校驗者根據回答判斷，不需要另外設計一套判定流程。

在詢問舊的理解債時，校驗者必須取得該條目所記錄的 commit SHA 對應的 diff，而不是使用這次工作的 diff。如果找不到對應的 diff，就直接說明無法取得足夠資訊，不要用目前的變更內容推測過去問題的答案。

沒有足夠依據時，不應判定使用者已經理解。

決策紀錄

收工時如果做了值得留的決定，寫進 decisions/（格式見 references/file-formats.md）。

判準：如果之後由其他人接手，這項資訊是否仍然重要。操作上看這個決定有沒有留下 後續待辦、或產生技術債——接手的人最需要知道的就是這兩件事。

技術債不進 debt.md，跟著決策紀錄走。理解債靠回答問題還，技術債靠寫程式還， 還法不同。

決策紀錄分兩層：第一層留在 decisions/，第二層由使用者自己挑進專案 repo。 第二層沒有固定時機，不要主動提醒。搬過去時可以改寫成給別人看的樣子—— 第一層給自己，第二層給接手的人。

參考檔案

幾個不應過度優化的地方

這套流程中有些步驟看起來可以進一步簡化或自動化，但如果處理方式不當，反而會削弱原本的效果。以下幾點應特別避免：

• 不要幫使用者把交接紀錄補得更完整。第一階段的重點，是觀察他在沒有提示的情況下實際能回想並說明多少內容。由 agent 主動補充的話，就無法再判斷哪些部分是他真正記得與理解的。

• 不要在使用者回來時重新整理或改寫輸出。固定的內容順序與他原本的用詞，本身就是重新建立工作脈絡的重要線索。每次都重新組織或改寫，反而會增加閱讀與理解的成本。

• 不要把理解層面的校驗結果寫成確定結論。這類結果應保留為 agent 的判斷，而不是直接告訴使用者「正確答案」。結論過於明確的話，他可能直接接受，而沒有重新思考或解釋自己的理解。

• 不要在理解債旁直接附上答案。理解債的目的，是讓使用者之後透過回想、查閱與重新說明來確認自己是否真正理解。答案直接附在問題旁，這個確認過程就會失去作用。

• 不要持續提醒使用者還有多少理解債尚未處理。理解債刻意設計成不阻擋目前工作的項目，只在既有的校驗階段中逐步處理。額外加入提醒、清單或待辦壓力的話，他很可能在忙碌時選擇忽略甚至停用整套流程。

• 不要替尚未登記的專案自動建立資料夾。專案登記代表使用者主動決定將這個專案納入管理。系統自動建立的話，就會失去這個明確的管理邊界。