understand-domain

name	understand-domain
description	Extract business domain knowledge from a codebase as constrained DomainAnalysisIR. The AstrBot runtime compiler turns that IR into the final domain graph.
argument-hint	["--full"]

/understand-domain

Extracts business domain knowledge — domains, business flows, and process steps — from a codebase as constrained DomainAnalysisIR. The AstrBot runtime compiler produces the final interactive horizontal flow graph after this skill returns.

How It Works

• If a knowledge graph already exists in the configured graph output root, derives domain knowledge from it (cheap, no file scanning)
• If no knowledge graph exists, performs a lightweight scan: file tree + entry point detection + sampled files
• Use --full flag to force a fresh scan even if a knowledge graph exists

Instructions

AstrBot SubAgent Dispatch

This skill runs as an AstrBot supervisor. Do not perform domain-analysis worker tasks directly in the supervisor context.

• Build the domain analyzer prompt input and call ua_run_subagent_role.
• Use role="domain-analyzer" and expected_output_path="$UA_GRAPH_ROOT/intermediate/domain-analysis.json".
• Continue only after the SubAgent tool returns.

Phase 0: Resolve PROJECT_ROOT

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. Ephemeral tool-managed worktrees can be removed after a session, so .understand-anything/ written there is destroyed when the session ends, taking the domain 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-domain] Detected git worktree at $PROJECT_ROOT"
      echo "[understand-domain] Redirecting output to main repo root: $MAIN_ROOT"
      echo "[understand-domain] (Set UNDERSTAND_NO_WORKTREE_REDIRECT=1 to keep PROJECT_ROOT as the worktree.)"
      PROJECT_ROOT="$MAIN_ROOT"
    fi
  fi
fi

Use $PROJECT_ROOT (not the bare CWD) for every reference to "the current project" / <project-root> in subsequent phases.

Set UA_GRAPH_ROOT to the host-provided graph output root. If the host did not provide one, set UA_GRAPH_ROOT="$PROJECT_ROOT/.understand-anything". Use $PROJECT_ROOT only for source files and git state. Use $UA_GRAPH_ROOT for every graph artifact, intermediate file, temp file, and domain IR output.

Phase 1: Detect Existing Graph

1. Check if $UA_GRAPH_ROOT/knowledge-graph.json exists
2. If it exists AND --full was NOT passed → proceed to Phase 3 (derive from graph)
3. Otherwise → proceed to Phase 2 (lightweight scan)

Phase 2: Lightweight Scan (Path 1)

The preprocessing script does NOT produce a domain graph — it produces raw material (file tree, entry points, exports/imports) so the domain-analyzer agent can focus on the actual domain analysis instead of spending dozens of tool calls exploring the codebase. Think of it as a cheat sheet: cheap Python preprocessing → expensive LLM gets a clean, small input → better results for less cost.

1. Run the preprocessing script bundled with this skill, passing $PROJECT_ROOT from Phase 0:

   python ./extract-domain-context.py "$PROJECT_ROOT" "$UA_GRAPH_ROOT"
   

   This outputs $UA_GRAPH_ROOT/intermediate/domain-context.json containing:
   • File tree (respecting .gitignore)
   • Detected entry points (HTTP routes, CLI commands, event handlers, cron jobs, exported handlers)
   • File signatures (exports, imports per file)
   • Code snippets for each entry point (signature + first few lines)
   • Project metadata (package.json, README, etc.)
2. Read the generated domain-context.json as context for Phase 4
3. Proceed to Phase 4

Phase 3: Derive from Existing Graph (Path 2)

1. Read $UA_GRAPH_ROOT/knowledge-graph.json
2. Format the graph data as structured context:
   • All nodes with their types, names, summaries, and tags
   • All edges with their types (especially calls, imports, contains)
   • All layers with their descriptions
   • Tour steps if available
3. This is the context for the domain analyzer — no file reading needed
4. Proceed to Phase 4

Phase 4: Domain Analysis

1. Read the domain-analyzer agent prompt from astrbot_adapter/prompts/agents/domain-analyzer.md
2. Build the SubAgent input from the domain-analyzer prompt + the context from Phase 2 or 3
3. Call ua_run_subagent_role with role="domain-analyzer" and expected_output_path="$UA_GRAPH_ROOT/intermediate/domain-analysis.json"
4. The SubAgent writes its output to $UA_GRAPH_ROOT/intermediate/domain-analysis.json

Phase 5: Hand Off to Runtime Compiler

1. Do not read, rewrite, validate, clean up, or transform $UA_GRAPH_ROOT/intermediate/domain-analysis.json after the SubAgent writes it.
2. Do not create or edit the final domain graph. The AstrBot runtime action compile_domain_ir validates domain-analysis.json, normalizes IDs, attaches provenance, writes domain-graph.json, and updates quality-report.json.
3. Report that DomainAnalysisIR has been produced and return control to the host runner.

Phase 6: Launch Dashboard

1. Do not launch the dashboard from inside the skill.
2. The host runner will finish only after runtime compilation succeeds. The user can then open the dashboard, which will detect domain-graph.json.