Ten-Day Pitfall Log: 16 Fatal Lessons in Building an AI Assistant System

May 7 to May 17, 2026, 10 days, 16 pitfalls, 4 system-level disasters. This is not a success story, this is a failure textbook, and it is more valuable than any success case.

Introduction: Why Write This

Over the past 10 days, the UltraClaw system underwent a transformation from a "pure conversational machine" to a "complete AI assistant with memory, deployment, research, and development capabilities." In this process, every major capability upgrade was accompanied by a major failure.

Below is the complete record of all 16 pitfalls, root cause analyses, and improvement measures. Classified by severity:

Severity	Count	Definition
🔴🔴🔴 Fatal	5	Causes permanent data loss or critical failure of system functionality
🔴🔴 High	6	Causes incorrect conclusions or interruption of important functionality
🔴 Medium	5	Causes reduced efficiency or directional deviation

I. Complete Pitfall Timeline

#	Date	Pitfall Name	Severity	One-Minute Summary
1	5/7	Lovable data loss	🔴 Medium	Built an SEO website with Lovable; after deleting branding traces, the data became inaccessible, and all old articles + images had no backups
2	5/10	Session amnesia	🔴🔴🔴	Worked on Agentics Website for 6+ hours (27 runs, 10.5MB log); did not write a memory file at the end, and completely forgot it the next day
3	5/10	Unrecorded model switch	🔴 Medium	Switched from qwen to deepseek mid-session, with no record; inconsistent behavior could not be traced
4	5/10	Deployment through GitHub by mistake	🔴🔴 High	Violated the "deploy only via CLI" rule and deployed via GitHub auto-deploy; was corrected on the spot by the boss
5	5/12	Misjudged WeChat Plugin status	🔴🔴 High	Saw a config warning and concluded the plugin was not installed; in fact, there were 101 active WeChat sessions
6	5/12	Cross-channel Session isolation	🔴🔴 High	The `sessions_list` API could not discover sessions across channels; WeChat and Feishu could not see each other
7	5/12	Pattern Matching exclusivity error	🔴 Medium	A Feishu user ID appeared in WeChat session content, causing channel misjudgment
8	5/12	UTC/HKT time zone boundary	🔴🔴🔴	The daily autocheck from 00:00-08:00 HKT would definitely be missed, because UTC was still the previous day
9	5/13	`find -newer` dependency	🔴 Medium	When the current day's daily log did not exist, `find -newer` behavior was nondeterministic
10	5/12	API cross-channel blind spot	🔴 Medium	The `dmScope: per-channel-peer` restriction caused the API to see only the current channel
11	5/14	Marker conflict	🔴🔴🔴	Two cron jobs shared the `<!-- consolidated -->` marker, causing memory consolidation to fail silently for 3 days
12	5/14	dream-log overwrite	🔴🔴🔴	The `write` tool overwrote dream-log.md, permanently losing 25 historical records (45 days)
13	5/14	weasyprint engine failure	🔴🔴 High	A gobject library path issue on macOS completely prevented the PDF rendering engine from starting
14	5/14	9982.HK misjudged as suspended	🔴🔴🔴	Tavily snippet cross-document concatenation + confirmation bias caused a normally trading stock to be misjudged as suspended
15	5/14	DI HKEXnews website failure	🔴🔴 High	The Hong Kong stock HKEXnews website had ASP.NET errors all day, making the T1 data source completely unavailable
16	5/16	JSONL v2 format Bug	🔴🔴🔴	OpenClaw format upgrade caused all old parsing scripts to fail; 22 user messages were marked as 0

II. In-Depth Category Analysis

🧠 Category A: Memory System (8 pitfalls, 50%)

The memory system is the core infrastructure of the entire system, and also the area with the most issues.

Pitfall #2: No Checkpoint at Session End (5/10, Fatal)

Event: The previous night, I worked on the Agentics Website for 6+ hours (10.5MB session log, 27 runs), and at the end, I did not call the write tool to write to the memory file. When I woke up the next day, I had completely lost my memory.

Root Cause:

