# Code Flow Map > Analyze and document the flow of a code feature, generating a markdown file and an interactive HTML page with flow diagrams and function reference tables. - Skill: `plearaj/code-flow-map` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add plearaj/code-flow-map` - Raw SKILL.md: https://api.skillmd.com/api/skills/plearaj/code-flow-map/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: plearaj (https://skillmd.com/u/plearaj) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/plearaj/code-flow-map --- ## Code Flow — Documentation Generator Analyze the codebase and generate flow documentation for the requested functionality. ### Before you write anything Name the flow you are about to map and wait for the user to confirm it, unless their own request already named it. This skill writes files under `Code_Flows/` and adds docstrings to source files that lack them. Some hosts start a skill because a conversation drifted near its description rather than because anyone asked for it, and on those hosts this paragraph is the only thing standing between that drift and an edit to the user's code. ### User Input The user's request says what to map, and may carry five option flags — `--whole-code-base`, `--detail thin|standard|verbose`, `--output files|bundle|both`, `--frontend auto|react|vue|angular|svelte|off` and `--tracer auto|on|off`. Step 1 reads them. ### Instructions #### 1. Identify the Target Flow The user's request says what to document. Read it first for its option flags. They are options, not part of the feature name — strip them out before you derive any filename from what is left. - `--whole-code-base` — map the whole repository instead of one feature. If it is present, skip the rest of this section and everything through step 7, and follow **Whole-Codebase Mode** at the end of this document instead. - `--detail thin|standard|verbose` — how much evidence each catalogued function carries. Default `standard`. It only changes anything in whole-codebase mode; if it appears without `--whole-code-base`, accept it silently rather than erroring. If it appears with a value that is not one of those three, tell the user what you read, use `standard`, and carry on. - `--output files|bundle|both` chooses which HTML gets written, default `files`. `files` writes `index.html`, one page per flow, and the quality report page, exactly as before. `both` adds `Code_Flows/code-flow.html`, a single self-contained page carrying every flow. `bundle` writes that page and no other HTML. If its value is not one of those three, say what you read, use `files`, and carry on. **`--output` never suppresses the JSON artifacts** — `index.json`, `.json` and `inventory.json` are written in every mode, because `/code-flow-quality` reads them and a run that skipped them would break it silently. Unlike `--detail`, it changes behavior in both modes: in whole-codebase mode it governs the bundle exactly as it does here — see Whole-Codebase Mode's Pass 1 and Pass 2 for where that applies. - `--frontend auto|react|vue|angular|svelte|off` — whether to map UI components as well as functions. Default `auto`: detect the frameworks this repository actually uses and map their components too. Naming one forces that framework; `off` maps functions only. **Frontend Component Mapping** below says what it changes. If its value is not one of those, say what you read, use `auto`, and carry on. - `--tracer auto|on|off` — whether to run the installed static tracers before tracing anything. Default `auto`: run each tracer whose language this repository contains and whose interpreter this machine has, and read source yourself where none applies. `on` means say so and stop when no tracer could run, since a user who asked for a traced map would otherwise get a slower one silently. `off` never runs one. **Automated Tracing** below says what they produce and how far to trust it. If its value is not one of those three, say what you read, use `auto`, and carry on. Everything from here through step 7 is **feature mode**, the default. The remaining input describes the functionality to document. If it is empty, analyze the project structure and suggest 3-5 key flows, then ask the user to pick one. Use the functionality name to derive the output filename. Convert to snake_case (e.g., "user login" → `user_login.md`, "password reset" → `password_reset.md`). #### 2. Discover Relevant Files and Functions Find all code related to the target flow: - Search for relevant files by name pattern - Search for functions, classes, keywords, and entry points related to the flow - Read discovered files to trace the call chain If a tracer ran, start from its output instead of from search: find this flow's entry function in `entryPoints[]` or `functions[]`, then walk `calls[]` transitively to collect the flow. Read the source of every function you collect — the tracer says what calls what, and you are describing what it does — and follow `ambiguousCalls[]` by hand wherever the chain passes through one. Trace the full execution path — follow function calls from entry point through to the final output. Include every function that participates in the flow. #### 3. Document Undocumented Functions For each function in the flow that lacks a docstring: 1. Analyze the function to understand its purpose, parameters, and return value 2. Generate a clear, concise docstring 3. Add the docstring to the function #### 4. Generate the Markdown Documentation Create `Code_Flows/.md` with these sections: **4a. Flow Description** A brief description of the flow's purpose and when/how it is triggered. **4b. Flow Diagram** A MermaidJS flowchart or sequence diagram. Every function in the flow MUST appear as a named node. Example: ```mermaid flowchart TD A[entry_function] --> B[process_data] B --> C[transform] C --> D[output_result] ``` **4c. Function List** A bullet list of ALL function names that appear in the flow diagram. **4d. Function Reference Table** A table with every function's description and exact file location: | Function | Description | File | |----------|-------------|------| | `entry_function` | Entry point that initializes the pipeline | `src/module/main.py:23` | | `process_data` | Validates and preprocesses input data | `src/module/data.py:45` | The **File** column MUST include the file path and line number in `file:line` format. #### 5. Generate the Interactive HTML View By default, **also** produce a self-contained interactive HTML page next to the markdown. It renders the same flow as a browsable graph: pan/zoom, click a node for its description + `file:line` + code snippet, search functions, and highlight a path. The page is a single file with everything inlined — it works by double-clicking, with no internet or build step. **5a. Build the flow-data JSON.** Assemble ONE JSON object describing the same flow you diagrammed in step 4: ```json { "meta": { "feature": "User Login", "slug": "user_login", "description": "", "generated": "", "root": "", "tool": "code-flow" }, "nodes": [ { "id": "src_web_views_login_view", "label": "login_view()", "file": "src/web/views.py", "line": 12, "kind": "entry", "description": "HTTP handler for POST /login.", "snippet": "def login_view(request):\n ..." } ], "edges": [ { "from": "src_web_views_login_view", "to": "src_auth_service_authenticate_user", "kind": "call", "label": "", "back": false } ] } ``` Rules — follow these exactly, or the page will refuse to render: - One node per function in the diagram. **Every `edge.from` and `edge.to` MUST match a node `id`.** - `id` is derived from the node's own `file` and function name, so that the same function always gets the same `id` in every flow and downstream tools can join flow nodes against a function catalog. Derive it exactly like this: **(1)** take the repo-relative `file` path and drop the extension from its **last segment only** — the final `.` in the filename and everything after it, so `src/v2.1/handler.py` → `src/v2.1/handler`, and a filename with no dot loses nothing; **(2)** append `_` followed by the function's **unqualified** name — `authenticate`, never `User.authenticate` — which is the same name a function catalog records for it; **(3)** lowercase the whole string, replace every remaining character outside `[a-z0-9_]` (path separators, dots, dashes, spaces, anything else) with `_`, collapse each run of `_` into a single `_`, and trim any leading or trailing `_`. Example: `src/web/views.py` + `login_view` → `src_web_views_login_view`. If **the file itself** derives that same id for more than one function — same-named methods on two classes, an overload, or *two different names that slug to one string*, which is what `__add__` and `add`, a `Builder` constructor and its `builder()` factory, or `~Widget` and `Widget` all do — append `_l` and the line number of each one's own definition keyword — the `def`, `function`, `func` or `fn` line itself, never a decorator, annotation or comment line above it: `src_jobs_worker_run_l31` and `src_jobs_worker_run_l88`. Suffix every one of them, including the first. If two of them are on the **same line**, the line cannot separate them, so append `_` and the position of each among that line's same-id definitions, counting from 1 in source order: `src_ui_panel_x_l7_1`, `src_ui_panel_x_l7_2`. Decide all of that from the file's own contents, never from which nodes happen to be in this flow: an `id` must not change depending on what else you mapped. - Two **different files** can derive the same `id` — `src/service.cpp` and `src/service.hpp`, since the rule drops the extension, or `distutils/_msvccompiler.py` and `distutils/msvccompiler.py`, since the leading `_` becomes a separator and collapses into the one before it. Where that happens, and only for the ids both files actually derived, append `_f` and each file's position among those paths, sorted, counting from 1: `src_service_describe_f1` for `src/service.cpp` and `src_service_describe_f2` for `src/service.hpp`. Leave every other function in both files alone. This is the one part of the rule that looks outside a single file, because the collision is between two of them; it is also rare, so if you are applying it to more than a handful of ids, re-read the paths. - `kind` on a **node** is one of `entry` | `step` | `external` | `io` | `component` (default `step`). `entry` = where the flow starts; `external` = a third-party/library boundary; `io` = a DB/network/file side effect; `component` = a UI component rather than a plain function. This drives node color. - **Exactly one** node MUST have `kind: entry`. If the flow has several plausible roots — two HTTP handlers, say — pick the one the user asked about, make that the `entry`, and mark the others `step`. - `kind` on an **edge** is one of `call` | `async` | `conditional` | `render` (default `call`). `render` is a parent component drawing a child. Set `"back": true` on any edge that closes a loop or recursion (points back to an ancestor) so it is drawn as a routed dashed curve. - All file paths use **forward slashes**, repo-relative. `meta.root` is the absolute project root with forward slashes (used only to build editor links). - `snippet` is optional — a short excerpt (up to ~40 lines). **Inside every `snippet` string, replace each `` would terminate the data block). No trailing commas anywhere. **5b. Fill the template.** Read `.code-flow/viewer.template.html`. Write `Code_Flows/.html` as an **exact copy** of that template with three tokens replaced and nothing else changed. `__FLOW_DATA__` becomes the JSON object from 5a. `__FLOW_INDEX__` becomes the `flows` array as it will stand after step 6b — read `Code_Flows/index.json` now, apply this flow's entry to a copy of its `flows` array, and use that; it drives the page's flow switcher. If `index.json` is missing or does not parse, leave `__FLOW_INDEX__` exactly as you found it: the page then hides the switcher and keeps its link to the index, which is the right behavior for a registry that is not there. `__THEME_CSS__` becomes the contents of `.code-flow/theme.css`, or an empty string if that file does not exist or cannot be read. The page self-validates on load: if the JSON is malformed or an edge points at a missing node, it shows a specific error card instead of a blank page — read it and fix the JSON. **5c. Fallback if the template is missing.** If `.code-flow/viewer.template.html` does not exist (the skill was only partially installed), write this minimal page to `Code_Flows/.html` instead, then tell the user to reinstall `code-flow` for the full interactive viewer: ```html <FEATURE> — Flow

