Use act's query tools to traverse large repositories efficiently.
Do NOT read entire files when you can query for specific information.
-
Start with repo-outline — Before exploring a codebase, run repo_outline to understand the file tree, languages, and structure. Use --symbols for files of interest.
-
Use skeleton for file structure — When you need to understand a file's structure, use skeleton to see declarations without bodies. Never read an entire file just to find function names.
-
Use interface for API surfaces — When you need to understand how to use a class or module, use interface to get signatures, types, and docstrings without implementation details.
-
Follow the dependency graph — Use graph to understand how files are connected. Start from the file you're interested in with --direction out (what it depends on) or --direction in (what depends on it).
-
Use mutations for raw side-effect detection — Before modifying a function, use mutations to see the individual reads/writes of external state.
-
Use effect_summary for a categorized effect picture — When you want the function's effects classified (reads, writes, raises, allocations, blocking calls, awaits) plus a purity verdict and an unresolved-call frontier, use effect_summary. It is the higher-level view over mutations: reach for effect_summary to answer "what does this touch, and is it pure?" before a change; drop to mutations for the raw access list.
-
Use control-flow for complex logic — When a function is hard to understand, use control_flow to get a linearized view of its branching structure.
-
Use data_flow to trace values through a function — The dual of control_flow: data_flow returns variable definition sites, use sites, def→use edges, and the locals that flow into the return. Reach for it to answer "where does this value come from / where does it go" within one function.
-
Batch symbol retrieval — When you need symbols from multiple files, use symbols_batch --files instead of making separate symbols calls. When you need specific implementations, use symbols_batch --ids with stable IDs.
-
Use stable symbol IDs — After finding a symbol, use its stable ID (format: file::QualifiedName#kind) for subsequent operations. This avoids ambiguity and eliminates the need to specify --file.
-
Use definition for cross-file navigation — When you find a reference to an unknown symbol, use definition to jump to its source.
-
Analyze before modifying — Before making changes, run effect_summary (or mutations) on affected functions and graph on affected files to understand the blast radius.
