---
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 require`d 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.