---
name: pactkit-visualize
description: "Generate project code dependency graph (Mermaid), supporting file-level, class-level, function-level, and module-level analysis"
model: haiku
---

# PactKit Visualize

Generate project code relationship graphs (Mermaid format), supporting four analysis modes.

> **Script location**: Use the base directory from the skill invocation header to resolve script paths.

## Prerequisites
- The project must have Python source files (`.py`) to generate meaningful graphs
- The `docs/architecture/graphs/` directory is automatically created by `init_arch`

## Command Reference

### visualize -- Generate code dependency graph
```
python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py visualize [--mode file|class|call|module] [--entry <func>] [--focus <module>]
```

| Parameter | Description | Default |
|-----------|-------------|---------|
| `--mode file` | File-level dependency graph (inter-module import relationships) | Default |
| `--mode class` | Class diagram (including inheritance) | - |
| `--mode call` | Function-level call graph | - |
| `--mode module` | Module-level dependency graph with weighted cross-module edges | - |
| `--entry <func>` | BFS transitive chain tracing from specified function (requires `--mode call`) | - |
| `--focus <module>` | Scope scan to a specific module directory. **MUST** be an exact module name from the project (e.g., `pactkit`, `app`), not a keyword or concept. Run without `--focus` first to see available modules. | - |

### init_arch -- Initialize architecture directory
```
python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py init_arch
```
- Creates `docs/architecture/graphs/` and `docs/architecture/governance/`
- Generates placeholder file `system_design.mmd`

### list_rules -- List governance rules
```
python3 ${CLAUDE_PLUGIN_ROOT}/skills/pactkit-visualize/scripts/visualize.py list_rules
```
- Outputs the list of rule files under `docs/architecture/governance/`

## Output Files

| Mode | Output Path | Mermaid Type |
|------|-------------|-------------|
| `--mode file` | `docs/architecture/graphs/code_graph.mmd` | graph TD |
| `--mode class` | `docs/architecture/graphs/class_graph.mmd` | classDiagram |
| `--mode call` | `docs/architecture/graphs/call_graph.mmd` | graph TD |
| `--mode module` | `docs/architecture/graphs/module_graph.mmd` | graph TD |
| `--focus` (file) | `docs/architecture/graphs/focus_file_graph.mmd` | graph TD |
| `--focus` (class) | `docs/architecture/graphs/focus_class_graph.mmd` | classDiagram |
| `--focus` (call) | `docs/architecture/graphs/focus_call_graph.mmd` | graph TD |

## Usage Scenarios
- `project-plan`, `project-act`, and `pactkit-trace` use `pactkit query --json --explain` for analysis.
- Use `visualize` only to explicitly regenerate derived Mermaid projections.
- `pactkit-doctor` checks graph-provider health and derived graph status.

## Graph Query Protocol

> **MUST NOT `Read` a full `.mmd` graph file** — graph files are large (50K–120K, 1000–2000+ lines). Full reads waste tokens before any work begins.

### Unified Query Router

```bash
pactkit query --callers atomic_write --json --explain
pactkit query --callees deploy --json --explain
pactkit query --chain atomic_write --json --explain
pactkit query --chain deploy --down --json --explain
pactkit query --explore deployer --json --explain
pactkit query --impact deploy --json --explain
```

The router owns Codegraph health, bounded sync, and provider selection. Configured Codegraph fails closed. Only an explicit `--allow-fallback` may select `builtin_graph` and then `text_search`; a healthy empty result never triggers fallback.