---
name: nyne-analyze
description: >
  This skill should be used when the user asks to "find callers", "check references",
  "what calls this", "who uses this", "check diagnostics", "find errors",
  "understand impact", "check blast radius", "find dependencies",
  "git blame", "who changed this", "commit history for a function", or needs to understand
  code relationships in a nyne-mounted codebase. Provides LSP intelligence, impact analysis,
  diagnostics, and per-symbol git history through virtual files. Auto-triggers when reading
  `CALLERS.md`, `REFERENCES.md`, `IMPACT.md`, `DIAGNOSTICS.md`, `DEPS.md`, or
  `git/LOG.md` paths.
disable-model-invocation: true
---

{% import "macros/paths" as paths %}

# nyne-analyze — LSP Intelligence, Impact & Diagnostics

Every symbol in a nyne mount exposes rich LSP intelligence and git history as virtual
files. Read them to understand code relationships, assess blast radius before changes,
and check diagnostics — all without running build commands or grepping for patterns.

## MANDATORY: Pre-Modification Checklist

**Before modifying any function, method, struct, or trait — read these files FIRST:**

1. **`{{ FILE_CALLERS }}`** — `cat {{ paths.sym_md("file." ~ ext, "Foo", "CALLERS") }}`
   Shows all callers with **inline code context** (the actual call expression + surrounding lines).
   One read replaces N grep + file read cycles.

2. **`{{ FILE_DEPS }}`** — `cat {{ paths.sym_md("file." ~ ext, "Foo", "DEPS") }}`
   Shows what this function calls — understand internal dependencies before refactoring.

3. **`{{ FILE_REFERENCES }}`** — `cat {{ paths.sym_md("file." ~ ext, "Foo", "REFERENCES") }}`
   Every place `Foo` is referenced — uses, type annotations, trait bounds, etc.
   Essential before renaming or deleting.

**Do not skip this.** Understanding blast radius before making changes prevents cascading fixes.

{% include "shared/vfs-full" %}

## Symlink Traversal — Edit Through the Graph

Callers, deps, and references are **symlinks to other symbols' `@/` directories**.
Follow them to read, edit, or inspect actions without resolving file paths:

```sh
# List callers as traversable symlinks
ls file.{{ ext }}@/symbols/process@/callers/
# init-main.{{ ext }}:15 → main.{{ ext }}@/symbols/init@/
# start-server.{{ ext }}:42 → server.{{ ext }}@/symbols/start@/

# Read a caller's body directly through the symlink
cat file.{{ ext }}@/symbols/process@/callers/init.{{ ext }}
# → reads main.{{ ext }}@/symbols/init@/body.{{ ext }}

# Edit a caller directly — no need to know which file it lives in
Edit file.{{ ext }}@/symbols/process@/callers/init.{{ ext }}

# Check what code actions are available on a caller
ls file.{{ ext }}@/symbols/process@/callers/init/actions/

# Follow the chain: Foo → callers → bar → deps → baz
cat file.{{ ext }}@/symbols/Foo@/callers/bar/deps/baz.{{ ext }}
```

This enables powerful workflows: find who calls a function → edit the caller → check the caller's
actions → apply a fix — all without ever resolving a file path manually.

## Diagnostics

### File-level diagnostics

```sh
cat {{ paths.file_diagnostics("file." ~ ext) }}                   # all diagnostics for this file
```

**Use this instead of running build commands.** After VFS writes, diagnostics are collected
before the write returns. Read `DIAGNOSTICS.md` for instant feedback — no `cargo check` needed.

### Per-symbol code actions

```sh
ls {{ paths.sym_actions("file." ~ ext, "Foo") }}             # LSP code actions scoped to this symbol
cat {{ paths.sym_action("file." ~ ext, "Foo", "10-add-missing-fields") }}   # preview
rm {{ paths.sym_action("file." ~ ext, "Foo", "10-add-missing-fields") }}    # apply
```

Code actions are `.diff` files — inspect with `cat`, apply by `rm` (delete = apply).
**After a write causes errors**, always check `actions/` — the LSP may already have an auto-fix.

## Per-Symbol Git History

```sh
cat file.{{ ext }}@/symbols/Foo@/git/LOG.md         # commits touching Foo's line range
cat file.{{ ext }}@/symbols/Foo@/git/BLAME.md       # per-line authorship within Foo
cat file.{{ ext }}@/symbols/Foo@/git/BLAME.md:5-10  # blame for lines 5-10 within Foo
```

Only shows commits that actually modified this symbol — not the entire file history.

### File-level git

```sh
cat file.{{ ext }}@/git/LOG.md                       # file commit log
cat file.{{ ext }}@/git/LOG.md:-10                   # last 10 commits
cat file.{{ ext }}@/git/BLAME.md                     # full file blame
cat file.{{ ext }}@/git/CONTRIBUTORS.md             # contributors ranked by ownership
cat file.{{ ext }}@/diff/HEAD.diff                  # uncommitted changes
```

## Analysis-Specific Anti-Patterns

| Anti-pattern | Correct approach |
|-|-|
| `Grep "fn foo" src/` to find callers | `cat {{ paths.sym_md("file." ~ ext, "foo", "CALLERS") }}` — one read, with code context |
| `Grep "Foo" src/` to find references | `cat {{ paths.sym_md("file." ~ ext, "Foo", "REFERENCES") }}` |
| `cargo check` after every edit | `cat {{ paths.file_diagnostics("file." ~ ext) }}` — instant, scoped |
| Reading N files to understand call sites | `{{ FILE_CALLERS }}` has inline code context for all sites |
| Manually resolving which file a caller is in | Follow symlinks: `callers/bar.{{ ext }}` → reads body directly |

## Additional Resources

### Reference Files

- **`references/lsp-features.md`** — Complete LSP feature matrix: which languages support which features, fallback behavior
- **`references/git-integration.md`** — Advanced git patterns: cross-branch diffs, history navigation, co-change analysis