Improve complex mechanical/illustrative diagram quality

[GeneralJerel]

Summary

• Adds mechanical-illustration-skill.txt with guidance for recognizable mechanical diagrams
• Adds svg-shape-library.txt with geometric primitive recipes for common objects
• Expands illustrative diagram section in svg-diagram-skill.txt with composition rules and planning protocol
• Adds master-agent-playbook.txt with centralized state-and-render pattern for interactive diagrams
• All changes are prompt/skill files only — no runtime code changes

Test plan

• Run pnpm dev and open http://localhost:3000
• Ask 'how do cars work?' and verify improved diagram quality
• Ask 'how do airplanes fly?' and verify proper composition
• Compare against same prompts on main branch

[GeneralJerel]

Self-Review Findings

Verdict: No merge block — P0=0, P1=2, P2=4, P3=2

ID	Sev	Category	Location	Issue
F1	P1	correctness	.github/ISSUE_PROPOSAL_mechanical_diagrams.md:15-20	Issue proposal references ./assets/car-diagram-screenshot.png and ./assets/airplane-diagram-screenshot.png but .github/assets/ directory does not exist. Broken images in rendered markdown.
F2	P1	design	apps/agent/skills/ (all new files)	Adds ~9,150 tokens (75% increase) to the system prompt on every request. load_all_skills() concatenates ALL .txt files unconditionally — mechanical diagram guidance is injected even for non-mechanical queries. Consider conditional loading or trimming the shape library to 6-8 common shapes (as the issue proposal itself suggests).
F3	P2	duplication	apps/agent/skills/ + apps/mcp/skills/	All 4 modified/new files are exact byte-for-byte copies across agent and MCP directories. No mechanism prevents drift — edits to one must be manually replicated. Consider symlinks or a CI check.
F4	P2	duplication	mechanical-illustration-skill.txt + svg-diagram-skill.txt	Significant conceptual overlap: both now cover shape construction rules, 3-tier annotation hierarchy, sub-diagram standards, force arrow conventions, and composition zones. The mechanical skill repeats guidance already in the expanded svg-diagram-skill with fuller examples. Suggest keeping architectural rules in one file and domain-specific examples in the other.
F5	P2	duplication	master-agent-playbook.txt + mechanical-illustration-skill.txt	The progressive rendering / updateState → render() pattern appears in both files with nearly identical code examples. Suggest removing the "Interactive Control Binding" section from the mechanical skill and referencing the playbook instead.
F6	P2	scope	.github/ISSUE_PROPOSAL_mechanical_diagrams.md	The issue proposal describes 5 separate PRs but this single PR implements all 5. The proposal is a stale artifact on merge. Should be a GitHub Issue (closeable) or removed.
F7	P3	style	svg-shape-library.txt	Several SVG shapes use hardcoded color values (#444, #ddd, #bbb, #999) that don't match the design token palette in svg-diagram-skill.txt (#F1EFE8, #5F5E5A, etc.).
F8	P3	content	mechanical-illustration-skill.txt:516-544	"Worked Reference: Car Drivetrain Composition" is a text outline only — no actual SVG. Meanwhile the shape library has full SVG for the sedan. Should cross-reference or include complete SVG.

Context Budget Impact

• Pre-PR skill text: ~48.9 KB (~12,200 tokens)
• Post-PR skill text: ~85.5 KB (~21,400 tokens)
• Delta: +36.6 KB (~9,150 tokens) loaded on every request

Testing Gaps

• No automated way to verify prompt/skill quality
• No before/after comparison of diagram outputs in the PR
• No test that validates total system prompt stays within a token budget
• No test that agent/MCP skill files remain in sync

---

Self-review by Claude Code