Skill v1.0.0
currentAutomated scan100/100version: "1.0.0"
code-relationship-mapper
Purpose
Create a complete, agent-friendly understanding of a selected code project by:
- Reading all source code files in scope.
- Mapping relationships between modules, classes, functions, and data flow.
- Producing layered Markdown documentation.
- Capturing function-level call and return behavior for every function in scope.
When To Use
Use this skill when user asks for:
- full codebase analysis
- code relationship mapping
- call graph and dependency graph
- architecture understanding docs
- function-level caller/callee/return tracing
Required Outcomes
This skill MUST produce documentation that is:
- complete for the selected scope
- precise down to each function's calls and returns
- structured for fast agent reading
- linkable with stable IDs and relative links
Scope Rules
Before analysis, define scope explicitly:
project_root: root folder to analyzeinclude_patterns: source file globsexclude_patterns: vendor/build/cache/generated pathslanguage_set: detected or user-specified languages
If user does not specify, default include:
**/*.py,**/*.js,**/*.ts,**/*.tsx,**/*.jsx,**/*.java,**/*.go,**/*.rs,**/*.cs,**/*.cpp,**/*.c,**/*.h,**/*.hpp,**/*.php,**/*.rb,**/*.swift,**/*.kt
Default exclude:
**/node_modules/**,**/.git/**,**/dist/**,**/build/**,**/out/**,**/.next/**,**/target/**,**/__pycache__/**,**/coverage/**,**/vendor/**,**/*.min.*
Output Location
Write documentation to:
docs/code-map/
If folder does not exist, create it.
Output Files (Layered)
Generate these files in order:
docs/code-map/00-overview.mddocs/code-map/01-module-map.mddocs/code-map/02-dependency-map.mddocs/code-map/03-call-graph.mddocs/code-map/04-function-index.mddocs/code-map/05-dataflow-return-map.mddocs/code-map/06-entrypoints-and-routes.mddocs/code-map/07-external-interfaces.mddocs/code-map/08-hotspots-and-risks.mddocs/code-map/99-glossary-and-ids.md
When codebase is large, add per-module detail pages:
docs/code-map/modules/<module-id>.md
Function-Level Precision Standard
For EACH function/method in scope, capture:
- stable function ID
- file path and line
- signature (name, params, return annotation if present)
- direct callers (internal)
- direct callees (internal)
- external/library calls (grouped)
- return behavior:
- return type annotation or inferred shape
- all distinct return paths
- sentinel returns (
null,None, error objects, empty collections) - side effects (I/O, DB, network, file write, global state)
- error behavior (throws/raises/returns error)
- async/concurrency behavior
If exact return type cannot be proven, mark as:
unknown (static inference limited)
Do not fabricate.
Markdown Format Contract
Use compact, scan-friendly Markdown with strict structure.
A. Header Block
Every file starts with:
# <title>Generated: <ISO datetime>Scope: <short scope>Confidence: <high|medium|low>
B. Stable IDs
Use IDs:
- module:
M-<slug> - class:
C-<slug> - function:
F-<slug>
Keep IDs stable across reruns unless path/name changes.
C. Function Record Template
Use this exact block shape in 04-function-index.md and module pages:
## F-<slug> `<function_name>`-Location: `<path>:<line>`-Parent: `<module-or-class-id>`-Signature: `<raw signature>`-Calls: `F-...`, `F-...`-Called by: `F-...`, `F-...`-External calls: `<lib.fn>`, `<lib.fn>`-Returns:-Path A: `<condition>` -> `<value/type>`-Path B: `<condition>` -> `<value/type>`-Side effects: `<none|list>`-Errors: `<none|throws/raises/returns error>`-Async: `<sync|async|mixed>`-Notes: `<brief fact only>`
D. Call Graph Tables
In 03-call-graph.md, include:
- top-down call chains from entrypoints
- fan-in/fan-out table
- cycles (if any)
Table format:
| Function ID | Fan-in | Fan-out | Layer | Notes ||---|---:|---:|---|---|
E. Return Map
In 05-dataflow-return-map.md, include:
- function -> return type/shape summary table
- uncertain inferences grouped separately
- error/exception return channels
Execution Workflow
- Inventory
- enumerate files in scope
- group by module/package
- Symbol extraction
- collect classes/functions/methods/signatures
- Relationship extraction
- imports and dependencies
- caller/callee graph
- Return-path analysis
- enumerate return statements and conditions
- Entrypoint analysis
- CLI, HTTP routes, main functions, workers, schedulers
- Markdown generation
- write required files with stable IDs and links
- Consistency pass
- verify each referenced ID exists
- verify each function appears at least once in index
Quality Gates
Before finalizing, MUST verify:
function_coverage == 100%for in-scope functions- all
CallsandCalled byIDs resolve - all files have generated timestamp and confidence
- no broken relative links
- unknown items explicitly marked (not omitted)
If any gate fails, fix and regenerate affected files.
Fast-Read Optimizations For Agents
Always optimize for machine + human scan:
- short bullets
- consistent field order
- no narrative padding
- no duplicated long prose
- prefer tables and ID links for traversal
- keep each function block concise
Non-Goals
- no runtime profiling unless user requests
- no code changes unless user requests
- no speculative behavior claims without evidence
Minimal Command Checklist
When executing this skill, follow this checklist:
- detect scope
- build symbol map
- build dependency map
- build call graph
- build return map
- write layered Markdown docs
- run consistency gates
- report completion with file list and coverage stats