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 is diagram-kind specific: for a flowchart it shows 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); for a sequence diagram it shows click a message or participant for details with single-selection highlight, Tab to select, Enter to open, and Esc to close — relationship pinning does not apply.
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. Choose the diagram kind deliberately and record it in meta.diagramKind (flowchart is the default and needs no field). When the question asks who calls whom, in what order — request/response exchanges, callback and retry loops, protocol handshakes — use sequence: declare participants plus messages (with loop/opt/alt frames, optional activation pairing, and three-state evidence on every participant and message) and never nodes/edges. When the question asks about structure, dependencies, or branching ownership, keep flowchart. When both readings matter, generate two maps from the same evidence rather than mixing kinds. 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. For sequence maps keep the literal-text discipline: every display text (participant.title, message.label, frame.label, branches[].label) is single-line with no \n/\r; message labels and participant titles are encoded by the renderer's sequence encoder, while frame conditions are plain text and must not contain & ; # < > " $ : % — reword or move the fact into a message detail instead. Keep one label at most 40 code points (100 is the hard cap; content moves into detail), and keep one map at most about 30 declared messages (60 hard; above the soft limit prefer splitting by scenario into several maps). Never bypass the validator or hand-concatenate DSL text; activatesTo and deactivatesFrom must not both be true, neither may appear inside frames, and an outer activation may wrap whole frames with linear open-close pairing.
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.