— Flow
``` #### 6. Write the Machine-Readable Artifacts These files are the contract consumed by `code-flow-quality`. They are not optional, and they are not derived by parsing the generated HTML. **6a. The flow sidecar.** Write `Code_Flows/.json` containing exactly the JSON object you built in step 5a — the same `meta`, `nodes`, and `edges`. This is the same data embedded in the HTML page, written as a plain file so downstream tools never have to parse markup. **6b. The index.** Create or update `Code_Flows/index.json`. If it does not exist, create it with this shape. If it does exist, read it, add or replace the entry for this flow in `flows` (matching on `slug`), and write it back — preserving every other entry and any existing `coverage` values you did not compute. If it exists but does not parse as JSON, **stop**: do not overwrite it and do not regenerate it. Report the file path and what is wrong with it to the user, and let them repair or delete it — rewriting the file would silently discard the registry of every flow mapped before this one. ```json { "meta": { "root": "", "generated": "", "mode": "feature", "schema": 1 }, "coverage": { "flowsTraced": 1 }, "flows": [ { "slug": "user_login", "title": "User Login", "file": "user_login.json", "entry": "src_web_views_login_view", "nodes": 9 } ] } ``` - `slug` is the snake_case functionality name. `title` is `meta.feature` from the sidecar's JSON object (step 5a). `file` is the sidecar's filename, relative to `Code_Flows/` — a bare filename, not a path. - `entry` is the `id` of the one node whose `kind` is `entry` — step 5a requires exactly one. - `nodes` is the count of entries in the flow's `nodes` array. - `coverage.flowsTraced` is the length of `flows` after your update. - Set `meta.mode` to `feature` — **unless the file already has `"mode": "whole-code-base"`, in which case leave `meta.mode` and `meta.detail` exactly as you found them.** Whole-codebase mode reuses this step, and rewriting the marker there would leave a whole-repository map claiming to be a single-feature one. **6c. The index page.** `index.json` is the data; `Code_Flows/index.html` is how a person reads it. Read `.code-flow/index.template.html` and write `Code_Flows/index.html` as an **exact copy** of that template with two tokens replaced. `__INDEX_DATA__` becomes the registry object you just wrote in 6b. `__THEME_CSS__` becomes the contents of `.code-flow/theme.css`, or an empty string if that file does not exist or cannot be read. Change nothing else in the template. Inside every string value, replace each `, "flows": [], "report": }`. `__THEME_CSS__` becomes the contents of `.code-flow/theme.css`, or an empty string if that file does not exist or cannot be read — an absent theme is the normal case and is never an error. Inside every string value, replace each `.md`, `.html`, and `.json`, plus `index.json` and `index.html` - If `--output` was `bundle` or `both` and the bundle was written, also report `Code_Flows/code-flow.html` - Report the markdown and HTML paths to the user, name `Code_Flows/index.html` as the page that lists every mapped flow, and mention that the JSON artifacts were updated ## Automated Tracing Reading a repository function by function is what leaves a large map half-finished. The installed tracers do that reading in one pass, and they are the difference between a hundred flows traced in one session and ten. Run them unless `--tracer off`. Nothing below depends on their being there: when no tracer applies, every step still works by reading source, only slower. ### Which tracer, and how `.code-flow/tracers/` holds one tracer per supported language. Run the ones whose language this repository contains: | Language | Command | |---|---| | Python | `python .code-flow/tracers/trace_python.py --root . --detail --out Code_Flows/trace-python.json` | | TypeScript, JavaScript | `node .code-flow/tracers/trace_typescript.mjs --root . --detail --out Code_Flows/trace-typescript.json` | | Rust | `python .code-flow/tracers/trace_rust.py --root . --detail --out Code_Flows/trace-rust.json` | | Java | `python .code-flow/tracers/trace_java.py --root . --detail --out Code_Flows/trace-java.json` | | C, C++, Objective-C, C# | `python .code-flow/tracers/trace_c_family.py --root . --detail --out Code_Flows/trace-c.json` | Pass the `--detail` value the user passed you, so one flag governs snippet size everywhere. A repository written in several of these languages runs several tracers, into one file each; nothing merges them, and everything else here reads them as one catalog. Every tracer but the TypeScript one runs under Python, so a machine with a Python interpreter can trace four of the five. A tracer that is missing, exits non-zero, or needs an interpreter this machine does not have is not an error under `--tracer auto`: say which one did not run and why, and carry on reading source for that language. `.code-flow/tracers/README.md` documents the output in full. What matters here: - `functions[]` — one entry per function, already shaped like an inventory entry: the same `id` rule, and the same `role`, `exported`, `owner`, `overrides`, `loc`, `signature`, `purpose` and `snippet` fields. - `functions[].calls[]` — the call graph. `to` is another function's `id`, and `confidence` is `exact` or `heuristic`. - `entryPoints[]` — where execution enters: routes, CLI commands, jobs, handlers, mounted applications. Each names an `id` and a `kind`. - `components[]` and `routes[]` — the UI half, empty for a language with no UI. - `ambiguousCalls[]` — the calls the tracer refused to guess, with their candidates. `externalCalls[]` — the ones that leave the repository. `limits` — what it cannot see at all. ### How far to trust it A tracer is evidence, not the map. Three rules: 1. **Read the source of anything you describe.** A `purpose` the tracer inferred is where a flow description starts, not what it says. 2. **An `exact` call is a fact; a `heuristic` call is a claim.** Confirm a heuristic edge against the source before you draw it, and drop it when the source disagrees. 3. **What the tracer could not resolve is still there.** `ambiguousCalls` and `limits` name real calls, so a chain that passes through one is unfinished rather than finished. Follow it by reading, and say in your report where you could not. Never present a traced map as complete. Say **catalogued** and **found**, never "all" — a tracer is static analysis, and it sees no more of reflection, dynamic dispatch or configuration-declared routes than search does. ## Frontend Component Mapping A repository with a UI is two graphs, not one. Functions call functions; components render components; the two meet where a handler or a hook calls into the rest of the system. Mapping only the calls leaves the half of the system a user actually touches undocumented. This applies unless `--frontend off`, and only to the frameworks the repository really uses — decided from `package.json` dependencies, then the config files present, then the file extensions on disk. Under `--frontend auto` detect them; when the user named one, use that one and say so if the repository disagrees. ### What a component is, per framework | Framework | A component is | Its children come from | Its inputs are | |---|---|---|---| | React, Preact, Solid | a capitalized function or class that returns markup | the JSX tags in its body, resolved through the file's imports | destructured props, or the props type | | Vue | a `.vue` file, or an options object carrying a `template` | the tags in its `