Execute tasks (write code, deploy, analyze) → deliver results to user
                                    ↓
                              ⚠️ "Writing memory" is a meta-task
                                    ↓
                              No automatic trigger mechanism

When the Agent is focused on execution, the context window is filled with work content. The meta-task of "writing logs" was never queued for execution.

Fix: Establish a three-layer protection mechanism: task-level real-time writing → session-end checkpoint → Heartbeat/Cron fallback check.

Lesson: Documentation beats memory. If you don't write down anything you've done, it's as if it never happened.

Pitfall #11: Marker Conflict (5/14, Fatal)

Event: Auto-dream reported "no new content" for 3 consecutive days, but 5/13 was the busiest day ever (AK-SDD v4.1 upgrade, Deal Execution Plan, 4 Agentics articles, 4 research tasks), and none were merged into MEMORY.md.

Root Cause: Two independent cron jobs share the  marker:

Cron	Frequency	Meaning of writing the marker
`daily-log-autocheck`	Every 2h	"I've finished checking" (actually nothing was merged)
`auto-memory-dream`	Daily at 04:00	"Merged into MEMORY.md" → skip when marker is seen

Fatal Chain: autocheck runs first → writes marker → dream sees the marker and skips → content never gets merged.

Fix: Add 🚫 to the prompt to explicitly prohibit autocheck from writing ; only dream may write it.

Lesson: Two independent processes should not share the same flag. Namespace isolation is a basic principle.

Pitfall #12: write tool Overwrite (5/14, Fatal)

Event: When Dream #26 wrote to dream-log.md, the model used the write tool instead of exec (cat >>). write = overwrite the entire file, causing all previous 25 complete dream records (3/31-5/13, 45 days of history) to disappear.

Root Cause: The prompt said "Append to dream-log.md", but did not specify the specific tool. The model chose write, and the semantics of write are to overwrite.

Fix:

Change the prompt to 🚫 prohibit the write tool + force exec cat >> heredoc
Must cp backup before writing

Lesson: The prompt must explicitly state the specific tool name. "Append" is not enough; you must write "Use exec with cat >> heredoc, NEVER use write tool".

Pitfall #8: UTC/HKT Time Zone Boundary (5/12, Fatal)

Event: Automatic checks during 00:00-08:00 HKT every day are bound to miss things, because session timestamps are in UTC (8 hours behind HKT), while the check greps using the HKT date.

Root Cause:

HKT 00:00 = UTC 16:00 (previous day)
autocheck grep "2026-05-13" → session timestamp "2026-05-12" → 0 match

Fix: Switched to grepping three dates simultaneously: HKT today | UTC today | UTC yesterday.

Lesson: Cross-time-zone systems must always account for time zone conversion. Always search multiple dates.

Pitfall #16: JSONL v2 Format Bug (5/16, Fatal)

Event: The boss reported "a huge amount of interaction over the past 8 hours", but autocheck replied "all 7 sessions are pure cron sessions". The main session had 619KB / 22 real user messages, all of which were missed.

Root Cause: The OpenClaw JSONL format was upgraded from v1 (flat) to v2 (nested), but the old scripts still used v1 checking logic:

v1: {"type": "user", "content": "message"}       → d.get('type') == 'user' ✅
v2: {"type": "message", "message": {"role": "user"}} → d.get('type') == 'message' ❌

Fix: Dual-format compatibility (v2 first + v1 fallback) + Sanity Check Gate (force a double-check when everything is 0).

Lesson: A JSONL format version change = every dependent parsing script may fail. Double defense is better than trusting a single path.

Pitfall #5: Misjudged WeChat Plugin Status (5/12, High)

Event: Saw a config warning and concluded WeChat plugin was not installed. In fact, the Tencent version plugin was running normally, with 101 active sessions.

Root cause: Config warning targets an old path check, and does not affect actual operation of the Tencent version plugin. Concluded first, then checked data.

Lesson: Check the session file (data) first, then conclude. Surface evidence is not enough to judge.

Pitfall #6/#10: Cross-channel Isolation (5/12, High+Medium)

Event: From a Feishu session, cannot discover WeChat sessions through API. dmScope: "per-channel-peer" restricts API to only see the current channel.

