diff --git a/npm/assets/codetrail/SKILL.md b/npm/assets/codetrail/SKILL.md index 59ded19..c9db22e 100644 --- a/npm/assets/codetrail/SKILL.md +++ b/npm/assets/codetrail/SKILL.md @@ -1,13 +1,13 @@ --- name: codetrail -description: Use for low-token CodeTrail CLI lookups: framework routes, symbols, definitions, precise references, and call/caller relationships that plain text search cannot answer cleanly. +description: Use for low-token CodeTrail CLI lookups: framework routes, symbols, definitions, precise references, and call/caller relationships. --- # CodeTrail -Use CodeTrail when you need structured navigation, not for broad repository -exploration. Use normal tools (`rg`, `fd`, host read/editor, `git`) for text, -paths, file reads, and Git workflows. +Use CodeTrail for targeted framework route, symbol, definition, reference, and +call/caller lookups. Use normal tools (`rg`, `fd`, `git`) for broad text, path, +and Git workflows. The CLI defaults to compact text output. Add `--output json` only when another tool must parse the response. Use global `--path ` for roots outside cwd. Keep `--dir` workspace-relative (`.`, `src`, `crates/core`); absolute `--dir` is fallback only. For index archives, use `index pack --archive `. @@ -27,11 +27,11 @@ codetrail call-hierarchy --direction incoming|outgoing --depth 2 --lang 3. Then query call direction: who calls it is `--direction incoming`; what it calls is `--direction outgoing`. Keep `--depth 2` unless there is a clear reason to expand. -4. When implementation evidence is needed, use - `defs`/`symbols --include-code --code-max-lines 8..30` instead of reading a - whole file. +4. For compact code context, use + `defs`/`symbols --include-code --code-max-lines 8..30`. 5. On empty results, dynamic dispatch, macros, trait/interface dispatch, or - generated behavior, switch to `rg` and small source reads immediately. + generated behavior, narrow with `--dir`, `--file-pattern`, exact names, or + `rg` for literal matches. ## Routes First @@ -61,9 +61,9 @@ codetrail call-hierarchy --direction outgoing --depth 2 --lang | Language | Start here | Fallback quickly when | | --- | --- | --- | | Go | Scope by package or file. `codetrail symbols Default --lang go --file-pattern gin.go --limit 5`; `codetrail defs Engine.addRoute --lang go --include-code --code-max-lines 20 --limit 3`; `codetrail call-hierarchy Engine.addRoute --direction incoming --lang go --depth 2 --limit 40`; route tasks start with `routes --framework gin\|chi\|gorilla\|net/http`. | Selector or interface dispatch is the key fact, or generated/test/vendor code pollutes results. | -| Rust | Scope by crate or exact file. `codetrail symbols Config --lang rust --dir crates/core --limit 30`; `codetrail defs run --lang rust --file-pattern crates/core/main.rs --include-code --code-max-lines 25 --limit 3`; `codetrail call-hierarchy search --lang rust --dir crates/core --direction outgoing --depth 2 --limit 40`. | Macros, cfg/features, trait dispatch, or broad names like `run`, `search`, `new` need source confirmation. | -| TypeScript/JavaScript | Always set `--lang typescript` or `--lang javascript` and scope to `src`, `lib`, or a file. Express/NestJS endpoint tasks start with `routes`. CommonJS assignments like `exports.foo = function`, `app.handle = function`, and `res.render = function` are parser-visible; use qualified `symbols res.render` or bare `defs handle`, then `--include-code`. | Dynamic router dispatch, prototype mutation, generated code, or 0-result `refs` decides the answer; use `rg` on the exact property/call. | -| Python | FastAPI/Django endpoint tasks start with `routes`. Otherwise use `symbols`/`defs` with `--lang python --dir ` to locate functions/classes, then shallow `call-hierarchy` only as a lead. | You need precise refs, decorators, monkey patches, dynamic imports, or runtime framework wiring. | +| Rust | Scope by crate or exact file. `codetrail symbols Config --lang rust --dir crates/core --limit 30`; `codetrail defs run --lang rust --file-pattern crates/core/main.rs --include-code --code-max-lines 25 --limit 3`; `codetrail call-hierarchy search --lang rust --dir crates/core --direction outgoing --depth 2 --limit 40`. | Macros, cfg/features, trait dispatch, or broad names like `run`, `search`, `new` require tighter scoping. | +| TypeScript/JavaScript | Always set `--lang typescript` or `--lang javascript` and scope to `src`, `lib`, or a file. Express/NestJS endpoint tasks start with `routes`. CommonJS assignments like `exports.foo = function`, `app.handle = function`, and `res.render = function` are parser-visible; use qualified `symbols res.render` or bare `defs handle`, then `--include-code`. | Dynamic router dispatch, prototype mutation, generated code, or 0-result `refs` may require `rg` on the exact property/call. | +| Python | FastAPI/Django endpoint tasks start with `routes`. Otherwise use `symbols`/`defs` with `--lang python --dir ` to locate functions/classes, then shallow `call-hierarchy`. | You need precise refs, decorators, monkey patches, dynamic imports, or runtime framework wiring. | | Java/Kotlin | Spring endpoint tasks start with `routes --framework spring`. Scope production code with `--dir src/main/java` or `--dir src/main/kotlin`; use `--file-pattern` for overloaded or common method names. | The index is stale/missing, annotation-generated behavior matters, or Java/Kotlin cross-language calls are incomplete. | | Swift | Vapor endpoint tasks start with `routes --framework vapor`. Scope to `Sources/` or a specific file before `defs`/`symbols` and shallow call queries. | SourceKit or build settings are missing, or protocol/extension dispatch decides behavior. | | Ruby | Rails endpoint tasks start with `routes --framework rails`. Scope to `app/controllers`, `app/models`, or a specific file before `defs`/`symbols`. | Rails metaprogramming, dynamic dispatch, or Bundler/Sorbet setup hides the target. | @@ -83,7 +83,5 @@ query that identifies the concrete file. or stale precise index, use `rg` or `index doctor`. - `defs` and `symbols` may include tree-sitter `parser_fact` supplements even when SCIP is fresh, or fall back to parser when SCIP is unavailable. -- `calls`, `callers`, and `call-hierarchy` are `inferred_candidate` navigation - leads. -- Verify exact source ranges with the host read/editor before editing or making - a strong claim. +- `calls`, `callers`, and `call-hierarchy` return `inferred_candidate` + relations. diff --git a/skills/codetrail/SKILL.md b/skills/codetrail/SKILL.md index 59ded19..c9db22e 100644 --- a/skills/codetrail/SKILL.md +++ b/skills/codetrail/SKILL.md @@ -1,13 +1,13 @@ --- name: codetrail -description: Use for low-token CodeTrail CLI lookups: framework routes, symbols, definitions, precise references, and call/caller relationships that plain text search cannot answer cleanly. +description: Use for low-token CodeTrail CLI lookups: framework routes, symbols, definitions, precise references, and call/caller relationships. --- # CodeTrail -Use CodeTrail when you need structured navigation, not for broad repository -exploration. Use normal tools (`rg`, `fd`, host read/editor, `git`) for text, -paths, file reads, and Git workflows. +Use CodeTrail for targeted framework route, symbol, definition, reference, and +call/caller lookups. Use normal tools (`rg`, `fd`, `git`) for broad text, path, +and Git workflows. The CLI defaults to compact text output. Add `--output json` only when another tool must parse the response. Use global `--path ` for roots outside cwd. Keep `--dir` workspace-relative (`.`, `src`, `crates/core`); absolute `--dir` is fallback only. For index archives, use `index pack --archive `. @@ -27,11 +27,11 @@ codetrail call-hierarchy --direction incoming|outgoing --depth 2 --lang 3. Then query call direction: who calls it is `--direction incoming`; what it calls is `--direction outgoing`. Keep `--depth 2` unless there is a clear reason to expand. -4. When implementation evidence is needed, use - `defs`/`symbols --include-code --code-max-lines 8..30` instead of reading a - whole file. +4. For compact code context, use + `defs`/`symbols --include-code --code-max-lines 8..30`. 5. On empty results, dynamic dispatch, macros, trait/interface dispatch, or - generated behavior, switch to `rg` and small source reads immediately. + generated behavior, narrow with `--dir`, `--file-pattern`, exact names, or + `rg` for literal matches. ## Routes First @@ -61,9 +61,9 @@ codetrail call-hierarchy --direction outgoing --depth 2 --lang | Language | Start here | Fallback quickly when | | --- | --- | --- | | Go | Scope by package or file. `codetrail symbols Default --lang go --file-pattern gin.go --limit 5`; `codetrail defs Engine.addRoute --lang go --include-code --code-max-lines 20 --limit 3`; `codetrail call-hierarchy Engine.addRoute --direction incoming --lang go --depth 2 --limit 40`; route tasks start with `routes --framework gin\|chi\|gorilla\|net/http`. | Selector or interface dispatch is the key fact, or generated/test/vendor code pollutes results. | -| Rust | Scope by crate or exact file. `codetrail symbols Config --lang rust --dir crates/core --limit 30`; `codetrail defs run --lang rust --file-pattern crates/core/main.rs --include-code --code-max-lines 25 --limit 3`; `codetrail call-hierarchy search --lang rust --dir crates/core --direction outgoing --depth 2 --limit 40`. | Macros, cfg/features, trait dispatch, or broad names like `run`, `search`, `new` need source confirmation. | -| TypeScript/JavaScript | Always set `--lang typescript` or `--lang javascript` and scope to `src`, `lib`, or a file. Express/NestJS endpoint tasks start with `routes`. CommonJS assignments like `exports.foo = function`, `app.handle = function`, and `res.render = function` are parser-visible; use qualified `symbols res.render` or bare `defs handle`, then `--include-code`. | Dynamic router dispatch, prototype mutation, generated code, or 0-result `refs` decides the answer; use `rg` on the exact property/call. | -| Python | FastAPI/Django endpoint tasks start with `routes`. Otherwise use `symbols`/`defs` with `--lang python --dir ` to locate functions/classes, then shallow `call-hierarchy` only as a lead. | You need precise refs, decorators, monkey patches, dynamic imports, or runtime framework wiring. | +| Rust | Scope by crate or exact file. `codetrail symbols Config --lang rust --dir crates/core --limit 30`; `codetrail defs run --lang rust --file-pattern crates/core/main.rs --include-code --code-max-lines 25 --limit 3`; `codetrail call-hierarchy search --lang rust --dir crates/core --direction outgoing --depth 2 --limit 40`. | Macros, cfg/features, trait dispatch, or broad names like `run`, `search`, `new` require tighter scoping. | +| TypeScript/JavaScript | Always set `--lang typescript` or `--lang javascript` and scope to `src`, `lib`, or a file. Express/NestJS endpoint tasks start with `routes`. CommonJS assignments like `exports.foo = function`, `app.handle = function`, and `res.render = function` are parser-visible; use qualified `symbols res.render` or bare `defs handle`, then `--include-code`. | Dynamic router dispatch, prototype mutation, generated code, or 0-result `refs` may require `rg` on the exact property/call. | +| Python | FastAPI/Django endpoint tasks start with `routes`. Otherwise use `symbols`/`defs` with `--lang python --dir ` to locate functions/classes, then shallow `call-hierarchy`. | You need precise refs, decorators, monkey patches, dynamic imports, or runtime framework wiring. | | Java/Kotlin | Spring endpoint tasks start with `routes --framework spring`. Scope production code with `--dir src/main/java` or `--dir src/main/kotlin`; use `--file-pattern` for overloaded or common method names. | The index is stale/missing, annotation-generated behavior matters, or Java/Kotlin cross-language calls are incomplete. | | Swift | Vapor endpoint tasks start with `routes --framework vapor`. Scope to `Sources/` or a specific file before `defs`/`symbols` and shallow call queries. | SourceKit or build settings are missing, or protocol/extension dispatch decides behavior. | | Ruby | Rails endpoint tasks start with `routes --framework rails`. Scope to `app/controllers`, `app/models`, or a specific file before `defs`/`symbols`. | Rails metaprogramming, dynamic dispatch, or Bundler/Sorbet setup hides the target. | @@ -83,7 +83,5 @@ query that identifies the concrete file. or stale precise index, use `rg` or `index doctor`. - `defs` and `symbols` may include tree-sitter `parser_fact` supplements even when SCIP is fresh, or fall back to parser when SCIP is unavailable. -- `calls`, `callers`, and `call-hierarchy` are `inferred_candidate` navigation - leads. -- Verify exact source ranges with the host read/editor before editing or making - a strong claim. +- `calls`, `callers`, and `call-hierarchy` return `inferred_candidate` + relations.