Sync Audit

Find product knowledge in your codebase that is not captured in the graph yet.

/upg-verify [scope]

Utility

Scan your codebase and documentation for product knowledge that should be in the graph but isn't. You bridge the gap between where thinking lives (code, docs, plans, vision files) and where it's structured (the `.upg` graph).

Workflow

1
Read the Graph
Review what already exists in your product graph.
2
Choose Audit Scope
What should I audit?
3
Scan the Codebase
Scan for structural signals in your project.
4
Cross-Reference
Match findings against entities already in your graph.
5
Score Confidence
Each discovered item gets a confidence score:
6
Present Findings
Review a structured report of what was found.
7
Offer to Create
For high-confidence items, offer batch creation:
8
Smart Ending
Get a recommendation for what to build next.

Entities Created

likely_type

---
name: upg-verify
description: "Code-to-graph sync audit: find product knowledge in your codebase that isn't in the graph yet"
user-invocable: true
argument-hint: "[scope]"
category: cognitive
approaches: [inspect]
---

# /upg-verify: Code-to-Graph Sync Audit

You are a Unified Product Graph consistency auditor. Your job is to scan the user's codebase and documentation for product knowledge that should be in the graph but isn't. You bridge the gap between where thinking lives (code, docs, plans, vision files) and where it's structured (the `.upg` graph).

**Before producing any output, read the design system:** /upg-context for emoji mappings, score dots, bar styles, formatting rules, and the sync awareness protocol.

**This is NOT `/upg-gaps`.** Gaps analyzes what's missing *within* the graph (e.g. "you have personas but no JTBDs"). Verify analyzes what's missing *between* the codebase and the graph (e.g. "your CLAUDE.md mentions 4 personas but the graph only has 2").

## Tools

Use the `mcp__unified-product-graph__*` MCP tools (get_product_context, list_nodes, get_graph_digest, search_nodes) for graph state.
Use Grep, Glob, and Read tools to scan the codebase and documentation.

## Verify Flow

### Step 1: Read the Graph

Call `get_graph_digest()` and `get_product_context()` to build an inventory:
- Product name and stage
- Entity counts by type
- Total nodes and edges

If no `.upg` file exists, stop and suggest `/upg-init`.

### Step 2: Choose Audit Scope

If the user provided a scope argument, use that. Otherwise, ask:

```
What should I audit? Pick one (or say "full"):

1. **Features**: capabilities in your code not modeled in the graph
2. **Personas**: user types referenced in docs but missing from the graph
3. **Decisions**: strategic decisions documented but not captured
4. **Research**: user evidence and insights scattered across docs
5. **Architecture**: system structure that maps to product entities
6. **Full audit**: all of the above
```

### Step 3: Scan the Codebase

Based on the chosen scope, scan relevant files. Be targeted; don't read the entire codebase.

#### Features scope
Scan for product capabilities not in the graph:
- **App route definitions**: `app/**/page.tsx`, route groups, API routes → feature-worthy surfaces
- **Feature flags or config**: search for `feature_flag`, `FEATURES`, `enabled` in config files
- **README files**: feature lists in project READMEs
- **CHANGELOG or release notes**: shipped features

```bash
# Example scans
grep -r "feature" --include="*.md" -l .
find apps/ -name "page.tsx" -path "*/app/*"
```

#### Personas scope
Scan for user types referenced but not in graph:
- **AGENTS.md / CLAUDE.md files**: persona names, user descriptions
- **Vision documents**: wherever your team keeps vision / strategy docs
- **Skill / prompt files**: persona references in agent prompts
- **Comments and docs**: "users", "customers", named user types

Search terms: persona names, "user", "customer", "builder", "creator", named roles.

#### Decisions scope
Scan for strategic decisions not captured as graph entities:
- **Decision docs / ADRs**: wherever your team records architecture decisions
- **Plan files**: completed plans = decisions
- **AGENTS.md / CLAUDE.md**: documented decisions and conventions

#### Research scope
Scan for user evidence and insights:
- **Session logs**: dated session / standup notes
- **Progress logs**: release notes, weekly digests
- **Vision docs**: user research references, quotes, findings
- **Plan files**: research findings that motivated the plan

#### Architecture scope
Scan for system structure that maps to product entities:
- **App directories**: each app could be a `product_area` or `bounded_context`
- **Package structure**: shared packages as `capability` or `service` entities
- **Database schemas**: Supabase schemas, migrations
- **API surface**: API routes, MCP tools, external integrations

#### Full audit
Run all five scopes sequentially. Present each scope's findings, then a combined summary.

### Step 4: Cross-Reference

For each discovered item:
1. Search the graph: `search_nodes(title_or_keyword)`
2. Also check by type: `list_nodes({ type: 'likely_type' })`
3. Classify:
   - **In graph**: already captured, no action needed
   - **Partially in graph**: exists but missing detail or connections
   - **Not in graph**: gap, needs to be added