Fix: Bypass API and directly read the file system (find agents/main/sessions/).

Lesson: When API has limitations, directly read the file system. This is the key breakthrough for cross-channel integration.

Pitfall #9: find -newer Dependency (5/13, Medium)

Event: find -newer daily.md is unreliable when daily log is initially missing.

Fix: Switched to find -mmin -240 (time range, no file dependency).

Lesson: Avoid relying on files that may not exist as query conditions.

🚀 Category B: Deployment and Infrastructure (3 pitfalls)

Pitfall #4: Incorrect Deployment via GitHub (5/10, High)

Event: After Build succeeded, used git push to wait for Vercel auto-deploy. The boss corrected on the spot: "GitHub is for backup, deploy directly via CLI."

Root cause: Did not solidify the deployment process into a mandatory rule. Last time, the CC project already discussed role division, but it was not written into permanent rules.

Fix: Created skills/deploy-vercel/SKILL.md + wrote into PERMANENT-RULES.md R6. Standard process:

npm run build → git commit → git push (backup) → npx vercel --prod --yes (deployment) → curl verification

Pitfall #13: weasyprint engine failure (5/14, High)

Event: On macOS, the weasyprint PDF engine completely failed to start due to a gobject path issue, forcing a downgrade to markdown_pdf (layout is flattened, lacking hierarchy).

Root cause: The C library installed by Homebrew (libgobject-2.0.0.dylib) is in /opt/homebrew/lib/, not in the Python cffi default search path. Linux-style filenames are incompatible with macOS.

Fix: Add the following at the top of md2pdf.py:

os.environ.setdefault('DYLD_LIBRARY_PATH', '/opt/homebrew/lib')

Must be placed before import markdown.

Lesson: C libraries installed by macOS Homebrew are not in the Python search path by default. DYLD_LIBRARY_PATH must be set before import.

📊 Category C: Data and Analysis (3 Pitfalls)

Pitfall #14: 9982.HK Misjudged as Suspended (5/14, Fatal)

This was the most serious analytical error in the past 10 days.

Event: 9982.HK (Central China Management, HK$0.14), which was trading normally, was misjudged as suspended. Three stages failed simultaneously:

Stage	Failure Mode
A. Tavily Search	The 9982 announcement and the "suspension" keyword came from different documents; the snippet stitched content across documents into a misleading conclusion
B. Gate 0 Verification	Did not perform a real-time quote check (Investing.com showed it was trading normally)
C. Confirmation Bias	Xueqiu post + Google Finance + snippet triple-locked the wrong conclusion

Fix:

Added three red lines to Gate 0 (must have ≥1 real-time quote source)
Tavily snippets must not be cited directly as conclusions
Added cases to the Anti-Rationalization table

Lesson: Tavily snippets may stitch together unrelated content across documents. The boss's intuition is the highest-authority verification mechanism. Real-time quotes are a step in Gate 0 that cannot be skipped.

Pitfall #15: DI HKEXnews Website Outage (5/14, High)

Event: The Hong Kong stock market's HKEXnews website (di.hkex.com.hk) had ASP.NET errors all day, and the T1 precise data source was completely unavailable.

Fix: Established a three-layer fallback query process: Layer 1 direct connection to DI → Layer 2 Tavily cache → Layer 3 annual report fallback.

Lesson: A single data source is never reliable. A fallback plan is mandatory.

🔧 Category D: Tool Selection (1 Pitfall)

Pitfall #1: Lovable Data Loss (5/7, Medium)

Event: Used Lovable to build an SEO website. After deleting Lovable branding traces, all articles and images stored in Lovable Cloud became inaccessible. The old data required authorization from the previous person in charge before it could be migrated, and there was no backup.

Lesson: Do not use a website building app with "code watermarks" to build an SEO website. Use Claude Code, Antigravity, Trae, or OpenClaw. During handover, all important data must be backed up.

III. Root Cause Pattern Analysis

Reviewing the 16 pitfalls, we can summarize 5 recurring root cause patterns:

