reflect-status

Reflect: Status - Metrics & Review

Show the current state of the reflect system: metrics, pending reviews, sidecar coverage, and GraphRAG health. Also handles review of pending low-confidence items.

When to Use

• To check how many learnings have been captured
• To review pending low-confidence items
• To audit sidecar coverage (find knowledge notes missing sidecars)
• To check GraphRAG health (node/edge counts)
• To see which agents have been updated most

Status View

When invoked, display the following sections:

1. Reflect State

python {{HOME_TOOL_DIR}}/skills/reflect/scripts/state_manager.py status

Shows:

• Auto-reflect: enabled/disabled
• Last reflection: timestamp
• Pending reviews: count

2. Aggregate Metrics

python {{HOME_TOOL_DIR}}/skills/reflect/scripts/metrics_updater.py --show

Shows:

• Sessions analyzed
• Total signals detected
• Changes proposed / accepted (acceptance rate)
• Skills created
• Estimated time saved
• Confidence breakdown (high/medium/low)
• Most updated agents (top 5)

3. Sidecar Coverage

Check how many knowledge notes have entity sidecars:

# Count knowledge notes
NOTES=$(find docs/solutions -name "*.md" -not -name "README.md" 2>/dev/null | wc -l | tr -d ' ')

# Count sidecars
SIDECARS=$(find docs/solutions -name "*.entities.yaml" 2>/dev/null | wc -l | tr -d ' ')

# Find notes missing sidecars
for md in $(find docs/solutions -name "*.md" -not -name "README.md" 2>/dev/null); do
    sidecar="${md%.md}.entities.yaml"
    if [[ ! -f "$sidecar" ]]; then
        echo "MISSING: $md"
    fi
done

Display:

Sidecar Coverage: 15/18 (83%)
Missing sidecars:
  - docs/solutions/build-errors/webpack-chunk-error.md
  - docs/solutions/testing-patterns/playwright-retry.md
  - docs/solutions/api-integrations/stripe-webhook.md

If coverage < 100%: Suggest running /reflect:consolidate to generate missing sidecars.

4. GraphRAG Health

if command -v reflect >/dev/null 2>&1; then
    reflect stats
elif [[ -x "$HOME/.local/bin/reflect" ]]; then
    "$HOME/.local/bin/reflect" stats
fi

Shows:

• Total indexed learnings
• Node count (entities)
• Edge count (relationships)
• Last indexing timestamp

5. Orphaned Memory Stats

python3 {{HOME_TOOL_DIR}}/skills/reflect/scripts/memory_discovery.py stats

Shows:

• Repo name
• Orphaned memory dirs count
• Total lines across all orphaned dirs

If orphaned dirs > 0: Suggest running /reflect:consolidate to merge them. If unindexed memories found: Suggest running /reflect:ingest to index into GraphRAG + QMD.

6. Project Memory Health

Check if .agents/MEMORY.md exists and its line count:

if [[ -f .agents/MEMORY.md ]]; then
    LINES=$(wc -l < .agents/MEMORY.md | tr -d ' ')
    echo "Project memory: .agents/MEMORY.md ($LINES/200 lines)"
else
    echo "Project memory: not found (run /reflect:consolidate to create)"
fi

7. Knowledge Gaps (negative recall)

Every 0-result recall is appended to ~/.reflect/knowledge-gaps.jsonl by recall.py (normalized query + session id). Queries that came up empty in >=2 distinct sessions are knowledge gaps — users keep asking about them with no learnings in the KB. This is the curation backlog.

python3 {{HOME_TOOL_DIR}}/skills/reflect-status/scripts/knowledge_gaps.py

Shows:

• Repeat gaps (normalized-query dedup'd, distinct-session counted)
• Ask counts and last-seen dates
• Total distinct 0-result queries on file

Options: --min-sessions 1 to include one-off gaps, --format json for programmatic use.

If repeat gaps exist: Suggest capturing learnings for those topics via /reflect or /reflect:ingest — once indexed, the gap stops recurring.

8. Learning Update History

Every UPDATE to a learning snapshots its old form into the learning_history table in ~/.reflect/reflect.db (and, for knowledge notes, an append-only {slug}.history.yaml sidecar next to the note). Show the update count per learning:

python3 {{HOME_TOOL_DIR}}/skills/reflect/scripts/reflect_db.py history

Shows, per learning (most-updated first):

• Learning id
• Update count (history snapshots recorded)
• Last-updated timestamp
• Title

If a learning has an unusually high update count: its belief keeps getting revised — inspect the snapshots (learning_history.snapshot_json or the .history.yaml sidecar) to see why the rule kept changing.

9. Contradictions (cross-turn detection)

Every new learning write runs deterministic contradiction detection against recent in-scope learnings sharing >= 1 concept tag (negation-stripped token Jaccard > 0.9 with a negation marker in exactly one of the two — e.g. saving "never use foo" against an existing "use foo"). The OLDER learning is demoted (is_latest = 0, superseded_by_learning_id set) and a contradiction_detected audit event is written to the events table in ~/.reflect/reflect.db, mirrored to ~/.reflect/events.jsonl.

python3 {{HOME_TOOL_DIR}}/skills/reflect/scripts/reflect_db.py contradictions

Shows:

• Total contradiction count
• Recent contradiction pairs (older id -> newer id, similarity, both titles)

If contradictions exist: the demoted side is preserved (history snapshot + is_latest = 0, never deleted) — review the pairs to confirm the newer rule is actually the correct one; if the flip was wrong, re-state the older rule so it wins the next round.

Review Mode

When invoked as reflect review or when there are pending items, enter review mode.

Pending Low-Confidence Items

python {{HOME_TOOL_DIR}}/skills/reflect/scripts/state_manager.py pending

For each pending item, show:

• Signal text
• Detection date
• Source quote
• Category

Review actions:

• approve N -- Promote item N to full confidence, apply the change
• reject N -- Remove item N from pending queue
• approve all -- Promote all pending items
• reject all -- Clear all pending items
• skip -- Leave pending for later

When approving:

1. Apply the behavioral change or create the knowledge note
2. Generate entity sidecar if knowledge type
3. Index via reflect add CLI (reflect-kb)
4. Remove from pending queue:

   # Done internally via state_manager
   python -c "
   import sys; sys.path.insert(0, '{{HOME_TOOL_DIR}}/skills/reflect/scripts')
   from state_manager import clear_pending_review
   clear_pending_review(INDEX)
   "
   

5. Update metrics

Staleness Check

Flag items that have been pending for more than 7 days:

STALE (14 days): "Consider using memoization for expensive renders"
  - Detected: 2026-03-30
  - Recommend: reject (too old, context lost) or approve if still relevant

Output Format

Present everything in a clean dashboard format:

# Reflect Status Dashboard

## System State
| Metric | Value |
|--------|-------|
| Auto-Reflect | Disabled |
| Last Reflection | 2026-04-12 14:30:00 |
| State Directory | ~/.reflect |

## Aggregate Metrics
| Metric | Value |
|--------|-------|
| Sessions Analyzed | 42 |
| Signals Detected | 156 |
| Changes Proposed | 114 |
| Changes Accepted | 89 (78%) |
| Skills Created | 5 |
| Estimated Time Saved | ~7.4 hours |

## Confidence Breakdown
| Level | Count |
|-------|-------|
| High | 45 |
| Medium | 32 |
| Low | 12 |

## Most Updated Agents
| Agent | Updates |
|-------|---------|
| code-reviewer | 23 |
| backend-developer | 18 |
| frontend-developer | 12 |
| security-agent | 8 |
| solution-architect | 5 |

## Sidecar Coverage
15/18 knowledge notes have sidecars (83%)
3 notes missing sidecars -- run /reflect:consolidate to fix

## GraphRAG Health
- Indexed learnings: 34
- Entities: 112
- Relationships: 87
- Last indexed: 2026-04-12

## Orphaned Memories
- Orphaned dirs: 3
- Total lines: 127
- Suggest: /reflect:consolidate

## Knowledge Gaps (negative recall)
Knowledge gap — users keep asking about these with no learnings:
- **istio sidecar injection failures** — 3 sessions, 5 asks, last 2026-04-11
- **bun workspace hoisting** — 2 sessions, 2 asks, last 2026-04-09
Suggest: capture learnings for these topics, then /reflect:ingest

## Learning Update History
| Learning | Updates | Last Updated |
|----------|---------|--------------|
| never use var in this codebase | 4 | 2026-04-12 |
| prefer uv over pip | 2 | 2026-04-10 |

## Contradictions
Contradictions detected: 2
| Older (demoted) | Newer (kept) | Similarity |
|-----------------|--------------|------------|
| use fab deploy | never use fab deploy | 1.00 |
| commit straight to main | don't commit straight to main | 1.00 |

## Pending Reviews: 2
1. [MEDIUM] "Consider cursor-based pagination for large datasets" (5 days)
2. [LOW] "Memoize expensive component renders" (12 days, STALE)

Review pending items? (approve N / reject N / skip)

Troubleshooting

Metrics show 0:

• Run /reflect at least once to initialize metrics
• Check state directory: ls ~/.reflect/

GraphRAG stats unavailable:

• Check if reflect-kb CLI is installed: command -v reflect
• Install if missing: uv tool install --upgrade 'git+https://github.com/stevengonsalvez/ainb-reflect-memory.git[graph]'

Sidecar count is 0:

• Knowledge notes may exist without sidecars (pre-v3 behavior)
• Run /reflect:consolidate to generate missing sidecars