understand

What it does

Analyzes a codebase to produce a knowledge-graph.json in the project's data directory, then optionally merges subdomain graphs, and manages incremental vs full analysis based on flags, existing graphs, and commit state. It supports language customization, auto-update config, and exclude patterns for analysis. It also collects project context (readme, manifests, directory tree, entry point) for subagent injection, and initializes or updates ignore configuration.

How it works

• Analyzes the current codebase to create knowledge-graph.json in the project's data directory (.ua/ or .understand-anything/).
• Supports options: --full, --auto-update, --no-auto-update, --review, --language <lang>, --exclude <patterns>, and a target directory argument.
• Performs Phase 0 pre-flight, including determining PROJECT_ROOT, potential worktree redirection, and ensuring a plugin build.
• Resolves UA_DIR as the data directory, then creates intermediate and tmp directories.
• Handles auto-update flags by writing a JSON with autoUpdate true/false to config.json and stores OUTPUT_LANGUAGE for later phases.
• Processes --language to set or persist language preferences, including a user-prompt flow when not specified and a detected language is non-English. Stores a LANGUAGE_DIRECTIVE note describing the chosen language behavior.
• Parses --exclude to collect and pass exclude patterns to downstream steps, with patterns taking highest priority.
• Merges any subdomain knowledge graphs found in $UA_DIR (excluding knowledge-graph.json) by running a Python script in the skill directory: python "<SKILL_DIR>/merge-subdomain-graphs.py" "$PROJECT_ROOT".
• If a knowledge-graph.json already exists, loads it and, if applicable, uses a review path via --review or prompts for actions based on commit hash changes and --full.
• For incremental updates, uses git diff to identify changed files since last commit and re-analyzes only those files; if none, reports up-to-date and stops.
• Collects project context for subagent injection: README content, primary manifest content, a top-level directory tree excerpt, and detects an entry point by checking common file patterns.
• Phase 0.5 establishes or verifies the .understandignore via a starter script if missing, invoking a bundled node script with plugin path injected.

When to use it

• Use --full to force a complete re-analysis regardless of existing graphs or commit state.
• Use --review to run a full LLM graph-reviewer instead of inline validation when a graph exists and commit unchanged.
• Use --exclude to ignore specific files or directories during analysis, with highest priority over defaults.
• Use --language to generate all textual content in a target language and persist the preference for future updates.
• Use a target directory argument to analyze a different repository or path instead of the current one.

What it can touch

• Executes Python script: "merge-subdomain-graphs.py" located next to the skill (path relative to the skill folder).
• Writes and reads: knowledge-graph.json, config.json, intermediate/, tmp/, and possibly other UA_DIR files.
• Reads: README.* files in the project root, manifest files like package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml; directory listings via find.
• Executes node-based ignore generation: generate-ignore.mjs, passing PLUGIN_ROOT via environment.

Caveats

• Output is redirected when in a Git worktree unless UNDERSTAND_NO_WORKTREE_REDIRECT is set to 1.
• The process may prompt for language confirmation when a non-English detected language is found and no explicit --language is provided.
• Language templates and directives are stored for downstream reference and display.
• If incremental updates detect no changed files, the process stops with a notice that the graph is up to date.
• The merge-subdomain-graphs step relies on a helper script within the skill directory and may affect how the base knowledge graph is structured through deduplication of nodes and edges.