code-structure

code-structure

When the question is "list the X in Y", do not Read the whole file. Get an outline first; Read selectively after.

Trigger discrimination

• "list / show / all the methods/classes/exports in ..." -- outline (this skill)
• "where is X defined" / "find calls to X" -- search (rg or ast-grep)
• "how does X work" / "what does X do" -- Read

Tiered approach

1. ast-grep outline -- the default. One interface across languages, no build or import step, and every text view carries line numbers so you can Read just the range you need afterward. Pass -l to be safe (required for stdin; inferred from extension for paths).

   • File outline: ast-grep outline -l go file.go (digest: signatures + member names)
   • Cheapest survey: ast-grep outline -l go file.go --view names
   • Drill one symbol's members: ast-grep outline -l go file.go --match Visitor --view expanded
   • Directory's exported surface: ast-grep outline -l go ./pkg
   • Filter by kind: --type struct,function; by name: --match REGEX; public members only: --pub-members
   • Dependency check: ast-grep outline -l go file.go --items imports
   • Machine-readable: --json=compact (also pretty, stream)

2. Compiler/parser-aware tool when you need true export semantics or docstrings, which outline does not carry:

   • Go: go doc -all ./path/to/pkg
   • Python: python -m pydoc some.module.path (requires the module to be importable -- deps installed, on PYTHONPATH)
   • TS/JS third-party: cat node_modules/<pkg>/dist/index.d.ts -- the declaration file is a pre-made API outline
   • Java: javap -p <Class> (requires compiled .class files)

3. ctags fallback -- for languages outline's bundled rules don't cover; canonical for C/C++:

   ctags -f - file | grep -v '^!' | cut -f1,4    # symbol + kind
   

Use the outline to decide what to Read, then Read just that section.