Understand

/understand

Analyze the current codebase and produce a knowledge-graph.json file in .understand-anything/. This file powers the interactive dashboard for exploring the project's architecture.

Options

• $ARGUMENTS may contain:
• --full — Force a full rebuild, ignoring any existing graph
• --auto-update — Enable automatic graph updates on commit (writes autoUpdate: true to .understand-anything/config.json)
• --no-auto-update — Disable automatic graph updates (writes autoUpdate: false to .understand-anything/config.json)
• --review — Run full LLM graph-reviewer instead of inline deterministic validation
• --language <lang> — Generate all textual content (summaries, descriptions, tags, titles, languageNotes, languageLesson) in the specified language. Accepts ISO 639-1 codes (zh, ja, ko, en, es, fr, de, etc.) or friendly names (chinese, japanese, korean, english, spanish, etc.). Locale variants supported: zh-TW, zh-HK, etc. Defaults to en (English). Stores preference in .understand-anything/config.json for consistency across incremental updates.
• A directory path (e.g. /path/to/repo or ../other-project) — Analyze the given directory instead of the current working directory

---

Progress Reporting

Throughout execution, report progress to the user at each phase transition and during batch processing. This keeps users informed on large codebases where analysis can take a long time.

• Phase transitions: At the start of each phase, print a status line:

[Phase N/7] <phase name>...

>

Example: [Phase 2/7] Analyzing files (12 batches)...

• Batch progress: During Phase 2, report each batch with its index and total:

Analyzing batch X/N (files: foo.ts, bar.ts, ...) (list up to 3 filenames, then ... if more)

• Phase completion: When a phase finishes, briefly confirm:

Phase N complete. <one-line summary of result>

>

Example: Phase 1 complete. Found 247 files across 3 languages.

---

Phase 0 — Pre-flight

Determine whether to run a full analysis or incremental update.

1. Resolve `PROJECT_ROOT`:

• Parse $ARGUMENTS for a non-flag token (any argument that does not start with --). If found, treat it as the target directory path.
• If the path is relative, resolve it against the current working directory.
• Verify the resolved path exists and is a directory (run test -d <path>). If it does not exist or is not a directory, report an error to the user and STOP.
• Set PROJECT_ROOT to the resolved absolute path.
• If no directory path argument is found, set PROJECT_ROOT to the current working directory.
• Worktree redirect. If PROJECT_ROOT is inside a git worktree (not the main checkout), redirect output to the main repository root. Worktrees managed by Claude Code are ephemeral — .understand-anything/ written there is destroyed when the session ends, taking the knowledge graph with it (issue #133). Detect a worktree by comparing git rev-parse --git-dir against git rev-parse --git-common-dir; in a normal checkout or submodule they resolve to the same path, in a worktree they differ and the parent of --git-common-dir is the main repo root.

     COMMON_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-common-dir 2>/dev/null)
     GIT_DIR=$(git -C "$PROJECT_ROOT" rev-parse --git-dir 2>/dev/null)
     if [ -n "$COMMON_DIR" ] && [ -n "$GIT_DIR" ]; then
       COMMON_ABS=$(cd "$PROJECT_ROOT" && cd "$COMMON_DIR" 2>/dev/null && pwd -P)
       GIT_ABS=$(cd "$PROJECT_ROOT" && cd "$GIT_DIR" 2>/dev/null && pwd -P)
       if [ -n "$COMMON_ABS" ] && [ "$COMMON_ABS" != "$GIT_ABS" ]; then
         MAIN_ROOT=$(dirname "$COMMON_ABS")
         if [ -d "$MAIN_ROOT" ] && [ "${UNDERSTAND_NO_WORKTREE_REDIRECT:-0}" != "1" ]; then
           echo "[understand] Detected git worktree at $PROJECT_ROOT"
           echo "[understand] Redirecting output to main repo root: $MAIN_ROOT"
           echo "[understand] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
           PROJECT_ROOT="$MAIN_ROOT"
         fi
       fi
     fi

Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 if you intentionally want a per-worktree graph (rare — most users want the redirect). 1.5. Ensure the plugin is built. Later phases invoke Node scripts that import @understand-anything/core. On a fresh install packages/core/dist/ does not exist yet — build once.

Important: do not assume the plugin root is simply two directories above the skill path string. In many installations ~/.agents/skills/understand is a symlink into the real plugin checkout. Prefer runtime-provided plugin roots first (for Claude), then fall back to universal symlinks, skill symlink resolution, and common clone-based install paths.

Resolve the plugin root like this:

   SKILL_REAL=$(realpath ~/.agents/skills/understand 2>/dev/null || readlink -f ~/.agents/skills/understand 2>/dev/null || echo "")
   SELF_RELATIVE=$([ -n "$SKILL_REAL" ] && cd "$SKILL_REAL/../.." 2>/dev/null && pwd || echo "")
   COPILOT_SKILL_REAL=$(realpath ~/.copilot/skills/understand 2>/dev/null || readlink -f ~/.copilot/skills/understand 2>/dev/null || echo "")
   COPILOT_SELF_RELATIVE=$([ -n "$COPILOT_SKILL_REAL" ] && cd "$COPILOT_SKILL_REAL/../.." 2>/dev/null && pwd || echo "")

   PLUGIN_ROOT=""
   for candidate in \
     "${CLAUDE_PLUGIN_ROOT}" \
     "$HOME/.understand-anything-plugin" \
     "$SELF_RELATIVE" \
     "$COPILOT_SELF_RELATIVE" \
     "$HOME/.codex/understand-anything/understand-anything-plugin" \
     "$HOME/.opencode/understand-anything/understand-anything-plugin" \
     "$HOME/.pi/understand-anything/understand-anything-plugin" \
     "$HOME/understand-anything/understand-anything-plugin"; do
     if [ -n "$candidate" ] && [ -f "$candidate/package.json" ] && [ -f "$candidate/pnpm-workspace.yaml" ]; then
       PLUGIN_ROOT="$candidate"
       break
     fi
   done

   if [ -z "$PLUGIN_ROOT" ]; then
     echo "Error: Cannot find the understand-anything plugin root."
     echo "Checked:"
     echo "  - ${CLAUDE_PLUGIN_ROOT:-<unset CLAUDE_PLUGIN_ROOT>}"
     echo "  - $HOME/.understand-anything-plugin"
     echo "  - ${SELF_RELATIVE:-<unresolved path derived from ~/.agents/skills/understand>}"
     echo "  - ${COPILOT_SELF_RELATIVE:-<unresolved path derived from ~/.copilot/skills/understand>}"
     echo "  - $HOME/.codex/understand-anything/understand-anything-plugin"
     echo "  - $HOME/.opencode/understand-anything/understand-anything-plugin"
     echo "  - $HOME/.pi/understand-anything/understand-anything-plugin"
     echo "  - $HOME/understand-anything/understand-anything-plugin"
     echo "Make sure the plugin is installed correctly."
     exit 1
   fi

   if [ ! -f "$PLUGIN_ROOT/packages/core/dist/index.js" ]; then
     cd "$PLUGIN_ROOT" && (pnpm install --frozen-lockfile 2>/dev/null || pnpm install) && pnpm --filter @understand-anything/core build
   fi

