-
Visualizing the wrong entities. Not every entity benefits from a diagram. News digests, single-fact entries, and pure opinion pieces score 0-3 and should be skipped. Always run the scan first.
-
Generating too many elements. The LLM will happily generate 25-node diagrams. That's too dense. Cap at 9 elements (6 layers + 3 projects is plenty). If the entity has more, group them.
-
Excalidraw JSON drift. The LLM will sometimes add label: { text: "..." } (invalid) instead of using the container-binding pattern. The validator catches this. If validation fails, retry with temperature=0.3 and a stricter prompt — the second attempt usually works.
-
Forgetting the shareable link. Excalidraw files are useless without a way to open them. Always upload via the skill's scripts/upload.py (requires cryptography Python package) to get a shareable link.
-
AI cover image text typos. The user explicitly flagged this. The cover image is decorative only. Add a markdown caption on the Mermaid image warning readers. Never put critical information in the AI cover.
-
One commit per entity, not per artifact. Don't commit Excalidraw, then Mermaid, then cover as 3 separate commits. One Phase 2 closeout = one commit. This is the wiki's convention.
-
Lint pre-existing errors. Don't try to fix unrelated lint errors in the same commit. The convention is "0 new errors, not 0 total errors". The skill now distinguishes new vs pre-existing errors automatically.
-
Index.md corruption. When inserting backticks/quotes into entity frontmatter, the patch tool may add |- prefix corruption. Always run sed -i '' 's/^|- /- /' index.md after any index.md patch.
-
Excalidraw text positioning. The skill uses approximate x/y for text elements; Excalidraw recalculates on load based on containerId. The file will look slightly off in raw JSON view but render correctly in the browser. Don't manually adjust text positions after generation.
-
Mermaid graph TB vs flowchart TB. Use flowchart TB for new diagrams — graph is deprecated. The prompt template uses flowchart; if you see graph in output, regenerate.
-
LLM hallucination (critical). LLMs sometimes ignore the actual entity content and produce a generic "central node with branches" diagram with completely wrong labels (verified 2026-06-02: a Sequoia/AGI entity came back as a "Solar System" diagram with Sun+planets). The skill's validate_and_clean function now checks that the LLM's returned title overlaps with the entity's title — at least 2 meaningful terms in common. If not, the skill aborts with a clear error message and the user can re-run with stricter prompt or build by hand.
Implementation detail (in validate_and_clean):
- Strip common stop words from BOTH titles (English and Chinese — STOP list lives in the function)
- Extract remaining meaningful terms (alphanumeric + CJK characters)
- Compute set intersection
- If
len(overlap) < 2 AND len(entity_meaningful) >= 3 → abort
- The threshold of 2 chars is empirical — tested on AGI/Solar (overlap=0, aborts) and 1Password/Securing AI Agents (overlap=4, passes)
-
Template loader bug (fixed 2026-06-02). The prompt template in references/llm-prompt-template.md is wrapped in a fenced code block preceded by a prose line ("This is sent to..."). The original regex r'## The Prompt\n+(```\n)?(.+?)(?=\n## )' extracted only the prose-intro line, not the full prompt. The full prompt was 461 chars instead of 2334. Symptom: the LLM gets a generic "generate a diagram" prompt with no entity content, and returns something completely unrelated. Fix: use a prose-prefix-aware regex that explicitly skips the intro line before matching the fenced block.
How to detect this in a future session: if the script's prompt length comes out under ~1000 chars (it should be 2000+), the template loader is broken. Quick check: python3 -c "from visualize_entity import build_llm_prompt; print(len(build_llm_prompt('test',['t'],'b',1.0)))". Should print ~2300. If it prints ~460, the template loader regressed.
-
Cover image timeout (split-commit pattern). The skill uses a 60s urllib.request.urlopen timeout for the Agnes call. Long prompts (>2000 chars) can exceed this. The skill's generate_cover_image function catches the timeout and prints "Cover generation failed: ..." but the script continues to commit Excalidraw + Mermaid anyway (good — partial work is preserved). The cover image is then generated manually in a follow-up commit.
Established recovery workflow (verified 2026-06-02 on 1password-securing-ai-agents-machine-identities):
- Skill commits Excalidraw + Mermaid in commit #1 (
visualize: <slug> (Excalidraw + Mermaid))
- Cover generation times out, script continues to commit without it
- User runs a separate
python3 -c "urllib curl ..." with a shorter prompt
- Downloads the PNG, saves to
assets/entities/<slug>.png
- Patches a
### 封面图 section into the entity body via patch tool
- Commits as commit #2 (
visualize: <slug> (cover image added))
This results in 2 commits per entity when covers are slow, 1 commit when covers succeed. Both are valid Phase 2 closeouts. Don't try to "fix" this by re-running the whole skill — that would re-generate the Excalidraw and create a diff.
To prevent timeouts proactively: keep the cover prompt under 1500 chars. The skill's build_cover_prompt is verbose by default; trim if the entity is long.
-
Linting interactive prompt blocks automation. The original skill called input("Continue anyway? [y/N] ") when lint failed. In a non-interactive terminal, this crashed with EOFError after the LLM + file work was already done. The skill now classifies errors as "new" vs "pre-existing" automatically and proceeds without prompting. If you see EOFError in logs, the lint-classification logic is broken — patch run_wiki_lint in visualize_entity.py.
