lynxlangya/techne/anchor-viz

anchor-viz

Investigate by diagramming. The diagram is the byproduct; the value is forcing real investigation before drawing.

Forced Procedure

1. Route the request. Choose one diagramKind from the table below. If the

user's intent fits multiple kinds, ask one short clarification instead of guessing.

1. 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.

1. 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, or non-code. For other kinds, state the bounded scope and the files that prove it.

1. 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.

1. 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.

1. 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.

1. Enforce complexity gates. Keep architecture at 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.

1. 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 verified techne:source; relationship-like elements need file+symbol proof unless explicitly inferred with sourced endpoints. Use actor for 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.

1. 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

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.