Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 35 additions & 13 deletions .agents/skills/phantom/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,21 @@ description: >
`phantom.nu` beside this file. Needs `nu` and `phantom-fractal` on `PATH`,
or `$PHANTOM_FRACTAL_BIN` naming the binary. Run it from the indexed tree
or pass `--repo PATH`. Every command prints one line,
`{ ok, command, data, meta }` or `{ ok: false, command, error, kind, stderr, exit }`,
`{ ok, command, data, meta, exit: 0 }` or `{ ok: false, command, error, kind, stderr, exit }`,
and exits with that `exit`. `meta.stale: true` means the answer comes from
the last index pass; say so.

The envelope is one JSON line; if your harness cuts long lines, raise its
output width or pipe through `jq -c .data`.

Which command for which question:

```bash
nu phantom.nu help # this table as an envelope; --help and -h print it too
nu phantom.nu where NAME # where is X: file:line, kind, signature; methods included; every candidate of a bare name
nu phantom.nu callers NAME [--limit N] # who calls X: distinct callers as file::Type::name, their sites, their files
nu phantom.nu callees NAME [--limit N] # what X calls, grouped the same way, and how many calls were unresolved
nu phantom.nu impact NAME [--depth 1..5] [--no-tests] # what breaks if I change X: callers by depth, tests apart, risk, reasons
nu phantom.nu impact NAME [--depth 1..5] [--limit N] [--no-tests] # what breaks if I change X: callers by depth, tests apart, risk, reasons
nu phantom.nu diff-impact [--against REF] # what my uncommitted change reaches
nu phantom.nu path FROM TO # how does A reach B
nu phantom.nu cochange FILE [--limit N] # what changes in the same commits as FILE: raw counts over every tracked file, docs and manifests too
Expand All @@ -38,18 +42,36 @@ nu phantom.nu status # is the index current, and what change
nu phantom.nu index [PATH] # writes the index; run only when a human asked
```

Flags: `--repo`, `--limit` and `--depth` may come before or after the
command (`nu phantom.nu --repo PATH callers NAME`). The rest follow the
command. Flags go before `--`; a name or path after `--` is never read as a
flag.

Names: a bare name (`parse`), `Type::method` (`App::watch_dir`),
`module::name` (`app::watch_dir`), or a module path
(`tui::app::App::watch_dir`). On `kind: ambiguous` the envelope carries
`matches`; rerun with one of their names. On `kind: not_found` it may carry
`did_you_mean`, the symbols whose bare name is the last part of yours.
Flags go before `--`; a name or path after `--` is never read as a flag.

Trust: `callers`, `callees` and `impact` follow resolved calls only. Read
`min_confidence` and `reasons`; a missing caller is unknown, not absent. A
caller reached only through a re-export or a macro may be missing, so when
the answer must be complete (a signature change), confirm with one grep of
the bare name and compare counts. `cochange` is history, not dependency.
`module::name` (`app::watch_dir`), a module path
(`tui::app::App::watch_dir`), or a `display` from any reply
(`src/tui/app.rs::App::watch_dir`, or `where`'s
`src/tui/app.rs:40 App::watch_dir`). Use `where NAME` first when a
`Type::method` may exist in more than one crate, then pass its `display`.
On `kind: ambiguous` the envelope carries `matches`; rerun with one of
their `display`s. On `kind: not_found` it may carry `did_you_mean`, the
symbols whose bare name is the last part of yours.

Trust, per kind of question:

