Brainstorm Diagrams

Use this skill to create structured thinking diagrams for brainstorming, root-cause analysis, product design, process design, and solution exploration.

Version 1 supports only diagram_type="fishbone", generates editable SVG output, can export work SVGs to PNG for sharing, and supports Codex-assisted fishbone drafts from natural-language source text. For non-technical users, prefer the double-click launcher after the draft structure exists:

鱼骨图工具.cmd

English fallback:

fishbone_tool.cmd

Command-line usage is also available:

& "C:\Users\gon56956\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" scripts\new_fishbone.py my-analysis --format md

This creates a user-owned input and initial SVG under work/fishbone/. To render an existing input directly, use scripts/generate_diagram.py.
Work names must be safe file stems: lowercase letters, numbers, hyphen, and underscore only, such as my-analysis or customer_complaints_v1.

After editing a work/fishbone/ input, regenerate it with:

& "C:\Users\gon56956\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" scripts\render_work.py my-analysis

Export a generated work SVG to PNG with:

& "C:\Users\gon56956\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" scripts\export_png.py my-analysis

PNG export is intended for SVGs generated by this fishbone renderer, not arbitrary third-party SVG files.

Fishbone category badges use confirmed semantic mappings from a curated Lucide SVG candidate library in assets/lucide-candidates/. The renderer should only map categories to Lucide badges when the category meaning is confirmed; keep extra Lucide files as future candidates, not automatic mappings.

Regenerate the badge review board with:

& "C:\Users\gon56956\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" scripts\render_lucide_candidate_catalog.py

Run the maintained testcase, template, and layout checks after renderer changes:

& "C:\Users\gon56956\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" scripts\verify_testcases.py

For manual visual review after dense-layout changes, regenerate stresscases:

& "C:\Users\gon56956\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" scripts\render_stresscases.py

To protect the optional stresscase structure:

& "C:\Users\gon56956\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" scripts\verify_stresscases.py

To protect natural-language extraction examples:

& "C:\Users\gon56956\.cache\codex-runtimes\codex-primary-runtime\dependencies\python\python.exe" scripts\verify_naturalcases.py

Inputs

Prefer JSON for automation and structured Markdown for user-authored briefs.

• JSON: follows the shared fishbone model described in references/input_contract.md.
• Markdown: use # for the topic, ## for categories, and bullet lists for cause items.
• Markdown subcategories: a primary bullet with indented bullets becomes a subcategory with child causes.
• Starting templates live in templates/; copy them before authoring a new diagram.
• Natural-language source text: Codex must first extract a structured Markdown draft using references/natural_language_extraction.md and references/natural_language_prompt_template.md; do not pass raw .txt directly to scripts/generate_diagram.py for semantic extraction.

Workflow

1. For structured Markdown/JSON, normalize the user input into the fishbone data model.
2. For natural-language source text, first extract or confirm topic, domain-specific categories, and primary items using references/natural_language_extraction.md; use references/natural_language_prompt_template.md as the execution template when drafting from raw text.
3. For a new blank/template diagram, run scripts/new_fishbone.py <name> --format md or --format json.
4. For a Codex-assisted natural-language fishbone draft, write the extracted Markdown to work/fishbone/<name>.md; use safe file stems only.
5. Render a work input with scripts/render_work.py <name>; if both Markdown and JSON inputs exist for the same name, pass --format md or --format json.
6. Optionally run scripts/export_png.py <name> when the user needs a PNG for quick sharing.
7. Read the printed Diagnostics: block for defaults, truncation, ignored nesting, and compatibility notices.
8. Check the generated SVG for readability and adherence to references/visual_style_contract.md.
9. For natural-language fishbone drafts, review semantic quality with references/natural_language_review_checklist.md; use naturalcases/fishbone/ as examples, not as generated output storage.
10. For naturalcase edits, run scripts/verify_naturalcases.py.
11. For renderer, badge, testcase, template, work-entrypoint, extraction-doc, or export edits, run scripts/verify_testcases.py before finishing.
12. For dense layout changes, also run scripts/render_stresscases.py, run scripts/verify_stresscases.py, and inspect stresscases/fishbone/full-stress.svg by eye using references/visual_review_checklist.md.

Layout Rules

• Keep the topic block as a rounded SVG <rect> with id="topic-block".
• Render ordinary primary causes as short secondary bones: anchor circle on the main branch, short horizontal connector, then text.
• Draw connector lines before anchor circles so the white-filled circles mask lines inside the circle.
• Render subcategories as anchor circle, horizontal connector, text-only card, outside curly brace, and child bullets.
• Right-side subcategory children use a { brace; left-side children use a } brace.
• Keep branch length density tiers ordered as sparse primary causes < standard primary causes < subcategory branches.
• Preserve the current compact branch length base tiers unless intentionally changing layout tests: 180 / 230 / 270.
• Allow dense subcategory branches to expand beyond the base tier when actual row heights require it.
• Keep sparse diagrams at the base 1920x1080 canvas, but automatically expand the SVG canvas for dense content instead of shrinking fonts, cards, or line widths.
• When the canvas expands, keep the topic block on the right side of the dynamic canvas and keep the spine, chevrons, and category anchors aligned to the dynamic spine center.
• Keep cause rows centered within the vertical segment between the spine and the category card edge.
• Space cause rows by actual visual height so subcategories with child bullets do not overlap neighboring rows.
• Plan top/bottom category placement by content load, while preserving input-relative order within each half.
• Keep every category internally left/right alternating, including subcategory entries.
• Place categories horizontally by estimated left/right footprint instead of simple equal spacing.
• Use testcases/fishbone/fishbone.five-primary.* and testcases/fishbone/fishbone.five-subcategories.* as stress tests for the densest supported category content.
• Use stresscases/fishbone/full-stress.* as an optional manual visual stresscase; it is deliberately denser than normal regression testcases.
• Use naturalcases/fishbone/*.source.txt and naturalcases/fishbone/*.expected.md as semantic extraction examples; do not place generated SVG/PNG files there.
• Keep templates/fishbone.template.* parseable and structurally complete; scripts/verify_testcases.py protects them from accidental deletion or malformed edits.
• Keep assets/lucide-candidates/ as the reusable Lucide badge library. scripts/verify_testcases.py protects required mapped icons and verifies the candidate catalog can still render.
• Keep user-authored fishbone files in work/fishbone/; do not mix them into testcases/fishbone/, templates/, stresscases/fishbone/, or naturalcases/fishbone/.

Current Limits

• Only fishbone is implemented.
• Each main category renders up to five primary entries; each subcategory renders up to three child causes.
• Natural-language extraction is a Codex skill workflow, not an offline local script or .cmd menu feature.
• Redrawing existing fishbone files or whiteboard photos is planned but not implemented.