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)

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

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

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

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