anchor-viz
Investigate by diagramming. The diagram is the byproduct; the value is forcing real investigation before drawing.
Forced Procedure
- Route the request. Choose one
diagramKindfrom the table below. If the user's intent fits multiple kinds, ask one short clarification instead of guessing. - Find evidence for that kind. For
architecture, enumerate roots, manifests, workspace/build/native/container/edge/infra/source-only signals. For other kinds, find the bounded entrypoint, schema, state enum, workflow, or module/type namespace before drawing. - Classify shape or scope. For
architecture, state one project shape and cite evidence:single-frontend,single-backend,coupled-fullstack,monorepo,library,native,native+edge,source-only code, ornon-code. For other kinds, state the bounded scope and the files that prove it. - Apply the non-code decision. Never declare non-code only because manifests are absent. First scan roots; then run a bounded source-extension/code-signal scan. If both are absent, or docs/vault signals clearly dominate, do not fabricate a code diagram. Draw the real top-level structure or ask what the user wants.
- Match the user's language. Human-facing diagram text follows the user's primary language: titles, display labels, edge/message labels, shape notes, and short explanations. Keep code-facing identifiers source-native: Mermaid IDs, file paths, symbols, package names, class/function/module names, and established technical terms such as API, SDK, CLI, HTTP, SwiftUI, AppKit, or React.
- Draw only evidenced relationships. Use the evidence contract for the selected kind. Every node, participant, entity, state, type, and edge/message must come from a file read.
- Enforce complexity gates. Keep
architectureat 12-15 top-level nodes by default. For other kinds, use the validator's participant/message, entity/relationship, state/transition, or type/member limits. Split into drill-down diagrams when needed. - Mark provenance. Add render-neutral comments for every element before
storing:
%% techne:source <elementRef> <path>[#<symbol>]or, for relationship-like elements only,%% techne:inferred <relationshipRef> <reason>. Entity-like elements always need verifiedtechne:source; relationship-like elements need file+symbol proof unless explicitly inferred with sourced endpoints. Useactorfor human sequence participants so the actor path-only allowance is mechanically scoped. Solid relationships mean read-from-code. Dashed or labeled relationships mean inference only where the selected Mermaid type supports it. - Emit, validate, store, build viewer, open when interactive. Write Mermaid
source first, validate it, store it with
scripts/store_viz.py, always build the self-contained viewer, and only open it when the session is interactive.
Diagram Routing
| User intent | diagramKind | Mermaid type | Evidence focus |
|---|---|---|---|
| Project architecture, module/service/package topology | architecture | flowchart / graph | Manifests, workspaces, imports, services, bindings, infra edges. |
| Request lifecycle, command/job flow, actor conversation | interaction | sequenceDiagram | Entrypoint, ordered calls/messages, handlers, clients, queues. |
| Tables, entities, persistence relationships | data-model | erDiagram | Schema, migrations, ORM/entity declarations, foreign keys, associations. |
| Status/order/task/review lifecycle | state-model | stateDiagram-v2 / stateDiagram | Status constants, state machines, reducers, guards, transition handlers. |
| Classes, interfaces, structs, protocols, bounded type structure | type-structure | classDiagram | Type declarations, inheritance, implementation, composition, public method groups. |
Examples:
- "map this project" ->
architecture. - "show how login request flows" ->
interaction. - "draw the database relationships" ->
data-model. - "how does order status change" ->
state-model. - "show the public types in this module" ->
type-structure.
Script Usage
- Validate Mermaid and altitude:
node skills/anchor-viz/scripts/validate-mermaid.mjs diagram.md --project /path/to/project --max-nodes 15 - Store a diagram in a target project:
python3 skills/anchor-viz/scripts/store_viz.py --project /path/to/project --name login-flow --title "Login flow" --diagram diagram.md --shape monorepo - Build the self-contained viewer, opening it only when interactive:
python3 skills/anchor-viz/scripts/build_viewer.py --project /path/to/project --open
The validator expects mermaid@11.15.0 and jsdom to be installed in one of
these places: TECHNE_VIZ_NODE_MODULES, skills/anchor-viz/scripts/node_modules, the
current working directory, or an ancestor directory.
Stop Conditions
- Stop and ask if you cannot inspect the project files.
- Stop and ask if the requested diagram kind is ambiguous.
- Stop before drawing unsupported architecture for a non-code project.
- Stop before drawing a non-architecture diagram without a bounded entrypoint, schema, status lifecycle, or module/type scope.
- Stop before storing a diagram that fails syntax validation, provenance validation, or a complexity gate.
- Do not create
.techne/content inside this repository while authoring the skill itself.
