interactive-code-map

interactive-code-map

Use this skill to create a concise, evidence-backed interactive code map. It produces one HTML file and never opens a browser automatically. Besides a codebase, a described non-code business process can be mapped the same way.

Chinese reading version: SKILL.zh-CN.md. This SKILL.md is the sole executable entry; if the two files differ, this file takes precedence.

Workflow

1. Establish the input boundary. Obtain either a repository directory plus the question to answer, or a described non-code business process plus, when available, a directory of supporting documents. Ask for missing scope; do not infer facts outside the supplied directory or the user's description.
2. Confirm the optional interaction profile before generating. Ask: “Should keyboard operation and small-viewport usability be included in this HTML map’s acceptance scope? (Recommended)” An explicit preference already given by the user counts as confirmation. If the user does not confirm, continue with the map but treat these capabilities as out of scope for this delivery; do not claim or test them as accepted behavior. Do not remove renderer capabilities merely because they are unselected. The generated controls guide shows the primary commands: click a card for details, click a relationship line to pin or unpin its hover-identical highlight, Tab to select, Enter to open or pin, and Esc to close and clear pins; node button semantics also accept Space to open.
3. Choose the CDN delivery profile. Default to global; use china-friendly only when the user explicitly prefers China-mainland delivery or identifies that audience. Treat conversation language as a weak signal, not a location fact. Only use a live speed measurement when the current environment represents the target audience and the user agrees to network probing. Select only a bundled profile; never add arbitrary CDN URLs or bypass SRI. Report the selected profile and rationale.
4. Inspect only within that boundary: code for repository inputs, or the user's supplied documents and statements for business-process inputs. Mark every MapSpec claim as verified, inferred, or unconfirmed.
5. Form a MapSpec. Use mapspec-v1.schema.json as the authoritative structure. Every verified evidence item needs a real relative path and an inspected line range resolved against --repo-root: code lines for repository inputs, or document lines (for example a requirements or process markdown file) for business-process inputs. A statement that comes only from the user's verbal description, with no inspectable file, must be marked inferred or unconfirmed — never verified. Set the optional meta.uiLocale deliberately for each delivered map: use en for the English Demo, and use zh-CN by default when the user is conversing in Chinese (unless they request English output). The fixed renderer UI copy—document language, graph region name, dependency-failure page, reading guide, relationship keys, condition marker, evidence-status caption, and controls guide—must consistently follow this value; never leave a mixed-language legend. Each node must expose its localized claim state with the renderer's small upper-left, legend-matched status dot as well as the border treatment. languageProfile describes the code or business source and does not select UI language. Preserve the supplied language of business node, group, and edge text; only translate business content when the user explicitly asks.
6. Read visual-quality-contract.md before generating or revising a multi-group map. Apply its relationship semantics, routing limits, label placement, locale, and visual-acceptance rules. Do not repair a complex graph by repeatedly layering ad-hoc routing changes; retain Mermaid's node-to-node corridor and make only the documented local adjustments.
7. Validate and generate the artifact. First verify node --version is at least 20. If it is not, report that Node.js 20 or newer is required and retain the MapSpec for the user instead of attempting generation.
8. Report the generated relative HTML path, the evidence-state limits, the confirmed interaction and CDN profiles, and any manual browser verification performed. Do not report browser behavior as verified unless it was actually checked.