punkshell/.agents/skills/tcl-whatis/SKILL.md

name: tcl-whatis description: Use BEFORE reviewing, testing, editing, porting or relocating any Tcl command in this repo, and for any question about a command's definition site, calling interface, loaded module version, or runtime body (including ensemble subcommands like 'string is'). Run it first; reserve grep for full-text source-pattern searches - this repo has several coexisting copies of many modules and grep cannot tell you which copy is actually loaded. Cost: one sub-1s side-effect-free punkshell invocation. Reports resolved name, kind (proc/alias/ensemble), providing package + loaded version, origin file, def file:line, and punk::args synopsis; the only option for runtime-generated procs. For namespace/package-level discovery (listing what a namespace exposes, no command name needed) use the tcl-nslist skill.

tcl-whatis

Runtime introspection for Tcl commands in the punkshell repo. Asks the live interpreter instead of grepping source, so it resolves aliases, ensembles and subcommand chains, autoloads the providing module, and reports which of the repo's several module copies (src/modules vs bootsupport vs kit-internal zipfs) is actually loaded.

Command

Run from the repo root (punk91 lives in bin/, so bin/punk91 from the Bash tool; any punkshell kit works). Cost: sub-1s, no side effects.

punk91 src script lib:developer/whatis ?-body? ?-doc? <command> ?subcommand?...

lib:developer/whatis is punkshell script-path shorthand for scriptlib/developer/whatis.tcl.

• <command> - Tcl command name, qualified or not (e.g. punk::args::parse, corp). If not already loaded, the longest namespace-prefix package match is package required automatically.
• ?subcommand?... - ensemble/subcommand words: whatis string is resolves the chain to ::tcl::string::is (via punk::ns::cmdinfo) and reports that origin's synopsis - no prior knowledge of the implementing namespace needed. Unresolvable trailing words are reported in a warning: line.
• -body - append the runtime proc body. Line numbers are file-relative when the def: line was located, so they match the origin file exactly.
• -doc - append the full argument documentation as plain ANSI-free text with the argument section of EVERY command form (punk::ns::cmdhelp -return text). Large for big commands; prefer the default synopsis unless you need per-argument help text, defaults and choices.

Exit codes: 0 ok, 1 command not found, 2 usage error.

Output fields

command:  string is                    the queried words
alias:    -> punk::ns::cmdhelp         alias chain, if any
resolves: ::tcl::string::is            chain/alias resolution target
kind:     proc | ensemble | native command
package:  punk::args 999999.0a1.0      providing package + loaded version
origin:   C:/repo/.../src/modules/punk/args-999999.0a1.0.tm
def:      <origin-file>:6528           proc definition line in origin file
synopsis: one usage line per command form (from the punk::args definition)

Ensembles report their namespace and subcommand map instead of def:.

-doc output structure (parsing contract)

• Column-0 lines containing TYPE: are argument rows, one line each: name TYPE:type(constraints) ?DEFAULT:'val'? ?MULTI:yes?. Optional arguments show as ?name?, repeatable ones as name....
• Indented lines under a row are that argument's help text (never flags, even when a line starts with -word).
• Choices are markdown-style bullets: - `choice` - label text, with label continuation lines indented past the bullet dash. The backticked token is the choice (it may carry a trailing marker glyph); everything after the closing backtick is label/documentation.
• Multiform commands render one --ARGUMENTS (form 'name')-- section per form under a single common header (description + all-forms synopsis).

Namespace discovery (sibling skill)

whatis needs a command name. For the discovery question - what commands and child namespaces a namespace or package exposes at all - use the tcl-nslist skill (lib:developer/nslist). whatis prints a redirect hint when the queried name turns out to be a namespace rather than a command.

Caveats

• Keep the src launch argument: it loads the working-tree modules under src/modules (versions like 999999.0a1.0) so origin/def point at editable files. Without it the kit-stamped copies inside the executable are introspected (//zipfs:/... paths, older versions) and the report says so in a warning: line.
• Load noise ("src mode: registered ...") goes to stderr; read stdout only (append 2>/dev/null in bash, 2>$null in PowerShell).
• Prefer the Bash tool over the PowerShell tool for these invocations: PowerShell-tool children get an attached console, which can flip punkshell's colour/terminal detection and change output classification.
• To edit a proc, go to the def: file:line and Read the file there; do not build edits from -body output text.
• def: (no proc definition found ...) means the proc was generated at runtime - -body output is then the only source.
• Trust origin: over assumptions about which module copy is loaded; this repo has several coexisting copies of many modules and ties do not always resolve the way you expect.