ua-chat

name	ua-chat
description	Ask questions about a codebase using both the structural knowledge graph and the domain graph. Enhanced replacement for /understand-chat that includes business flow context.
argument-hint	["query"]

/ua-chat

Answers questions about this codebase using both .understand-anything/knowledge-graph.json and .understand-anything/domain-graph.json (when present). Provides structural file/function answers AND business-flow answers with step-by-step file pointers.

Graph Structure Reference

knowledge-graph.json:

• nodes[] — file, function, class, config, document, service, table, endpoint, pipeline, schema, resource nodes
• edges[] — imports, calls, contains, deploys, configures, documents, tested_by, etc.
• layers[] — architectural layer assignments
• tour[] — guided learning steps

domain-graph.json (optional):

• nodes[] — domain, flow, step nodes
• edges[] — contains_flow (domain→flow), flow_step (flow→step, weight=sequential order), cross_domain
• Step nodes have filePath and lineRange pointing to implementing code

How to Read Efficiently

1. Use Grep to search within JSON for relevant entries BEFORE reading the full file
2. Only read sections you need — don't dump the entire graph into context
3. Node names and summaries are the most useful fields for understanding
4. Edges tell you how components connect — follow imports and calls for dependency chains

Instructions

1. Staleness check (non-blocking — warn but continue):

   STORED=$(node -p "require('fs').existsSync('.understand-anything/meta.json') && JSON.parse(require('fs').readFileSync('.understand-anything/meta.json','utf8')).gitCommitHash || ''" 2>/dev/null || echo "")
   CURRENT=$(git rev-parse HEAD 2>/dev/null || echo "")
   [ -n "$STORED" ] && [ -n "$CURRENT" ] && [ "$STORED" != "$CURRENT" ] && echo "⚠️  Note: Knowledge graph may be stale. Run /ua-status for details."
   

2. Check graph exists:

   [ -f .understand-anything/knowledge-graph.json ] || { echo "No knowledge graph found. Run /understand first."; exit 1; }
   

3. Read project metadata — grep the top of knowledge-graph.json for the "project" section (name, description, languages, frameworks).

4. Search the structural graph for nodes matching the user's query: "$ARGUMENTS"

   • Search "name" fields: grep -i for query keywords
   • Search "summary" fields for semantic matches
   • Search "tags" arrays for topic matches
   • Note matched node IDs

5. Find structural edges — for each matched node ID, grep the edges section for that ID as source or target. Find upstream callers (target matches) and downstream dependencies (source matches).

6. Find structural layers — grep matched node IDs in the "layers" section to identify which architectural layers are touched.

7. Search the domain graph (if it exists):

   [ -f .understand-anything/domain-graph.json ] && DOMAIN_EXISTS=true || DOMAIN_EXISTS=
   

Example output structure when both graphs match

**{query topic}** is handled by:

**Structural view:**
- `src/checkout/controller.ts` (API layer) — handles HTTP POST /checkout requests
- `src/checkout/validator.ts` (Service layer) — validates cart contents

**Business Flow — Checkout Process:**
1. Validate cart → `src/checkout/validator.ts:38`
2. Apply promotions → `src/promotions/service.ts:112`
3. Charge payment → `src/payments/stripe.ts:89`
4. Send confirmation → `src/email/transactional.ts:44`