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/graph may 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 --repo flag.
• Always call "$PUI" from the target repo. Do not run ./scripts/pui.sh inside the target repo.
• zoom target is positional. There is no --target or --file flag.
• zoom does not accept file paths. Use a symbol id/name or file:line.

Core Workflow

1. Set tool path once: PUI="/path/to/skills/project-understanding/scripts/pui.sh" (use pui.ps1 on Windows). Do NOT run ./scripts/pui.sh from the target repo.
2. From the repo root (no --repo flag):
   • "$PUI" index (or "$PUI" index build after big changes)
   • "$PUI" repomap --depth 2 --max-tokens auto
3. 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
4. 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 800

Installation

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

Usage notes:

• zoom target is positional; there is no --target flag.
• zoom does not accept file paths; use a symbol id/name or file:line.
• Use find first if you are unsure of symbol ids.

Impact Analysis Confidence

Confidence signals are meaningful only for supported languages with symbol extraction.

Common Mistakes

• Wrong script path: Running ./scripts/pui.sh from the repo root fails. Use an absolute path or PUI=....
• Skipping index: Commands will fail or show stale data. Use index regularly; use index build for full rebuilds.
• Wrong zoom target: zoom needs a symbol id/name or file:line. There is no --target flag.
• Guessing symbols: Run find before zoom/graph, especially in large repos.
• Inventing flags: There is no --repo flag; set the repo by cd into it.
• Assuming C/C++ symbol graphs: Check skills/project-understanding/references/LANG_SUPPORT.md first.
• Ignoring budget: Large repo-maps can burn 20k+ tokens. Use --depth or --max-tokens.

Rationalization Table

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.sh inside 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.