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

name

description

tcl-whatis

Use when you need to know how to call a Tcl command in this repo (including ensemble subcommands like 'string is'), where a proc is defined (file and line number), which module version is actually loaded, or what a proc's runtime body is. Runtime introspection via punkshell - reports resolved name, kind (proc/alias/ensemble), providing package + version, origin file, def file:line, and punk::args synopsis. Cheaper and more accurate than grep+read for interface questions, and the only option for runtime-generated procs.

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/; any punkshell kit works):

punk91 src script scriptlib/developer/whatis.tcl ?-body? ?-doc? <command> ?subcommand?...

• <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).

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).
• 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.