evil-skills/project-understanding

Overview

This skill provides fast, token-budgeted views of a large unfamiliar repository to produce reliable architecture and impact summaries under time pressure. It indexes the repo once with tree-sitter-based symbol extraction, then uses focused commands (repomap, find, zoom, graph, impact) to answer targeted questions without wasting LLM context. The workflow is optimized for safety and repeatability in supported languages like Python, JavaScript, TypeScript, Go, and Rust.

How this skill works

From the repo root you set a PUI wrapper script path and run an index to build a local symbol graph stored under .pui/. The skill exposes commands to generate directory-level maps, locate symbols, zoom into specific symbol implementations, render call/dep graphs, and run blast-radius impact analysis. Commands are token-budget aware and include flags like --depth and --max-tokens to control output size and LLM consumption.

When to use it

• Entering a large unfamiliar codebase and needing a high-level map quickly.
• Planning a refactor or hotfix and needing callers, dependents, or blast radius.
• Working under strict LLM token budgets and needing concise repository summaries.
• Verifying that a change respects architectural boundaries or module scopes.
• Under time pressure where manual grep risks missing indirect dependencies.

Best practices

• Always run index from the repo root before other commands; use index build after big changes.
• Set PUI to the absolute script path and cd into the target repo; there is no --repo flag.
• Use find to resolve symbol ids before zoom or graph; zoom targets are symbol ids/names or file:line only.
• Limit output with --depth and --max-tokens to stay within LLM context budgets.
• Check language support early: full symbol graphs work best for Python/JS/TS/Go/Rust; C/C++ is file-level.

Example use cases

• Generate a repomap --depth 2 --max-tokens 1200 to get a compact directory + top files overview for onboarding.
• Find a service symbol, then graph --symbol <id> --depth 1 to enumerate immediate callers before touching code.
• Run impact --files path/to/file --include-tests to list affected files and test coverage for a hotfix.
• Use find + zoom file:123 to extract the exact function body to feed into an LLM without sending whole files.
• Run impact --git-diff HEAD~1..HEAD to produce a scoped blast-radius for a recent commit.