aoc-understand

name	aoc-understand
description	Use AOC's Understand-Anything bridge for repository knowledge graphs, onboarding, architecture questions, explain/chat flows, and dashboard exploration. This replaces legacy teach workflows.
allowed-tools	Bash(aoc-understand:*), Bash(test:*), Bash(python3:*), Bash(rg:*), Bash(grep:*)

AOC Understand

Use aoc-understand when the user wants to understand a repo, onboard, ask architecture questions, inspect graph relationships, explain a file/function, analyze code impact, or launch an interactive knowledge graph dashboard.

This is the umbrella Understand-Anything skill. Do not expose or require the upstream granular skills (understand, understand-chat, understand-dashboard, understand-diff, understand-domain, understand-explain, understand-knowledge, understand-onboard) in normal AOC skill inventory; route those modes through this skill instead.

Canonical flow

1. Check status:

   aoc-understand status
   

2. If Understand-Anything is not installed and the user explicitly wants setup:

   aoc-understand install
   

3. Build/update the graph through the umbrella flow:

   aoc-understand analyze --full
   # or invoke: /skill:aoc-understand analyze --full
   

4. Explore:

   aoc-understand dashboard --open
   aoc-understand chat "How does auth work?"
   aoc-understand explain src/file.ts
   aoc-understand onboard
   aoc-understand domain
   aoc-understand diff
   

5. Optional curated AOC Map bridge:

   aoc-understand map-sync
   aoc-map serve --open
   

Umbrella modes

Use the operator's requested mode to select the appropriate flow inside this skill:

• analyze / full / repo graph: run aoc-understand status, then aoc-understand analyze --full; follow the printed guidance.
• dashboard: run aoc-understand dashboard --open after a graph exists.
• chat QUERY: use aoc-understand chat "QUERY" and answer from graph slices/search results, not by loading the whole graph.
• explain TARGET: use aoc-understand explain TARGET plus targeted file/graph inspection.
• onboard: use aoc-understand onboard to produce a newcomer-oriented repo guide.
• domain: use aoc-understand domain for business/domain flow extraction.
• diff: use aoc-understand diff for change impact analysis.
• gaps: use aoc-understand gaps [focus] or /skill:aoc-gaps for the broader AOC gap audit workflow.

Mental model

• Understand-Anything owns the deep generated knowledge graph under .understand-anything/.
• AOC owns safe install/status/doctor/project-root routing through aoc-understand.
• AOC Map remains the curated offline visual microsite under .aoc/map/.
• Open Design remains the GUI design studio bridge through aoc-od.

Teach deprecation

Do not start new work with /teach, /teach-full, /teach-dive, or teach-workflow unless the operator explicitly asks to inspect legacy artifacts. Use aoc-understand instead.

Guardrails

• Do not run remote curl installers. Use aoc-understand install for explicit clone/update.
• Do not load the full .understand-anything/knowledge-graph.json into context. Search/slice it first.
• Do not delete .aoc/insight/; legacy teach notes may still be useful history.
• Treat aoc-understand map-sync as a curated bridge, not a replacement for the full dashboard.