Pattern 1: Meta-Task Neglect (Pitfalls #2, #3)

Essence: When the Agent focuses on executing the user task, auxiliary tasks such as "recording" and "reporting status changes" are ignored.

Solution: Three layers of protection (task-level immediate write → Session-end checkpoint → Cron fallback).

Pattern 2: Implicit Assumption Failure (Pitfalls #5, #8, #9, #13, #16)

Essence: The code or process is based on an implicit assumption ("config warning = failure", "date format is consistent", "target file exists", "C library is in the search path", "JSONL format remains unchanged"), and this assumption does not hold in certain cases.

Solution: Defensive programming, always validate assumptions, always have a fallback.

Pattern 3: Shared Resource Conflict (Pitfalls #11, #12)

Essence: Two independent processes/operations share the same resource (marker, file), and neither is aware of the other's existence.

Solution: Namespace isolation. Each cron job has its own marker. write = overwrite, append = cat >>.

Pattern 4: Single Point of Failure (Pitfalls #10, #14, #15)

Essence: Reliance on a single data source or a single API, and when that source fails, the system fails completely.

Solution: Multiple engines in parallel + degradation plan. Never trust a single source.

Pattern 5: Confirmation Bias (Pitfall #14)

Essence: Once a preliminary conclusion is formed, subsequent searches only look for evidence supporting that conclusion and ignore counterevidence.

Solution: Anti-Rationalization enforces reverse verification + Gate 0 cannot be skipped.

IV. Overview of Improvement Mechanisms

Systematic improvements born from these pitfalls:

Improvement	Triggering Pitfall(s)	Details
Three-layer memory protection	#2, #11, #12, #16	Task-level write → end-of-session checkpoint → Cron fallback
Mandatory CLI deployment rule	#4	`npx vercel --prod --yes`; deployment via GitHub is permanently prohibited
Mandatory dual write (file + vector)	#2, #16	Writing files must simultaneously mem_save to openclaw_mem
Cron namespace isolation	#11	Each cron job uses its own marker; sharing is prohibited
Appended log protection	#12	Prohibit the write tool; enforce exec cat >>; cp backup before writing
Time zone three-date matching	#8	HKT today + UTC today + UTC yesterday
JSONL dual-format compatibility	#16	v2 priority + v1 fallback + Sanity Check
DI three-tier fallback query	#15	Direct connection → Tavily cache → annual report
AK-SDD Gate 0 red line	#14	≥1 real-time quote + Tavily snippet not directly cited
Anti-Rationalization	#14	Mandatory reverse verification; confirmation bias protection
Verify before concluding	#5	Check session files first, then check config
File system over API	#6, #10	Read the file system directly across channels

V. Quantitative Summary

10-day time span: 5/7 → 5/17
16 pitfalls
├── 🔴🔴🔴 Fatal: 5 (31%)
├── 🔴🔴 High: 6 (38%)
└── 🔴 Medium: 5 (31%)

Categories:
├── Memory system: 8 (50%) ← most vulnerable
├── Deployment infrastructure: 3 (19%)
├── Data analysis: 3 (19%)
└── Tool selection: 1 (6%)

Root cause patterns:
├── Meta-Task amnesia: 2
├── Implicit assumption failure: 5
├── Shared resource conflict: 2
├── Single point of failure: 3
└── Confirmation bias: 1

Systemic improvements that emerged: 12 mandatory rules

Conclusion

These 10 days were a critical transition period for UltraClaw as it evolved from a "conversational tool" into a "system-level AI assistant." No pitfall was a waste. Each pitfall gave rise to a permanent rule, and each lesson reinforced a layer of defense.

The three most important meta-lessons:

Documentation is greater than the brain. Anything done but not written down is as if it never happened.
Defense in depth is greater than a perfect single point. Always assume any link may fail.
The boss's intuition is the highest authority. When data and analysis conflict with the boss's judgment, question the data first.

This is not the end. Every future day, new pitfalls will be waiting. The point is not to avoid mistakes, but to make each mistake harder to repeat than the last.

Date written: 2026-05-17 Data source: vector memory system openclaw_mem (1,160+ memories) + memory/lessons/ + memory/daily/ Tool: UltraClaw @ DeepSeek v4-pro