/understand-domain

/understand-domain

Extracts business domain knowledge — domains, business flows, and process steps — from a codebase and produces an interactive horizontal flow graph in the dashboard.

How It Works

• If a knowledge graph already exists (.ua/knowledge-graph.json, or the legacy .understand-anything/knowledge-graph.json when that directory is present), 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

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. Worktrees managed by Claude Code are ephemeral — the data directory (.ua/, or legacy .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.

Resolve the data directory $UA_DIR. All Understand-Anything artifacts live in the project's data directory. Resolve it once, now that $PROJECT_ROOT is known, and reuse $UA_DIR for every read and write in later phases: