skill-system-analyst

Skill: System Analyst (Mindmap-Driven)

Using the approach of "first map (global map), then dive (drill down leaf node by leaf node)", generatedetailed, structured, visualizedsystem analysis documents. You do not write it all at once, but like writing a book:decompose → plan → execute chapter by chapter → verify → summarize。

Applicable scenarios

• Taking over an unfamiliar codebase, needing to quickly but not crudely build system understanding
• Architecture review/technical due diligence: focus on boundaries, trade-offs, risks, evolution paths
• Need to produce a shareable analysis report (HTML + Mermaid + mindmap)

Output standards (depth threshold)

Each "chapter" must contain at least:

• Scope and responsibilities: what problem this module solves, and what it does not solve
• Key evidence: down to specific file paths, key functions/classes, key configuration items
• Data/control flow: at least 1 Mermaid diagram (choose one of component diagram/sequence diagram/data flow diagram)
• Key trade-offs: why it is designed this way (trade-offs), and what the alternatives are
• Risk grading: security/reliability/performance/maintainability risks (high/medium/low), with remediation suggestions

Output in Chinese by default (unless the user requests English).

Core rules

1. Must orchestrate: it is forbidden to "write the entire report in one go"; you must use doc-generator.js to append chapter by chapter.
2. Must be traceable: key conclusions must land on "file + entry point + evidence"; vague descriptions are forbidden.
3. Must be visualized: every important chapter must have Mermaid, or explicitly reference nodes of the global mindmap.
4. Must be safe: when displaying code/user input in the output HTML, it must be escaped (e.g. <script>）。

Tool conventions (in Codex CLI)

Prefer reproducible commands to extract evidence:ls、rg -n、sed -n、git log、git blame , etc.

Workflow (systematic execution)

Phase 0: Requirements clarification (ask clearly before starting)

Before starting to scan, first confirm:

• Analysis goal: architecture overview / security audit / performance bottleneck / maintainability / launch risk
• Audience: development/architecture/management (determines terminology density and form of suggestions)
• Output scope: which modules/paths need to be covered, and whether improvement plans and priorities should be included

Phase 1: Cartography (global mapping + planning)

1. Global scan: find entry points (main/server/app), routes, task scheduling, configuration, dependencies, data storage, external integration points.
2. Build mindmap(Markdown list, ≥3 levels): covering Server / DB / Async / View / Security / Config / Observability.
3. Convert the mindmap into an execution plan: map each important leaf node to a "chapter list" (chapter names must be readable and searchable).
4. Initialize session: generate in the project root directory metadata.json, and initialize the session with this skill's generator:
   • Generator path: this skill directory's lib/doc-generator.js(i.e., SKILL.md in the directory where lib/）。
   • command:

     node <skill_dir>/lib/doc-generator.js init metadata.json
     

   • metadata.json must include mindmap_markdown; recommended to include related_files(entry files, key configuration, DB schema, etc.).

Phase 2: Deep Dive Loop (deep dive chapter by chapter, maintaining depth)

Execute on the "chapter list" one by one until key leaf nodes are covered:

1. Select chapter: do only one chapter at a time to avoid context divergence.
2. Targeted evidence collection: read only the file set related to this chapter (expand if necessary), and record "entry/exit/call chain/data structure".
3. Produce chapter JSON: write section.json, fields:
   • heading: chapter title (consistent with the mindmap node)
   • content: HTML string (including escaped code snippets and Mermaid)
4. Append：

   node <skill_dir>/lib/doc-generator.js append <session_id> section.json
   

5. Update progress: each time a chapter is appended, write back the current completion status (which nodes have been covered, which risk points are still missing).

Phase 3: Final Assembly (aggregation + quality verification)

1. Render：

   node <skill_dir>/lib/doc-generator.js render <session_id>
   

2. Quality verification: confirm that the HTML can be opened, Mermaid can be rendered, code and user input have been escaped, and the chapter structure is complete.
3. Delivery summary: provide a 1-page level "system overview + risk list + recommended roadmap (by priority)".

Chapter content template (recommended)

Chapter content should be organized at least according to the following structure (HTML):

• <h3>职责与边界</h3>
• <h3>关键组件与接口</h3>(including file/function evidence)
• <h3>关键流程</h3>（Mermaid）
• <h3>权衡与替代方案</h3>
• <h3>风险与改进建议</h3>(grading + specific action items)