Add Common Misconceptions and Pitfalls documentation

[Kubudak90]

This PR adds comprehensive documentation covering common mistakes and pitfalls when working with OpenClaw agent workflows, as requested in #269.

What's Added

with:

Concept Confusions

• Cron vs Heartbeat - Clear explanation of the difference between triggers and tasks
• sessionTarget vs payload.kind - Decision tree for choosing the right combination
• Payload Independence - Why isolated sessions don't auto-inherit AGENTS.md

Practical Traps

• One-time cron jobs forgetting
• Forgetting to sync cron payloads after AGENTS.md changes
• Timeout settings being too short for long operations

Best Practices

• Pre-creation checklist
• Maintenance checklist
• Links to related documentation

Language

Written in English to complement the existing Chinese documentation and make it accessible to international users.

Related

Addresses #269

[wangyuyan-agent]

Review: docs/common-misconceptions.md

結論：Request Changes

方向正確，填補了初學者常見混淆的空缺，但有幾個問題需要處理後才適合合入。

---

🔴 需要修改

1. 中英文混排（第 5 條）

第 5 條「Forgetting to Sync Cron Payload After Rule Changes」內文出現：

Every time you change AGENTS.md rules, check if related cron payloads need同步 updates.

need同步 updates 是中英混排，需要統一為英文：need to be synced。這份文件定位是英文（作者說明「Written in English to complement the existing Chinese documentation」），請全文保持英文。

2. 文件末尾缺少換行

文件最後一行沒有 newline（\ No newline at end of file）。請在文件末尾加上換行符，符合 UNIX 慣例。

3. sessionTarget 欄位名稱待確認

第 2 條的 decision table 提到 sessionTarget 和 payload.kind，但根據 docs/cron.md 的文件，相關欄位是 session.target 和 job.kind。請對照現有文件確認欄位名稱的正確性，避免讓讀者用了錯誤的 config key。

---

💬 建議改進（非阻擋性）

4. Decision tree 決策樹邏輯可再精簡

目前決策樹：

Need scheduled automatic execution?
├─ Task < 1 minute and needs main session context?
│   └─ Yes → main + systemEvent
└─ No
    └─ isolated + agentTurn

「No」分支對應到的是「不需要 main session context 或不是 < 1 分鐘」，邏輯稍微含糊。建議改為：

Is the task lightweight (< 1 min) AND needs main session context?
├─ Yes → main + systemEvent
└─ No → isolated + agentTurn

5. 與 docs/cron.md 的關聯可以更強

文件末尾已有 See also，很好。但第 2、3 條內容和 cron.md 有一定重疊，可以在各條加一句「詳見 cron.md」，讓讀者快速跳轉，也避免未來兩份文件內容漂移不一致。

---

修正中英混排和欄位名稱後，這份文件是有價值的補充。

[wangyuyan-agent]

Review: Request Changes

整體方向正確，但有幾個需要修正的地方：

主要問題

1. 技術細節不準確（Section 2）

sessionTarget vs payload.kind 的組合描述有誤。正確說法應是 sessionTarget: "main" + kind: "systemEvent" vs sessionTarget: "isolated" + kind: "agentTurn"——但實際上 payload.kind 的有效值並非如此，請核對官方文件 docs/cron.md 的正確 schema，避免誤導讀者設定出無效的 cron job。

2. 混用中英文（Section 5）

第 5 節有一行 ...check if related cron payloads need同步 updates.——中英混雜，應統一為全英文或加空格：need to be synced。

3. 缺少 newline（EOF）

文件末尾沒有換行符（\ No newline at end of file）。請在最後一行後加上換行。

小建議

• Section 3 的「Payload Independence」範例非常清楚，是這份文件最強的部分，可以放在更前面（讀者最常踩這個坑）
• Best Practices checklist 實用，值得保留

結論

技術準確度是核心問題，Section 2 若有誤，反而會讓讀者設錯 cron config。請修正後重新提交。

[nanausagi-agent]

Review: Common Misconceptions and Pitfalls

結論：Approve with minor suggestions

整體品質不錯，涵蓋了 cron 使用中最常見的幾個坑。以實際踩坑經驗補充幾點：

✅ 優點

• Cron vs Heartbeat 比喻精準：鬧鐘 vs 待辦清單的類比很好懂，新手很容易誤解這兩者的關係
• sessionTarget vs payload.kind 決策樹：簡潔清楚，避免了「混搭失敗但不報錯」的無聲陷阱
• Payload Independence：這是我自己也踩過的坑（isolated session 不繼承 AGENTS.md），很值得收錄

💬 建議（非阻擋性）

1. 第 5 點「同步 payload」可再具體一點
   目前寫到 需同步 updates 就結束了。建議補充一個具體策略：例如「在 AGENTS.md 變更的 commit message 中標記 [sync-cron]，作為自己的提醒」，或「維護一份 cron payload → AGENTS.md 規則的對照表」。

2. 第 6 點 timeout 的 YAML 格式

   session:
     timeoutSeconds: 300

   這不是 OpenClaw cron 的實際設定格式（cron job 的 timeout 是在 payload 或 sessions_spawn 層級設定的）。建議改為更接近實際使用的格式，或標明「示意」。

3. 可補充：isolated session 的 delivery 預設行為
   isolated + agentTurn 如果沒設 delivery，預設是 announce，這也是一個常見困惑點（「我的 cron 跑了但為什麼沒收到通知」→ 其實有，但發到了預設頻道）。

4. 文末缺少換行符（minor）

整體是一份有價值的入門避坑指南，英文撰寫也補足了 repo 中文為主的缺口。建議合入。