- **Where, path and co-change** (`where`, `show`, `path`, `cochange`):
answer from the envelope. Do not re-grep.
- **Callers and impact** (`callers`, `callees`, `impact`, `diff-impact`):
they follow resolved calls only, so a missing caller is unknown, not
absent, and a call made through a macro may be missing; read
`min_confidence` and `reasons`. Confirm with one grep of the bare name
and compare counts. Search further only when the reply sets
`confirm_with_grep: true`: the target is re-exported (`reexported: true`),
so callers through the re-export may be missing.
- **Tests and orientation** (`impact`'s `tests`, `map`, `rank`, `status`):
at most one confirming read.

`cochange` is history, not dependency.
Without a flag (or with `--count`) it counts, for every tracked file, the
non-merge commits shared with FILE in the scanned window: no decay, no
lift floor, and commits touching more than `scope.bulk_skip` files are
Expand Down
177 changes: 144 additions & 33 deletions .agents/skills/phantom/phantom.nu

Large diffs are not rendered by default.

48 changes: 35 additions & 13 deletions .claude/skills/phantom/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,17 +16,21 @@ description: >
`phantom.nu` beside this file. Needs `nu` and `phantom-fractal` on `PATH`,
or `$PHANTOM_FRACTAL_BIN` naming the binary. Run it from the indexed tree
or pass `--repo PATH`. Every command prints one line,
`{ ok, command, data, meta }` or `{ ok: false, command, error, kind, stderr, exit }`,
`{ ok, command, data, meta, exit: 0 }` or `{ ok: false, command, error, kind, stderr, exit }`,
and exits with that `exit`. `meta.stale: true` means the answer comes from
the last index pass; say so.

The envelope is one JSON line; if your harness cuts long lines, raise its
output width or pipe through `jq -c .data`.

Which command for which question:

```bash
nu phantom.nu help # this table as an envelope; --help and -h print it too
nu phantom.nu where NAME # where is X: file:line, kind, signature; methods included; every candidate of a bare name
nu phantom.nu callers NAME [--limit N] # who calls X: distinct callers as file::Type::name, their sites, their files
nu phantom.nu callees NAME [--limit N] # what X calls, grouped the same way, and how many calls were unresolved
nu phantom.nu impact NAME [--depth 1..5] [--no-tests] # what breaks if I change X: callers by depth, tests apart, risk, reasons
nu phantom.nu impact NAME [--depth 1..5] [--limit N] [--no-tests] # what breaks if I change X: callers by depth, tests apart, risk, reasons
nu phantom.nu diff-impact [--against REF] # what my uncommitted change reaches
nu phantom.nu path FROM TO # how does A reach B
nu phantom.nu cochange FILE [--limit N] # what changes in the same commits as FILE: raw counts over every tracked file, docs and manifests too
Expand All @@ -38,18 +42,36 @@ nu phantom.nu status # is the index current, and what change
nu phantom.nu index [PATH] # writes the index; run only when a human asked
```

Flags: `--repo`, `--limit` and `--depth` may come before or after the
command (`nu phantom.nu --repo PATH callers NAME`). The rest follow the
command. Flags go before `--`; a name or path after `--` is never read as a
flag.

Names: a bare name (`parse`), `Type::method` (`App::watch_dir`),
`module::name` (`app::watch_dir`), or a module path
(`tui::app::App::watch_dir`). On `kind: ambiguous` the envelope carries
`matches`; rerun with one of their names. On `kind: not_found` it may carry
`did_you_mean`, the symbols whose bare name is the last part of yours.
Flags go before `--`; a name or path after `--` is never read as a flag.

Trust: `callers`, `callees` and `impact` follow resolved calls only. Read
`min_confidence` and `reasons`; a missing caller is unknown, not absent. A
caller reached only through a re-export or a macro may be missing, so when
the answer must be complete (a signature change), confirm with one grep of
the bare name and compare counts. `cochange` is history, not dependency.
`module::name` (`app::watch_dir`), a module path
(`tui::app::App::watch_dir`), or a `display` from any reply
(`src/tui/app.rs::App::watch_dir`, or `where`'s
`src/tui/app.rs:40 App::watch_dir`). Use `where NAME` first when a
`Type::method` may exist in more than one crate, then pass its `display`.
On `kind: ambiguous` the envelope carries `matches`; rerun with one of
their `display`s. On `kind: not_found` it may carry `did_you_mean`, the
symbols whose bare name is the last part of yours.

Trust, per kind of question:

- **Where, path and co-change** (`where`, `show`, `path`, `cochange`):
answer from the envelope. Do not re-grep.
- **Callers and impact** (`callers`, `callees`, `impact`, `diff-impact`):
they follow resolved calls only, so a missing caller is unknown, not
absent, and a call made through a macro may be missing; read
`min_confidence` and `reasons`. Confirm with one grep of the bare name
and compare counts. Search further only when the reply sets
`confirm_with_grep: true`: the target is re-exported (`reexported: true`),
so callers through the re-export may be missing.
- **Tests and orientation** (`impact`'s `tests`, `map`, `rank`, `status`):
at most one confirming read.

`cochange` is history, not dependency.
Without a flag (or with `--count`) it counts, for every tracked file, the
non-merge commits shared with FILE in the scanned window: no decay, no
lift floor, and commits touching more than `scope.bulk_skip` files are
Expand Down
Loading
Loading