ua-chat

/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=false
   

   If DOMAIN_EXISTS is true:

   • Grep domain-graph.json "name" and "summary" fields for the query keywords
   • For any matched flow node (type "flow"): find all flow_step edges with that flow as source, then retrieve the step nodes they point to — sorted by edge weight (weight encodes order: 0.1=first, 0.2=second, etc.)
   • Step nodes carry filePath and optionally lineRange — include these as direct code pointers

8. Answer the query combining both result sets:

   • Lead with structural answer (files, functions, layers affected)
   • If domain results found, add a Business Flow section showing the ordered steps with file+line pointers
   • Format flow steps as a numbered sequence: 1. {step.name} — {step.summary} → \{step.filePath}:{step.lineRange[0]}``
   • Reference specific node IDs, file paths, and layer names from the graph data

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`