| name | ucl-workflow-patch |
| description | Workflow 補丁機制 (Proposal #31) — workflow QA confirm bug 後 register patch entry; 累積 ≥ 3 patches 自動警示該 refactor (anti-rot 機制)。
跟 qa-bug-reward cross-link — 一筆 QA bug = 一筆 reward + 一筆 patch entry。
觸發詞包含: workflow 補丁 / patch / workflow 出錯 / 修正 workflow / refactor workflow / workflow rot / 補丁機制 / 3 patch / spaghetti workflow / ad-hoc fix。
跨 agent 通用 — Claude / Antigravity / Gemini 都可走本機制 register patch 跟 refactor workflow。
|
UCL Workflow Patch — Anti-Rot 機制
一句話: workflow 出錯 → 修正 + register patch entry; 累積 ≥ 3 patches → 強制 refactor (不准再加 patch)。
🎯 為何需要
Workflow 累積 ad-hoc fixes (e.g. SKILL.md 一直加 "⚠ 注意: ...") 會變 spaghetti — 後續 agent 看不下去 / 邊界 case 互相衝突 / 維護成本爆炸。
3 patch 上限 是 anti-rot 機制: 強制 stop & rethink, refactor 整個 workflow 比繼續貼 patch 健康。
📁 Storage
docs/Workflows/_patches/<workflow-slug>/
_index.json # patch counter + 累積記錄
001_<short-name>.md # patch 1 frontmatter + 詳情
002_<short-name>.md # patch 2
003_<short-name>.md # patch 3 → 警戒
# 第 4 個會被 reject (強制 refactor)
refactor_history.md # refactor 記錄 + archived patches list
_archived_R01_001_...md # refactor 後改 prefix 不刪 (audit)
_index.json 結構:
{
"workflow_slug": "commit-workflow",
"patch_count": 2,
"patches": [
{"id": 1, "filename": "001_xxx.md", "applied_at": "...", "applied_by": "...", "qa_bug_ref": "...", "summary": "..."},
{"id": 2, ...}
],
"last_refactor_at": null,
"refactor_count": 0
}
🛠️ Python tool — workflow_patch.py
位置: AgentCommands/Tools/workflow_patch.py
register — workflow 出錯 + 修正後 register
python AgentCommands/Tools/workflow_patch.py register \
--workflow commit-workflow \
--root-cause "三層 bump 中 UCL submodule 未切 Dev 分支 → detached HEAD" \
--patch-summary "commit 前必先 git -C UCL checkout Dev" \
--applied-by claude-da-xiaojie \
--qa-bug-ref CommitDetachedHEAD
- 第 4 個 register → reject (強制走 refactor)
- 第 3 個 register → warn (剩 0 quota)
- 寫
001_<slug>.md frontmatter + 起因 + 修法 sections
list / status / status-all
python ... workflow_patch.py list --workflow commit-workflow
python ... workflow_patch.py status --workflow commit-workflow
python ... workflow_patch.py status-all
refactor — counter 重置
python ... workflow_patch.py refactor \
--workflow commit-workflow \
--refactor-summary "重寫 ucl-commit skill: 加 pre-flight check (branch state / submodule head)" \
--refactored-by claude-da-xiaojie
行為:
- Append refactor 記錄到
refactor_history.md
- 舊 patches
.md 改 prefix _archived_R<N>_<filename> (不刪)
- Counter reset to 0/3
refactor_count++
✍️ Agent 自律 SOP
撞到 workflow bug + QA confirm
- 修正 workflow (改 SKILL.md / 文檔 / cmd code)
- 走 qa-bug-reward:
python qa_bug_reward.py grant --severity ... --bug-ref <X> (grant Tim reward)
- 走 workflow_patch register: 同步 register patch entry, qa-bug-ref 填同 ref
- 看 status — 若 count = 3 → 標記 next time 必先 refactor
Refactor 時機
status-all 看到 🔴 NEEDS REFACTOR → 走 refactor:
- cat 舊 patches 整理 root cause pattern (哪些 bug 重複出現)
- rewrite workflow (改 SKILL.md / 文檔 / cmd code 根本性重設計)
workflow_patch refactor 標記完成- Counter reset, 重新追蹤新一輪
Cross-link 跟 qa-bug-reward
每筆 patch 該帶 --qa-bug-ref <X> 對應 Tim QA reward ledger entry。這樣:
- QA reward audit: 看 ledger Tim 收 N token = 確認 N 個 bug
- Patch audit: 看 patches/ 看哪些 workflow 累積最多
- Cross-reference: 高 reward 但低 patch = 開發 bug; 低 reward 但高 patch = workflow 設計 bug
🚫 不要做
- ❌ workflow 出錯不 register patch — 失去 anti-rot tracking
- ❌ patch 累積 ≥ 3 仍硬塞 (tool reject 但別找 workaround)
- ❌ refactor 沒寫 refactor_summary — counter reset 但失去脈絡
- ❌ qa-bug-ref 空 — 失去 cross-link audit
- ❌ patch_summary 寫得太抽象 ("修了 bug") — filename 不知道在修啥
- ❌ 一個 workflow 含多個 unrelated bug pattern — 該拆 workflow 不該疊 patch
🤝 跟其他 skill 協作
| Skill | 互補 |
|---|
qa-bug-reward | cross-link qa_bug_ref |
ucl-commit | commit-workflow 自己也適用本機制 (dogfood) |
agent-lessons-log | patch 寫進 lesson jsonl 跨 agent 共享 |
ucl-glossary | 「補丁」/「refactor」/「workflow rot」可進 glossary category=protocol |
📋 Phase 2 Backlog (Proposal #31 後續)
- Auto-detect rot pattern (LLM 看 3 patch root cause 推 common theme)
- Workflow health dashboard (IMGUI page 列各 workflow status)
- Discord broadcast: patch register / refactor 事件
- Cmd_WorkflowPatch (C# Cmd 化, 跟 Treasury / Glossary 對齊)
📖 必讀
- spec: Memory_System_Design Proposal #31
- tool:
AgentCommands/Tools/workflow_patch.py
- storage:
docs/Workflows/_patches/<slug>/