If pnpm is missing, report to the user: "Install Node.js ≥ 22 and pnpm ≥ 10, then re-run /understand."

2. Get the current git commit hash:

   git rev-parse HEAD

3. Create the intermediate and temp output directories:

   mkdir -p $PROJECT_ROOT/.understand-anything/intermediate
   mkdir -p $PROJECT_ROOT/.understand-anything/tmp

3.1. Purge stale trash dirs. Phase 7 cleanup mvs scratch dirs into .trash-<timestamp>/ rather than rm -rfing them directly (see issue #301), so that destructive-action gates on hardened hosts don't trip on just-created paths. Reclaim the space here once the trash is older than 7 days — by this point any freshness-window check has long since stopped caring about those dirs:

   find $PROJECT_ROOT/.understand-anything/ -maxdepth 1 -type d -name '.trash-*' -mtime +7 -exec rm -rf {} + 2>/dev/null || true

3.5. Auto-update configuration:

• If --auto-update is in $ARGUMENTS: write {"autoUpdate": true} to $PROJECT_ROOT/.understand-anything/config.json
• If --no-auto-update is in $ARGUMENTS: write {"autoUpdate": false} to $PROJECT_ROOT/.understand-anything/config.json
• These flags only set the config — analysis proceeds normally regardless.

3.6. Language configuration:

• Parse $ARGUMENTS for --language <lang> flag. If found, extract the language code.
• Language code normalization: Map friendly names to ISO codes:
• chinese → zh, japanese → ja, korean → ko, english → en, spanish → es, french → fr, german → de, portuguese → pt, russian → ru, arabic → ar, etc.
• Locale variants: zh-TW, zh-HK, zh-CN, pt-BR, etc. are preserved as-is.
• If --language is NOT specified:
• Stored preference wins. If $PROJECT_ROOT/.understand-anything/config.json has an outputLanguage field, set $OUTPUT_LANGUAGE to it and skip the rest.
• Otherwise detect (first run only). Infer the predominant language of the user's conversation as an ISO 639-1 code ($DETECTED_LANG). If it is en or cannot be confidently determined, set $OUTPUT_LANGUAGE=en and proceed silently — no prompt (English users see no change).
• If `$DETECTED_LANG` ≠ `en`, confirm once before analyzing: tell the user you detected <language> and ask whether to generate all content in it; they press Enter/"yes" to accept, or type another language code/name to override (normalize via the friendly-name map above). If running non-interactively (no reply possible), skip the wait, use $DETECTED_LANG, and print a one-line notice instead of blocking.
• Persist the resolved $OUTPUT_LANGUAGE (including en) into config.json so it never re-prompts for this project.
• If --language IS specified:
• Update $PROJECT_ROOT/.understand-anything/config.json with the new language: merge {"outputLanguage": "<lang>"} into existing config.
• Store as $OUTPUT_LANGUAGE for use throughout all phases.
• Language directive template: Store as $LANGUAGE_DIRECTIVE:

      > **Language directive**: Generate all textual content (summaries, descriptions, tags, titles, languageNotes, languageLesson) in **{language}**. Maintain technical accuracy while using natural, native-level phrasing in the target language. Keep technical terms in English when no standard translation exists (e.g., "middleware", "hook", "barrel").

4. Check for subdomain knowledge graphs to merge: List all *knowledge-graph*.json files in $PROJECT_ROOT/.understand-anything/ excluding knowledge-graph.json itself (e.g. frontend-knowledge-graph.json, backend-knowledge-graph.json). If any subdomain graphs exist, run the merge script bundled with this skill (located next to this SKILL.md file — use the skill directory path, not the project root):

   python <SKILL_DIR>/merge-subdomain-graphs.py $PROJECT_ROOT

The script discovers subdomain graphs, loads the existing knowledge-graph.json as a base (if present), and merges everything into knowledge-graph.json (deduplicating nodes and edges). Report the merge summary to the user, then continue with the merged graph.

5. Check if $PROJECT_ROOT/.understand-anything/knowledge-graph.json exists. If it does, read it. 6. Check if $PROJECT_ROOT/.understand-anything/meta.json exists. If it does, read it to get gitCommitHash. 7. Decision logic:

Review-only path: Copy the existing knowledge-graph.json to $PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json, then jump directly to Phase 6 step 3.

For incremental updates, get the changed file list:

   git diff <lastCommitHash>..HEAD --name-only

If this returns no files, report "Graph is up to date" and STOP.

8. Collect project context for subagent injection:

• Read README.md (or README.rst, readme.md) from $PROJECT_ROOT if it exists. Store as $README_CONTENT (first 3000 characters).
• Read the primary package manifest (package.json, pyproject.toml, Cargo.toml, go.mod, pom.xml) if it exists. Store as $MANIFEST_CONTENT.
• Capture the top-level directory tree:

     find $PROJECT_ROOT -maxdepth 2 -type f -not -path '*/node_modules/*' -not -path '*/.git/*' -not -path '*/dist/*' | head -100

Store as $DIR_TREE.

• Detect the project entry point by checking for common patterns (in order): src/index.ts, src/main.ts, src/App.tsx, index.js, main.py, manage.py, app.py, wsgi.py, asgi.py, run.py, __main__.py, main.go, cmd/*/main.go, src/main.rs, src/lib.rs, src/main/java/**/Application.java, Program.cs, config.ru, index.php. Store first match as $ENTRY_POINT.

---

Phase 0.5 — Ignore Configuration

Set up and verify the .understandignore file before scanning.

1. Check if $PROJECT_ROOT/.understand-anything/.understandignore exists. 2. If it does NOT exist, generate a starter file by invoking the bundled script (delegates to generateStarterIgnoreFile in @understand-anything/core, which reads .gitignore, deduplicates against built-in defaults, and emits language-grouped test-file suggestions). Pass $PLUGIN_ROOT via the env so the script doesn't have to re-derive it from its own path (which breaks for copied skill installs):

     PLUGIN_ROOT="$PLUGIN_ROOT" node <SKILL_DIR>/generate-ignore.mjs $PROJECT_ROOT

• Report to the user:

Generated .understand-anything/.understandignore with suggested exclusions based on your project structure. Please review it and uncomment any patterns you'd like to exclude from analysis. When ready, confirm to continue.

• Wait for user confirmation before proceeding.

3. If it already exists, report:

Found .understand-anything/.understandignore. Review it if needed, then confirm to continue.

• Wait for user confirmation before proceeding.

4. After confirmation, proceed to Phase 1.

---

Phase 1 — SCAN (Full analysis only)

Report to the user: [Phase 1/7] Scanning project files...

Dispatch a subagent using the project-scanner agent definition (at agents/project-scanner.md). Append the following additional context:

Additional context from main session:

>

Project README (first 3000 chars):

```

$README_CONTENT

```

>

Package manifest:

```

$MANIFEST_CONTENT

```

>

Use this context to produce more accurate project name, description, and framework detection. The README and manifest are authoritative — prefer their information over heuristics.

>

$LANGUAGE_DIRECTIVE

Pass these parameters in the dispatch prompt:

Scan this project directory to discover all project files (including non-code files like configs, docs, infrastructure), detect languages and frameworks.

Project root: $PROJECT_ROOT

Write output to: $PROJECT_ROOT/.understand-anything/intermediate/scan-result.json

After the subagent completes, read $PROJECT_ROOT/.understand-anything/intermediate/scan-result.json to get:

• Project name, description
• Languages, frameworks
• File list with line counts and fileCategory per file (code, config, docs, infra, data, script, markup)
• Complexity estimate
• Import map (importMap): pre-resolved project-internal imports per file (non-code files have empty arrays)

Store importMap in memory as $IMPORT_MAP for use in Phase 2 batch construction. Store the file list as $FILE_LIST with fileCategory metadata for use in Phase 2 batch construction.

Gate check: If >100 files, inform the user and suggest scoping with a subdirectory argument. Proceed only if user confirms or add guidance that this may take a while.

If the scan result includes filteredByIgnore > 0, report:

Excluded {filteredByIgnore} files via .understandignore.

---

Phase 1.5 — BATCH

Report: [Phase 1.5/7] Computing semantic batches...

Run the bundled batching script:

node <SKILL_DIR>/compute-batches.mjs $PROJECT_ROOT

Reads .understand-anything/intermediate/scan-result.json, writes .understand-anything/intermediate/batches.json.

Capture stderr. Append any line starting with Warning: to $PHASE_WARNINGS for the final report.

If the script exits non-zero, the failure is hard — relay the full stderr to the user as a Phase 1.5 failure. Do not attempt to recover; the script's internal fallback (count-based) already handles recoverable issues. A non-zero exit means a fundamental problem (missing input file, malformed JSON, etc.).

---

Phase 2 — ANALYZE

Full analysis path

Load .understand-anything/intermediate/batches.json (produced by Phase 1.5). Iterate the batches[] array.

Report: [Phase 2/7] Analyzing files — <totalFiles> files in <totalBatches> batches (up to 5 concurrent)...

For each batch, dispatch a subagent using the file-analyzer agent definition (at agents/file-analyzer.md). Run up to 5 subagents concurrently. Append the following additional context:

Additional context from main session:

>

Project: <projectName> — <projectDescription>

Languages: <languages from Phase 1>

>

$LANGUAGE_DIRECTIVE

Dispatch prompt template (fill in batch-specific values from batches.json[i]):

Analyze these files and produce GraphNode and GraphEdge objects.

Project root: $PROJECT_ROOT

Project: <projectName>

Languages: <languages>

Batch: <batchIndex>/<totalBatches>

Skill directory (for bundled scripts): <SKILL_DIR>

Output: write to $PROJECT_ROOT/.understand-anything/intermediate/batch-<batchIndex>.json (single-file mode) OR batch-<batchIndex>-part-<k>.json (split mode, per Step B of your output protocol).

>

Pre-resolved import data for this batch (use directly — do NOT re-resolve imports from source):

```json

<batchImportData JSON from batches.json[i].batchImportData>

```

>

Cross-batch neighbors with their exported symbols (confidence boost for cross-batch edges):

```json

<neighborMap JSON from batches.json[i].neighborMap>

```

>

Files to analyze in this batch (every entry MUST be passed through to batchFiles with all four fields — path, language, sizeLines, fileCategory):

1. <path> (<sizeLines> lines, language: <language>, fileCategory: <fileCategory>)

2. <path> (<sizeLines> lines, language: <language>, fileCategory: <fileCategory>)

...

Output naming is per-batchIndex — no fusion. If you fuse multiple small batches into a single file-analyzer dispatch for token efficiency, the dispatched agent must STILL write one output file per original batchIndex using batch-<batchIndex>.json or batch-<batchIndex>-part-<k>.json. The merge script's regex (batch-(\d+)(?:-part-(\d+))?\.json) silently drops any other naming (e.g., batch-fused-8-13.json, batch-8-13.json), losing every node and edge in that file. After each dispatch returns, verify each batchIndex in the dispatched input has a corresponding batch-<batchIndex>.json (or batch-<batchIndex>-part-*.json) on disk before proceeding to the next dispatch.

After ALL batches complete, report to the user: Phase 2 complete. All <totalBatches> batches analyzed.

Run the merge-and-normalize script bundled with this skill (located next to this SKILL.md file — use the skill directory path, not the project root):

python <SKILL_DIR>/merge-batch-graphs.py $PROJECT_ROOT

This script reads all batch-*.json files (including batch-<i>-part-<k>.json produced by file-analyzers that split their output) from $PROJECT_ROOT/.understand-anything/intermediate/, then in one pass:

• Combines all nodes and edges across batches
• Normalizes node IDs (strips double prefixes, project-name prefixes, adds missing prefixes)
• Normalizes complexity values (low→simple, medium→moderate, high→complex, etc.)
• Rewrites edge references to match corrected node IDs
• Deduplicates nodes by ID (keeps last occurrence) and edges by (source, target, type)
• Drops dangling edges referencing missing nodes
• Logs all corrections and dropped items to stderr

The merge script also runs a tested_by linker that canonicalizes test-coverage edges in two passes. Pass 1 walks LLM-emitted tested_by edges and flips inverted ones in place; semantically broken edges (test↔test, prod↔prod, orphan endpoints) are dropped. Pass 2 supplements with path-convention pairings. Production nodes that end up sourcing any tested_by edge get a "tested" tag. All resulting edges run production → test.

Output: $PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json

Include the script's warnings in $PHASE_WARNINGS for the reviewer.

Incremental update path

Write the changed-files list (one path per line) to a temp file:

git diff <lastCommitHash>..HEAD --name-only > $PROJECT_ROOT/.understand-anything/tmp/changed-files.txt

Run compute-batches with --changed-files:

node <SKILL_DIR>/compute-batches.mjs $PROJECT_ROOT \
  --changed-files=$PROJECT_ROOT/.understand-anything/tmp/changed-files.txt

This produces a batches.json that contains only batches with changed files, but neighborMap entries still reference unchanged files (with their full-graph batchIndex) so cross-batch edges remain emittable.

Then dispatch file-analyzer subagents per the same template as the full path.

After batches complete: 1. Remove old nodes whose filePath matches any changed file from the existing graph 2. Remove old edges whose source or target references a removed node 3. Write the pruned existing nodes/edges as batch-existing.json in the intermediate directory 4. Run the same merge script — it will combine batch-existing.json with the fresh batch-*.json files:

   python <SKILL_DIR>/merge-batch-graphs.py $PROJECT_ROOT

---

Phase 3 — ASSEMBLE REVIEW

Report to the user: [Phase 3/7] Reviewing assembled graph...

Dispatch a subagent using the assemble-reviewer agent definition (at agents/assemble-reviewer.md).

Pass these parameters in the dispatch prompt:

Review the assembled graph at $PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json.

Project root: $PROJECT_ROOT

Batch files are at: $PROJECT_ROOT/.understand-anything/intermediate/batch-*.json

Write review output to: $PROJECT_ROOT/.understand-anything/intermediate/assemble-review.json

>

Merge script report:

```

<paste the full stderr output from merge-batch-graphs.py>

```

>

Import map for cross-batch edge verification:

```json

$IMPORT_MAP

```

After the subagent completes, read $PROJECT_ROOT/.understand-anything/intermediate/assemble-review.json and add any notes to $PHASE_WARNINGS.

---

Phase 4 — ARCHITECTURE

Report to the user: [Phase 4/7] Identifying architectural layers...

Build the combined prompt template: 1. Use the architecture-analyzer agent definition (at agents/architecture-analyzer.md). 2. Language context injection: For each language detected in Phase 1 (e.g., python, markdown, dockerfile, yaml, sql, terraform, graphql, protobuf, shell, html, css), read the file at ./languages/<language-id>.md (e.g., ./languages/python.md, ./languages/dockerfile.md) and append its content after the base template under a ## Language Context header. If the file does not exist for a detected language, skip it silently and continue. These files are in the languages/ subdirectory next to this SKILL.md file. Include non-code language snippets — they provide edge patterns and summary styles for non-code files. 3. Framework addendum injection: For each framework detected in Phase 1 (e.g., Django), read the file at ./frameworks/<framework-id-lowercase>.md (e.g., ./frameworks/django.md) and append its full content after the language context. If the file does not exist for a detected framework, skip it silently and continue. These files are in the frameworks/ subdirectory next to this SKILL.md file. 4. Output locale injection: If $OUTPUT_LANGUAGE is NOT en (English), read the locale guidance file at ./locales/<language-code>.md (e.g., ./locales/zh.md, ./locales/ja.md, ./locales/ko.md) and append its content after the framework addendums under a ## Output Language Guidelines header. This provides language-specific guidance for tag naming conventions, summary style, and layer name translations. If the locale file does not exist for the specified language, skip silently — the $LANGUAGE_DIRECTIVE still applies. These files are in the locales/ subdirectory next to this SKILL.md file.

Append the language/framework context and the following additional context to the agent's prompt:

Additional context from main session:

>

Frameworks detected: <frameworks from Phase 1>

>

Directory tree (top 2 levels):

```

$DIR_TREE

```

>

Use the directory tree, language context, and framework addendums (appended above) to inform layer assignments. Directory structure is strong evidence for layer boundaries. Non-code files (config, docs, infrastructure, data) should be assigned to appropriate layers — see the prompt template for guidance.

>

$LANGUAGE_DIRECTIVE

Pass these parameters in the dispatch prompt:

Analyze this codebase's structure to identify architectural layers.

Project root: $PROJECT_ROOT

Write output to: $PROJECT_ROOT/.understand-anything/intermediate/layers.json

Project: <projectName> — <projectDescription>

>

File nodes (all node types — includes code files, config, document, service, pipeline, table, schema, resource, endpoint):

```json

[list of {id, type, name, filePath, summary, tags} for ALL file-level nodes — omit complexity, languageNotes]

```

>

Import edges:

```json

[list of edges with type "imports"]

```

>

All edges (for cross-category analysis — includes configures, documents, deploys, triggers, etc.):

```json

[list of ALL edges — include all edge types]

```

After the subagent completes, read $PROJECT_ROOT/.understand-anything/intermediate/layers.json and normalize it into a final layers array. Apply these steps in order:

1. Unwrap envelope: If the file contains { "layers": [...] } instead of a plain array, extract the inner array. (The prompt requests a plain array, but LLMs may still produce an envelope.) 2. Rename legacy fields: If any layer object has a nodes field instead of nodeIds, rename nodes → nodeIds. If nodes entries are objects with an id field rather than plain strings, extract just the id values into nodeIds. 3. Synthesize missing IDs: If any layer is missing an id, generate one as layer:<kebab-case-name>. 4. Convert file paths: If nodeIds entries are raw file paths without a known prefix (file:, config:, document:, service:, pipeline:, table:, schema:, resource:, endpoint:), convert them to file:<relative-path>. 5. Drop dangling refs: Remove any nodeIds entries that do not exist in the merged node set.

Each element of the final layers array MUST have this shape:

[
  {
    "id": "layer:<kebab-case-name>",
    "name": "<layer name>",
    "description": "<what belongs in this layer>",
    "nodeIds": ["file:src/App.tsx", "config:tsconfig.json", "document:README.md"]
  }
]

All four fields (id, name, description, nodeIds) are required.

For incremental updates: Always re-run architecture analysis on the full merged node set, since layer assignments may shift when files change.

Context for incremental updates: When re-running architecture analysis, also inject the previous layer definitions:

Previous layer definitions (for naming consistency):

```json

[previous layers from existing graph]

```

>

Maintain the same layer names and IDs where possible. Only add/remove layers if the file structure has materially changed.

---

Phase 5 — TOUR

Report to the user: [Phase 5/7] Building guided tour...

Dispatch a subagent using the tour-builder agent definition (at agents/tour-builder.md). Append the following additional context:

Additional context from main session:

>

Project README (first 3000 chars):

```

$README_CONTENT

```

>

Project entry point: $ENTRY_POINT

>

Use the README to align the tour narrative with the project's own documentation. Start the tour from the entry point if one was detected. The tour should tell the same story the README tells, but through the lens of actual code structure.

>

$LANGUAGE_DIRECTIVE

Pass these parameters in the dispatch prompt:

Create a guided learning tour for this codebase.

Project root: $PROJECT_ROOT

Write output to: $PROJECT_ROOT/.understand-anything/intermediate/tour.json

Project: <projectName> — <projectDescription>

Languages: <languages>

>

Nodes (all file-level nodes — includes code files, config, document, service, pipeline, table, schema, resource, endpoint):

```json

[list of {id, name, filePath, summary, type} for ALL file-level nodes — do NOT include function or class nodes]

```

>

Layers:

```json

[list of {id, name, description} for each layer — omit nodeIds]

```

>

Edges (all types — includes imports, calls, configures, documents, deploys, triggers, etc.):

```json

[list of ALL edges — include all edge types for complete graph topology analysis]

```

After the subagent completes, read $PROJECT_ROOT/.understand-anything/intermediate/tour.json and normalize it into a final tour array. Apply these steps in order:

1. Unwrap envelope: If the file contains { "steps": [...] } instead of a plain array, extract the inner array. (The prompt requests a plain array, but LLMs may still produce an envelope.) 2. Rename legacy fields: If any step has nodesToInspect instead of nodeIds, rename it → nodeIds. If any step has whyItMatters instead of description, rename it → description. 3. Convert file paths: If nodeIds entries are raw file paths without a known prefix (file:, config:, document:, service:, pipeline:, table:, schema:, resource:, endpoint:), convert them to file:<relative-path>. 4. Drop dangling refs: Remove any nodeIds entries that do not exist in the merged node set. 5. Sort by order before saving.

Each element of the final tour array MUST have this shape:

[
  {
    "order": 1,
    "title": "Project Overview",
    "description": "Start with the README to understand the project's purpose and architecture.",
    "nodeIds": ["document:README.md"]
  },
  {
    "order": 2,
    "title": "Application Entry Point",
    "description": "This step explains how the frontend boots and mounts.",
    "nodeIds": ["file:src/main.tsx", "file:src/App.tsx"]
  }
]

Required fields: order, title, description, nodeIds. Preserve optional languageLesson when present.

---

Phase 6 — REVIEW

Report to the user: [Phase 6/7] Validating knowledge graph...

Assemble the full KnowledgeGraph JSON object:

{
  "version": "1.0.0",
  "project": {
    "name": "<projectName>",
    "languages": ["<languages>"],
    "frameworks": ["<frameworks>"],
    "description": "<projectDescription>",
    "analyzedAt": "<ISO 8601 timestamp>",
    "gitCommitHash": "<commit hash from Phase 0>"
  },
  "nodes": [<all nodes from assembled-graph.json after Phase 3 review>],
  "edges": [<all edges from assembled-graph.json after Phase 3 review>],
  "layers": [<layers from Phase 4>],
  "tour": [<steps from Phase 5>]
}

1. Before writing the assembled graph, validate that:

• layers is an array of objects with these required fields: id, name, description, nodeIds
• tour is an array of objects with these required fields: order, title, description, nodeIds
• tour[*].languageLesson is allowed as an optional string field
• Every layers[*].nodeIds entry exists in the merged node set
• Every tour[*].nodeIds entry exists in the merged node set

If validation fails, automatically normalize and rewrite the graph into this shape before saving. If the graph still fails final validation after the normalization pass, save it with warnings but mark dashboard auto-launch as skipped.

2. Write the assembled graph to $PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json.

3. Check `$ARGUMENTS` for `--review` flag. Then run the appropriate validation path:

---

Default path (no --review): inline deterministic validation

Write the following Node.js script to $PROJECT_ROOT/.understand-anything/tmp/ua-inline-validate.cjs:

#!/usr/bin/env node
const fs = require('fs');
const graphPath = process.argv[2];
const outputPath = process.argv[3];
try {
  const graph = JSON.parse(fs.readFileSync(graphPath, 'utf8'));
  const issues = [], warnings = [];
  if (!Array.isArray(graph.nodes)) { issues.push('graph.nodes is missing or not an array'); graph.nodes = []; }
  if (!Array.isArray(graph.edges)) { issues.push('graph.edges is missing or not an array'); graph.edges = []; }
  const nodeIds = new Set();
  const seen = new Map();
  graph.nodes.forEach((n, i) => {
    if (!n.id) { issues.push(`Node[${i}] missing id`); return; }
    if (!n.type) issues.push(`Node[${i}] '${n.id}' missing type`);
    if (!n.name) issues.push(`Node[${i}] '${n.id}' missing name`);
    if (!n.summary) issues.push(`Node[${i}] '${n.id}' missing summary`);
    if (!n.tags || !n.tags.length) issues.push(`Node[${i}] '${n.id}' missing tags`);
    if (seen.has(n.id)) issues.push(`Duplicate node ID '${n.id}' at indices ${seen.get(n.id)} and ${i}`);
    else seen.set(n.id, i);
    nodeIds.add(n.id);
  });
  graph.edges.forEach((e, i) => {
    if (!nodeIds.has(e.source)) issues.push(`Edge[${i}] source '${e.source}' not found`);
    if (!nodeIds.has(e.target)) issues.push(`Edge[${i}] target '${e.target}' not found`);
  });
  const fileLevelTypes = new Set(['file', 'config', 'document', 'service', 'pipeline', 'table', 'schema', 'resource', 'endpoint']);
  const fileNodes = graph.nodes.filter(n => fileLevelTypes.has(n.type)).map(n => n.id);
  const assigned = new Map();
  if (!Array.isArray(graph.layers)) { if (graph.layers) warnings.push('graph.layers is not an array'); graph.layers = []; }
  if (!Array.isArray(graph.tour)) { if (graph.tour) warnings.push('graph.tour is not an array'); graph.tour = []; }
  graph.layers.forEach(layer => {
    (layer.nodeIds || []).forEach(id => {
      if (!nodeIds.has(id)) issues.push(`Layer '${layer.id}' refs missing node '${id}'`);
      if (assigned.has(id)) issues.push(`Node '${id}' appears in multiple layers`);
      assigned.set(id, layer.id);
    });
  });
  fileNodes.forEach(id => {
    if (!assigned.has(id)) issues.push(`File node '${id}' not in any layer`);
  });
  graph.tour.forEach((step, i) => {
    (step.nodeIds || []).forEach(id => {
      if (!nodeIds.has(id)) issues.push(`Tour step[${i}] refs missing node '${id}'`);
    });
  });
  const withEdges = new Set([
    ...graph.edges.map(e => e.source),
    ...graph.edges.map(e => e.target)
  ]);
  graph.nodes.forEach(n => {
    if (!withEdges.has(n.id)) warnings.push(`Node '${n.id}' has no edges (orphan)`);
  });
  const stats = {
    totalNodes: graph.nodes.length,
    totalEdges: graph.edges.length,
    totalLayers: graph.layers.length,
    tourSteps: graph.tour.length,
    nodeTypes: graph.nodes.reduce((a, n) => { a[n.type] = (a[n.type]||0)+1; return a; }, {}),
    edgeTypes: graph.edges.reduce((a, e) => { a[e.type] = (a[e.type]||0)+1; return a; }, {})
  };
  fs.writeFileSync(outputPath, JSON.stringify({ issues, warnings, stats }, null, 2));
  process.exit(0);
} catch (err) { process.stderr.write(err.message + '\n'); process.exit(1); }

Execute it:

node $PROJECT_ROOT/.understand-anything/tmp/ua-inline-validate.cjs \
  "$PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json" \
  "$PROJECT_ROOT/.understand-anything/intermediate/review.json"

If the script exits non-zero, read stderr, fix the script, and retry once.

---

--review path: full LLM reviewer

If --review IS in $ARGUMENTS, dispatch the LLM graph-reviewer subagent as follows:

Dispatch a subagent using the graph-reviewer agent definition (at agents/graph-reviewer.md). Append the following additional context:

Additional context from main session:

>

Phase 1 scan results (file inventory):

```json

[list of {path, sizeLines} from scan-result.json]

```

>

Phase warnings/errors accumulated during analysis:

- [list any batch failures, skipped files, or warnings from Phases 2-5]

>

Cross-validate: every file in the scan inventory should have a corresponding node in the graph (node types may vary: file:, config:, document:, service:, pipeline:, table:, schema:, resource:, endpoint:). Flag any missing files. Also flag any graph nodes whose filePath doesn't appear in the scan inventory.

Pass these parameters in the dispatch prompt:

Validate the knowledge graph at $PROJECT_ROOT/.understand-anything/intermediate/assembled-graph.json.

Project root: $PROJECT_ROOT

Read the file and validate it for completeness and correctness.

Write output to: $PROJECT_ROOT/.understand-anything/intermediate/review.json

---

4. Read $PROJECT_ROOT/.understand-anything/intermediate/review.json.

5. If `issues` array is non-empty:

• Review the issues list
• Apply automated fixes where possible:
• Remove edges with dangling references
• Fill missing required fields with sensible defaults (e.g., empty tags -> ["untagged"], empty summary -> "No summary available")
• Remove nodes with invalid types
• Re-run the final graph validation after automated fixes
• If critical issues remain after one fix attempt, save the graph anyway but include the warnings in the final report and mark dashboard auto-launch as skipped

6. If `issues` array is empty: Proceed to Phase 7.

---

Phase 7 — SAVE

Report to the user: [Phase 7/7] Saving knowledge graph...

1. Write the final knowledge graph to $PROJECT_ROOT/.understand-anything/knowledge-graph.json.

2. Generate structural fingerprints baseline. This creates the basis for future automatic incremental updates and must succeed before `meta.json` is written — otherwise auto-update sees a fresh commit hash with no fingerprints to compare against, classifies every file as STRUCTURAL, and escalates to FULL_UPDATE on every subsequent commit (issue #152).

Write the input file:

   cat > $PROJECT_ROOT/.understand-anything/intermediate/fingerprint-input.json <<EOF
   {
     "projectRoot": "$PROJECT_ROOT",
     "sourceFilePaths": [<all source file paths from Phase 1, as JSON array>],
     "gitCommitHash": "<current commit hash>"
   }
   EOF

Then invoke the bundled script (located next to this SKILL.md):

   node <SKILL_DIR>/build-fingerprints.mjs \
     $PROJECT_ROOT/.understand-anything/intermediate/fingerprint-input.json

The script uses TreeSitterPlugin + PluginRegistry exactly like extract-structure.mjs, so the baseline matches the comparison logic used during auto-updates.

If the script exits non-zero or stdout does not include `Fingerprints baseline:`, abort Phase 7 and report the error. Do NOT proceed to step 3 (writing `meta.json`).

3. Write metadata to $PROJECT_ROOT/.understand-anything/meta.json (only after step 2 succeeded):

   {
     "lastAnalyzedAt": "<ISO 8601 timestamp>",
     "gitCommitHash": "<commit hash>",
     "version": "1.0.0",
     "analyzedFiles": <number of files analyzed>
   }

4. Clean up intermediate files, preserving `scan-result.json` so future incremental runs can skip Phase 1 SCAN (see issue #293). We mv scratch dirs into a timestamped .trash-* instead of rm -rfing them directly — this avoids tripping destructive-action gates on hardened hosts (e.g. freshness-window checks) that flag deleting directories created moments earlier (see issue #301). The delayed-purge step in Phase 0 reclaims the space once the trash is older than 7 days.

   # Preserve scan-result.json — Phase 1's deterministic file inventory.
   # Future incremental runs (Phase 2 compute-batches.mjs --changed-files=…)
   # need this inventory; without it, Phase 1 must re-dispatch and pay ~157k
   # tokens / ~158s per incremental run.
   TRASH="$PROJECT_ROOT/.understand-anything/.trash-$(date +%s)"
   mkdir -p "$TRASH"
   INTER="$PROJECT_ROOT/.understand-anything/intermediate"
   if [ -d "$INTER" ]; then
     # Move every entry except scan-result.json into the trash dir.
     find "$INTER" -mindepth 1 -maxdepth 1 -not -name 'scan-result.json' -exec mv {} "$TRASH/" \; 2>/dev/null || true
   fi
   mv "$PROJECT_ROOT/.understand-anything/tmp" "$TRASH/" 2>/dev/null || true

5. Report a summary to the user containing:

• Project name and description
• Files analyzed / total files (with breakdown by fileCategory: code, config, docs, infra, data, script, markup)
• Nodes created (broken down by type: file, function, class, config, document, service, table, endpoint, pipeline, schema, resource)
• Edges created (broken down by type)
• Layers identified (with names)
• Tour steps generated (count)
• Any warnings from the reviewer
• Path to the output file: $PROJECT_ROOT/.understand-anything/knowledge-graph.json

6. Only automatically launch the dashboard by invoking the /understand-dashboard skill if final graph validation passed after normalization/review fixes. If final validation did not pass, report that the graph was saved with warnings and dashboard launch was skipped.

---

Error Handling

• If any subagent dispatch fails, retry once with the same prompt plus additional context about the failure.
• Track all warnings and errors from each phase in a $PHASE_WARNINGS list. When using --review, pass this list to the graph-reviewer in Phase 6. On the default path, include accumulated warnings in the Phase 7 final report.
• If it fails a second time, skip that phase and continue with partial results.
• ALWAYS save partial results — a partial graph is better than no graph.
• Report any skipped phases or errors in the final summary so the user knows what happened.
• NEVER silently drop errors. Every failure must be visible in the final report.

---

Reference: KnowledgeGraph Schema

Node Types (13 total)

Edge Types (26 total)

Edge Weight Conventions

Django Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Django is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

Django Project Structure

When analyzing a Django project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

URL routing graph — Create calls edges from urls.py nodes to their corresponding view nodes when path() or re_path() maps a URL pattern to a view function or class. These edges represent the HTTP routing chain.

Signal wiring — When signals.py uses post_save.connect(handler, sender=Model) or @receiver(post_save, sender=Model), create subscribes edges from the signal handler function to the model class. Create publishes edges from the model to the signal handler to show the trigger direction.

ORM relationships — When models.py defines ForeignKey, OneToOneField, or ManyToManyField, create depends_on edges between the model classes with a description indicating the relationship type and cardinality.

Serializer-to-model binding — When a DRF serializer has model = MyModel in its Meta class, create a depends_on edge from the serializer to the model.

View-to-serializer binding — When a DRF ViewSet or APIView references a serializer class, create a depends_on edge from the view to the serializer.

Architectural Layers for Django

Assign nodes to these layers when detected:

Notable Patterns to Capture in languageLesson

• Fat models vs. thin views: Django encourages business logic in model methods, keeping views thin HTTP adapters
• Django ORM lazy evaluation: QuerySets are not evaluated until iterated — chain filters without DB hits
• Class-based views (CBVs): Mixins like LoginRequiredMixin, PermissionRequiredMixin compose behavior through multiple inheritance
• Signal anti-patterns: Signals create invisible coupling; a signal in signals.py may be triggered by a save() call anywhere in the codebase
• App isolation: Each Django app (INSTALLED_APPS) should be self-contained with its own models, views, urls, and migrations

Express Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Express is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

Express Project Structure

When analyzing an Express project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

Route mounting — When app.use('/api/users', usersRouter) mounts a router, create depends_on edges from the main app to the router module. These edges represent the HTTP routing tree.

Middleware chain — When app.use(cors()), app.use(authMiddleware), or router.use(validate) registers middleware, create middleware edges from the app or router to the middleware function. Order matters — middleware executes in registration order.

Controller-to-service calls — When a controller imports and calls a service function, create depends_on edges from the controller to the service. This represents the separation between HTTP handling and business logic.

Model relationships — When models reference each other (Mongoose ref, Sequelize associations), create depends_on edges between model files with descriptions indicating the relationship type.

Architectural Layers for Express

Assign nodes to these layers when detected:

Notable Patterns to Capture in languageLesson

• Middleware chain (req, res, next): Express processes requests through a pipeline of middleware functions — each receives the request, response, and a next() callback to pass control forward
• Error-handling middleware (4 params): Middleware with signature (err, req, res, next) catches errors — must be registered after all routes to act as a global error handler
• Router modularity: express.Router() creates modular, mountable route handlers that can be composed into the main app at different path prefixes
• MVC pattern: Express apps commonly separate concerns into Models (data), Views (response formatting), and Controllers (request handling)
• Body parsing and validation: Request body parsing (express.json(), express.urlencoded()) and validation (Joi, Zod, express-validator) are middleware concerns applied before route handlers

FastAPI Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when FastAPI is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

FastAPI Project Structure

When analyzing a FastAPI project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

Router inclusion chain — When app.include_router(some_router, prefix="/api") appears in main.py or a router aggregator, create imports + depends_on edges from the main app file to each router module. This builds the URL hierarchy graph.

Dependency injection tree — When a route function or another Depends() provider imports and calls Depends(some_function), create depends_on edges from the caller to the dependency provider. Trace these chains — they often span multiple files (e.g., route → auth dependency → DB session dependency).

Pydantic model inheritance — When a schema class inherits from another (e.g., class UserCreate(UserBase)), create inherits edges between the schema class nodes.

ORM model relationships — When SQLAlchemy models use relationship(), ForeignKey, create depends_on edges between the model classes.

CRUD-to-model binding — When a crud.py function takes a model type as an argument or directly references a model class, create depends_on edges from the CRUD file to the model file.

Architectural Layers for FastAPI

Notable Patterns to Capture in languageLesson

• Dependency injection as composition: FastAPI's Depends() is a first-class DI system — a route can declare any number of dependencies, each of which can have their own dependencies, forming a tree resolved at request time
• Pydantic for validation: Request bodies, query params, and path params are automatically validated by Pydantic — invalid input raises 422 Unprocessable Entity before your code runs
• Async endpoints: async def routes run in the event loop; def routes run in a threadpool — mixing them incorrectly can cause performance issues
• Path operation order: FastAPI matches routes in declaration order; a catch-all route before a specific one will shadow it

Flask Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Flask is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

Flask Project Structure

When analyzing a Flask project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

Blueprint registration — When app.register_blueprint(bp, url_prefix='/api') appears in the application factory, create depends_on edges from the app factory to each blueprint module.

Extension coupling — When a view imports from extensions.py (e.g., from .extensions import db, login_manager), create imports edges to show which views depend on which extensions.

Before/after request hooks — When @app.before_request or @blueprint.before_request decorates a function, create middleware edges from those functions to the app/blueprint they attach to.

Architectural Layers for Flask

Notable Patterns to Capture in languageLesson

• Application factory pattern: create_app() functions allow multiple app instances (e.g., for testing) and delay extension initialization — avoids circular imports
• Blueprint modularity: Blueprints group related routes, templates, and static files; they are registered on the app with a URL prefix, making them independently testable
• Flask extension protocol: Extensions follow init_app(app) for lazy initialization — the extension object is created globally but bound to an app instance later

Gin (Go) Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Gin is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

Gin Project Structure

When analyzing a Gin project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

Route group registration — When r.Group("/api") creates a route group and registers handlers, create configures edges from the route definition file to each handler. Route groups organize endpoints by prefix and shared middleware.

Handler-to-service calls — When a handler function calls a service method, create depends_on edges from the handler to the service. This represents the separation between HTTP handling and business logic.

Service-to-repository calls — When a service calls a repository method for data access, create depends_on edges from the service to the repository. This represents the data access abstraction.

Middleware chaining — When r.Use(middleware) or a route group applies middleware, create middleware edges from the router or group to the middleware function. Middleware executes in registration order.

Architectural Layers for Gin

Assign nodes to these layers when detected:

Notable Patterns to Capture in languageLesson

• Handler functions with gin.Context: Every Gin handler receives a *gin.Context parameter — it provides request parsing (c.Bind, c.Param, c.Query), response writing (c.JSON, c.HTML), and control flow (c.Abort, c.Next)
• Middleware chain with c.Next(): Middleware calls c.Next() to pass control to the next handler in the chain — code before c.Next() runs pre-handler, code after runs post-handler
• Route grouping for modular APIs: r.Group("/v1") creates modular sub-routers that can have their own middleware stack — enables versioning and access control at the group level
• Dependency injection via constructors (no framework DI): Go has no DI framework — dependencies are passed as constructor parameters (e.g., NewUserHandler(userService)) and stored as struct fields
• Interface-driven design for testability: Services and repositories are defined as interfaces — handlers depend on the interface, enabling mock implementations in tests
• Error handling with gin.Error: Gin collects errors via c.Error(err) — middleware can inspect c.Errors after handler execution to implement centralized error logging and response formatting

Next.js Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Next.js is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

Next.js Project Structure

When analyzing a Next.js project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

Layout nesting — When app/foo/layout.tsx wraps app/foo/page.tsx and app/foo/bar/page.tsx, create contains edges from the layout to the pages it wraps. Layouts compose via the file-system hierarchy.

API route handlers — When a route.ts file exports named functions (GET, POST, PUT, DELETE), create edges from consuming components or server actions to the route handler based on fetch calls.

Server/Client component boundary — Files with "use client" directive at the top are Client Components. All other components in the app/ directory are Server Components by default. Create depends_on edges that cross this boundary and note the boundary in the edge description.

Parallel routes — When app/@slot/page.tsx patterns appear, create contains edges from the parent layout to each parallel slot. These render simultaneously in the same layout.

Route groups — Directories wrapped in parentheses (group) organize routes without affecting the URL path. Note these in node descriptions.

Architectural Layers for Next.js

Assign nodes to these layers when detected:

Notable Patterns to Capture in languageLesson

• Server Components by default: Components in the app/ directory are Server Components — no JavaScript is sent to the client unless "use client" is declared
• Server Actions for mutations: Functions marked with "use server" can be called directly from client components, replacing traditional API routes for form submissions and mutations
• App Router file conventions: Special files (page, layout, loading, error, not-found, route) define behavior by naming convention within the file-system router
• ISR and static generation: generateStaticParams pre-renders pages at build time; revalidation strategies control cache freshness
• Parallel and intercepting routes: @slot directories enable parallel rendering; (.) prefix directories enable route interception for modal patterns

Ruby on Rails Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Rails is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

Rails Project Structure

When analyzing a Ruby on Rails project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

Route-to-controller mapping — When config/routes.rb defines resources :users or get '/foo', to: 'bar#baz', create configures edges from the routes file to the corresponding controller. RESTful resources generate a full set of action mappings.

ActiveRecord associations — When models define has_many, belongs_to, has_one, or has_and_belongs_to_many, create depends_on edges between model files with descriptions indicating the association type and direction.

Controller-to-model — When a controller calls model methods (User.find, @post.save), create depends_on edges from the controller to the model. Controllers are the primary consumers of model data.

Callbacks — When models or controllers use before_action, after_save, before_validation, or similar callbacks, note these as middleware-like edges. Callbacks create implicit execution paths that are not visible from the call site.

Architectural Layers for Rails

Assign nodes to these layers when detected:

Notable Patterns to Capture in languageLesson

• Convention over configuration: Rails derives routing, table names, and file locations from naming conventions — UsersController maps to users_controller.rb, handles /users, and queries the users table
• ActiveRecord pattern: Models are database wrappers — each model class maps to a table, instances map to rows, and attributes map to columns with automatic type coercion
• Concerns for shared behavior: ActiveSupport::Concern modules are mixins included in models or controllers to share validations, scopes, callbacks, and methods across classes
• Strong parameters for mass-assignment protection: params.require(:user).permit(:name, :email) whitelists attributes — controllers must explicitly declare which fields can be set from user input
• RESTful resource routing: resources :posts generates seven standard CRUD routes — Rails strongly encourages RESTful design where each controller maps to a resource
• Callbacks and observers: before_save, after_create, and similar callbacks inject logic into the object lifecycle — they create invisible execution paths that can be difficult to trace

React Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when React is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

React Project Structure

When analyzing a React project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

Component composition — When a parent component renders a child component in its JSX return, create contains edges from the parent to the child. These edges represent the component tree hierarchy.

Hook usage — When a component or hook imports and calls a custom hook (useX), create depends_on edges from the consumer to the hook module. Hooks are the primary mechanism for shared logic in React.

Context provider/consumer — When a Context provider wraps components, create publishes edges from the provider to the context definition. When components call useContext or use a custom context hook, create subscribes edges from the consumer to the context.

Props drilling chains — When props are passed through multiple component layers without being used, create depends_on edges along the chain to surface the coupling depth.

Architectural Layers for React

Assign nodes to these layers when detected:

Notable Patterns to Capture in languageLesson

• Component composition over inheritance: React favors composing components via props and children rather than class inheritance hierarchies
• Custom hooks for reusable logic: Hooks prefixed with use extract stateful logic into shareable modules without changing the component tree
• React.memo for performance: Components wrapped in React.memo skip re-renders when props are unchanged — indicates performance-sensitive paths
• Controlled vs. uncontrolled components: Controlled components derive state from props; uncontrolled components manage internal state via refs
• Render props pattern: Components that accept a function as children or a render prop to delegate rendering decisions to the consumer

Spring Boot Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Spring Boot is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

Spring Boot Project Structure

When analyzing a Spring Boot project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

@Autowired injection — When a class injects a dependency via @Autowired, constructor injection, or @Inject, create depends_on edges from the consumer to the injected bean. Constructor injection is preferred and most common in modern Spring.

Controller-Service-Repository chain — The canonical call chain is @RestController -> @Service -> @Repository. Create depends_on edges along this chain to show the layered architecture.

@Entity relationships — When entities define @OneToMany, @ManyToOne, @OneToOne, or @ManyToMany annotations, create depends_on edges between entity classes with descriptions indicating the relationship type and direction.

@Configuration bean definitions — When a @Configuration class defines @Bean methods, create configures edges from the configuration class to the types it produces. These beans become available for injection throughout the application.

Architectural Layers for Spring Boot

Assign nodes to these layers when detected:

Notable Patterns to Capture in languageLesson

• Dependency injection via constructor injection: Spring favors constructor injection over field injection (@Autowired on fields) — it makes dependencies explicit, supports immutability, and simplifies testing
• Layered architecture (Controller -> Service -> Repository): Spring Boot applications follow a strict layered pattern where controllers handle HTTP, services contain business logic, and repositories manage persistence
• Spring Security filter chain: Security is implemented as a chain of servlet filters — SecurityFilterChain beans configure authentication, authorization, CORS, and CSRF protection
• JPA entity lifecycle: Entities transition through states (transient, managed, detached, removed) — understanding this lifecycle is essential for tracing data flow through the persistence layer
• AOP for cross-cutting concerns: @Aspect classes with @Before, @After, and @Around advice inject behavior at join points — used for logging, transactions (@Transactional), and caching (@Cacheable)

Vue Framework Addendum

Injected into file-analyzer and architecture-analyzer prompts when Vue is detected.

Do NOT use as a standalone prompt — always appended to the base prompt template.

Vue Project Structure

When analyzing a Vue project, apply these additional conventions on top of the base analysis rules.

Canonical File Roles

Edge Patterns to Look For

Component parent-child — When a parent component uses a child component in its <template>, create contains edges from the parent to the child. Template refs and slot usage further indicate composition relationships.

Composable usage — When a component or composable imports and calls a useX function, create depends_on edges from the consumer to the composable module. Composables are the primary mechanism for shared stateful logic.

Store actions/getters — When components or composables import and use a Pinia store (useXStore()), create depends_on edges from the consumer to the store. Store-to-store dependencies should also be captured.

Router view mapping — When router/index.ts maps paths to view components, create configures edges from the router to each view component. Navigation guards add middleware-like edges.

Plugin registration — When main.ts calls app.use(plugin), create configures edges from the bootstrap file to each plugin.

Architectural Layers for Vue

Assign nodes to these layers when detected: