Project Understanding
Overview
Automated repository intelligence via Tree-sitter indexing and PUI commands. Core principle: index once, then use focused packs (repomap/find/zoom/impact) instead of manual grep.
When to Use
- Entering new codebase: Rapidly map structure and entry points
- Planning refactors or hotfixes: Find callers and assess blast radius
- Budgeting context: Fit repository summaries into LLM token limits
- Time pressure: Reduce risk of missing indirect dependencies
- Verification: Ensure changes don't violate architectural boundaries
When NOT to Use
- Tiny repos: Manual reading is faster than indexing
- Unsupported languages: Avoid relying on symbol graphs (see
skills/project-understanding/references/LANG_SUPPORT.md)
Language Support (Read This Early)
- Full symbol/call graph support: Python, JavaScript, TypeScript, Go, Rust
- C/C++: Expect mostly file-level results;
zoom/graphmay show "Symbol not found" - Reference:
skills/project-understanding/references/LANG_SUPPORT.md
Command Guardrails (No Exceptions)
- Repo selection is the working directory. There is no
--repoflag. - Always call
"$PUI"from the target repo. Do not run./scripts/pui.shinside the target repo. zoomtarget is positional. There is no--targetor--fileflag.zoomdoes not accept file paths. Use a symbol id/name orfile:line.
Core Workflow
- Set tool path once:
PUI="/path/to/skills/project-understanding/scripts/pui.sh"(usepui.ps1on Windows). Do NOT run./scripts/pui.shfrom the target repo. - From the repo root (no
--repoflag):
- "$PUI" index (or "$PUI" index build after big changes) - "$PUI" repomap --depth 2 --max-tokens auto
- Locate symbols:
- "$PUI" find "SymbolName" to get a symbol id (avoid guessing generic names) - "$PUI" zoom <symbol-id|name|file:line> (file paths alone will fail) - "$PUI" graph --symbol <symbol-id|name> --depth 2
- Assess impact:
- "$PUI" impact --files path/to/file --include-tests - "$PUI" impact --git-diff HEAD~1..HEAD
Example (Lean Boost)
From the project-understanding-skill repo root:
PUI="$(pwd)/skills/project-understanding/scripts/pui.sh"
cd ./codebases/lean-boost
"$PUI" index
"$PUI" repomap --depth 3 --max-tokens 1200
"$PUI" find "services_manager"
"$PUI" graph --symbol 70 --depth 1 --format mermaid
"$PUI" impact --files src/uninstall/leftovers_scanner.cpp --max-tokens 800Installation
The skill works out of the box. On first run it bootstraps a shared virtual environment in ~/.local/share/pui/venv (or a local fallback). Repository indexes are stored in .pui/ under the project root.
Quick Reference
| Command | Purpose | Key Flag |
|---|---|---|
index | Build/update index | build, --force |
repomap | Directory + top files | --depth, --max-tokens |
find | Symbol search | --limit, --format |
zoom | Symbol detail | --max-tokens |
graph | Call/dependency graph | --symbol, --depth |
impact | Blast radius analysis | --files, --git-diff, --include-tests |
architecture | High-level architecture summary | --format |
depgraph | Module dependency graph | --scope, --format |
Usage notes:
zoomtarget is positional; there is no--targetflag.zoomdoes not accept file paths; use a symbol id/name orfile:line.- Use
findfirst if you are unsure of symbol ids.
Impact Analysis Confidence
| Score | Meaning | Action |
|---|---|---|
| 0.9+ | Definite match | Trust & proceed |
| 0.7-0.9 | Likely (imports) | Verify manually |
| <0.7 | Heuristic/dynamic | Treat as hints |
Confidence signals are meaningful only for supported languages with symbol extraction.
Common Mistakes
- Wrong script path: Running
./scripts/pui.shfrom the repo root fails. Use an absolute path orPUI=.... - Skipping index: Commands will fail or show stale data. Use
indexregularly; useindex buildfor full rebuilds. - Wrong zoom target:
zoomneeds a symbol id/name orfile:line. There is no--targetflag. - Guessing symbols: Run
findbeforezoom/graph, especially in large repos. - Inventing flags: There is no
--repoflag; set the repo bycdinto it. - Assuming C/C++ symbol graphs: Check
skills/project-understanding/references/LANG_SUPPORT.mdfirst. - Ignoring budget: Large repo-maps can burn 20k+ tokens. Use
--depthor--max-tokens.
Rationalization Table
| Excuse | Reality |
|---|---|
| "I can just grep for imports" | Grep misses indirect dependencies. impact is more accurate after indexing. |
| "Structure is obvious from folder names" | Folder names are not dependency graphs. Use repomap and graph. |
| "Indexing takes too long" | Indexing is incremental; manual tracing is slower and riskier. |
| "I haven't used the tool, so I'll skip it" | First run cost is one-time; find + impact save time after. |
| "I'll just read the big files" | Reading 600+ line files burns tokens and focus. zoom isolates the essential logic. |
| "The tool should be in./scripts here" | The script lives in the skill directory. Set PUI first. |
| "I can zoom a file path" | zoom needs a symbol id/name or file:line. File paths alone fail. |
Red Flags - STOP and Index
- You are about to publish an impact summary from manual grep alone.
- You are guessing architecture based on folder names.
- You see "Symbol not found" and keep going without checking language support or
find. - You are about to run
./scripts/pui.shinside the target repo. - You are about to pass a file path to
zoom. - You are manually following imports through more than 2 files.
- You are hitting context window limits with large code blocks.
All of these mean: run index, use repomap/find/impact, or verify language support first.