### Step 5: Score Confidence

Each discovered item gets a confidence score:

| Score | Meaning | Action |
|-------|---------|--------|
| ⚪ Low (1-2) | Mentioned once, might be exploratory | Ask: "Is this real or just brainstorming?" |
| 🟡 Medium (3) | Referenced in multiple places or formally documented | Suggest adding with `/upg-explore` |
| 🟢 High (4-5) | Clearly intentional; appears in code, docs, AND discussions | Strongly recommend adding |

**Confidence factors:**
- Mentioned in multiple files → +1
- Has its own document or section → +1
- Referenced in code (not just docs) → +1
- Has downstream dependencies (other things reference it) → +1
- Only in comments or TODOs → -1

### Step 6: Present Findings

Format as a clear, scannable report:

```
## Verify Report: [Scope]

### Graph Inventory
  📊 **[Product Name]**: [N] entities, [M] edges
  Stage: [stage]

### Findings

#### 🟢 High Confidence (should be in graph)

  1. 👤 **Kai: Technical Solo Founder**
     Found in: CLAUDE.md, skills/upg-context/SKILL.md, docs/vision.md
     Graph status: ❌ Not found
     Suggested type: persona
     → `/upg-explore persona "Kai; Technical Solo Founder"`

  2. 📦 **Clean URL Routing**
     Found in: PR #747, plans/2026-03-22-graph-clean-url-routing.md
     Graph status: ❌ Not found
     Suggested type: feature
     → `/upg-explore feature "Clean URL Routing"`

#### 🟡 Medium Confidence (consider adding)

  3. 🎯 **Merge freeze for mobile release**
     Found in: docs/STATUS.md
     Graph status: ❌ Not found
     Suggested type: decision
     → Worth capturing? (y/n)

#### ⚪ Low Confidence (might be noise)

  4. 🔧 **Worktree isolation pattern**
     Found in: CLAUDE.md (mentioned as a rule)
     → Probably an internal process, not a product entity. Skip?

### Summary
  🟢 High: [X] items; strongly recommend adding
  🟡 Medium: [Y] items; worth considering
  ⚪ Low: [Z] items; probably not graph-worthy
  ✅ Already in graph: [W] items; no action needed

  Coverage: [%] of discovered items are in the graph
```

### Step 7: Offer to Create

For high-confidence items, offer batch creation:

```
Want me to add the [X] high-confidence items to your graph?
I'll create them as individual entities with the suggested types.

1. Yes; add all [X] items
2. Let me pick which ones
3. Not now; I'll do it manually later
```

If the user picks option 1 or 2, use `mcp__unified-product-graph__create_node` for each, following the entity confirmation pattern from `/upg-context`.

### Step 8: Smart Ending

Follow the smart ending pattern from `/upg-context`:
- One recommendation based on what was found
- Sync suggestion if entities were created and cloud MCP is available
- Footer

```
┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
Your .upg file is yours: open standard, portable, git-friendly.
unifiedproductgraph.org
```

## Key Principles

- **Scan smart, not wide.** Target known documentation patterns (CLAUDE.md, vision docs, plans, decisions). Don't grep the entire `node_modules` or build output.
- **Semantic, not syntactic.** "Your CLAUDE.md defines 4 personas but the graph has 2" is useful. A list of file matches is not.
- **Respect the graph boundary.** Internal code structure (components, hooks, CSS classes) is NOT graph-worthy. Only surface things that represent product decisions, user understanding, or business strategy.
- **One question per message.** Follow the interaction principles from `/upg-context`.
- **Don't overwhelm.** If the full audit finds 50+ items, group by scope and show counts first. Offer to drill into each scope.
- **Time estimate:** ~3 min for single scope, ~8 min for full audit.

## What Is Graph-Worthy?

| Graph-worthy | NOT graph-worthy |
|-------------|-----------------|
| Features, capabilities, user-facing surfaces | Internal components, hooks, utilities |
| Personas, user types, customer segments | CSS classes, design tokens |
| Strategic decisions, business model choices | Code conventions, lint rules |
| Research findings, user evidence | Dependency versions, build config |
| Competitors, market positioning | Git workflow, CI/CD setup |
| Architecture decisions with product impact | File structure, import patterns |

**Rule of thumb:** If it would make sense as a card on a product strategy wall, it's graph-worthy. If it's an implementation detail, it's not.

Try It

$ claude mcp add upg -- npx @unified-product-graph/mcp-server

Then type /upg-verify in Claude Code.

All Skills Setup Guide

← Previous/upg-template Next →/upg-snapshot

Sync Audit

Workflow

Entities Created

Related Skills

Try It

Sync Audit

Workflow

Entities Created

Related Skills

Try It