Review Meaning Index Suggestions

Smart batch workflow that automatically accepts high-confidence suggestions and only prompts for manual review when needed.

What This Does

1. Categorizes files needing review into:

- High-confidence (auto-accept) - Recently added (mark as reviewed) - Low-confidence (manual review)

1. Batch applies changes automatically
2. Only prompts for files that need manual attention
3. Reports all changes made

Default Workflow (Recommended)

Run without arguments for automatic batch processing:

/meaning-review

This will:

• ✅ Auto-accept high-confidence suggestions (≥0.8 confidence)
• ✅ Mark recently added files as reviewed (< 1 hour old)
• ⚠️ Flag low-confidence files for manual review (if any)
• 💾 Save changes and validate

Example output:

✓ Loaded index with 35 files
🔍 Found 11 files needing review

📊 Categorizing...
   • 9 high-confidence (auto-accept)
   • 2 recently added (mark as reviewed)
   • 0 need manual review

🤖 Auto-accepting 9 files...
   ✓ README.md (updated intent, added 2 relationships)
   ✓ CLAUDE.md (updated intent)
   ✓ src/meaning/meaning_core.py (added 3 relationships)
   ✓ tests/test_core.py (added 1 relationship)
   ✓ .claude/skills/meaning-query/SKILL.md (updated intent, added 2 rels)
   ... 4 more files

✅ Accepted 2 recently added files
   ✓ .agent-sessions/2026-01-21-phase5-discovery-query.md
   ✓ .claude/settings.local.json

============================================================
📋 REVIEW COMPLETE
============================================================
✓ Files reviewed: 11/11 (100%)
✓ Files still needing review: 0
✓ Applied 24 suggestions automatically
✓ Validation: True

Total time: 0.8s
============================================================

Implementation

from pathlib import Path
from datetime import datetime, timedelta, timezone
import sys
sys.path.insert(0, 'src')

from meaning.meaning_core import (
    load_index, load_schema, load_config,
    save_yaml, validate_index,
    MEANING_DIR, INDEX_FILENAME, Relationship
)
from meaning_inference import infer_file_metadata, infer_timestamps

project_root = Path.cwd()

# Load index
index = load_index(project_root)
schema = load_schema(project_root)
config = load_config(project_root)

print(f"✓ Loaded index with {len(index.files)} files")

# Find files needing review
needs_review = index.files_needing_review()

if not needs_review:
    print("✅ No files need review!")
    exit(0)

print(f"🔍 Found {len(needs_review)} files needing review")
print()

# Categorize files
print("📊 Categorizing...")
now = datetime.now(timezone.utc)
auto_accept = []
recently_added = []
manual_review = []
total_suggestions = 0

for entry in needs_review:
    # Check if recently added (< 1 hour and has placeholder intent)
    age = now - entry.last_verified
    if age < timedelta(hours=1) and '[REVIEW NEEDED]' in entry.intent:
        recently_added.append(entry)
        continue

    # Run inference
    result = infer_file_metadata(entry.path, project_root, index, schema)

    # Calculate confidence score
    has_high_confidence = (
        result.intent and result.intent.confidence >= 0.8 and
        (not result.tags or all(t.confidence >= 0.8 for t in result.tags)) and
        not result.errors
    )

    if has_high_confidence:
        auto_accept.append((entry, result))
    else:
        manual_review.append((entry, result))

print(f"   • {len(auto_accept)} high-confidence (auto-accept)")
print(f"   • {len(recently_added)} recently added (mark as reviewed)")
print(f"   • {len(manual_review)} need manual review")
print()

# Apply auto-accept changes
if auto_accept:
    print(f"🤖 Auto-accepting {len(auto_accept)} files...")
    for entry, result in auto_accept:
        changes = []

        # Update intent
        if result.intent and result.intent.intent != entry.intent:
            entry.intent = result.intent.intent
            changes.append("updated intent")

        # Add high-confidence tags
        current_tags = set(entry.tags)
        for tag_info in result.tags:
            if tag_info.confidence >= 0.8 and tag_info.tag not in current_tags:
                entry.tags.append(tag_info.tag)
                changes.append(f"added tag:{tag_info.tag}")

        # Add high-confidence relationships
        current_rels = {(r.type, r.target) for r in entry.relationships}
        for rel_info in result.relationships:
            if rel_info.confidence >= 0.8:
                rel_key = (rel_info.relationship.type, rel_info.relationship.target)
                if rel_key not in current_rels:
                    entry.relationships.append(rel_info.relationship)
                    changes.append(f"added {rel_info.relationship.type}")

        # Mark as reviewed
        entry.needs_review = False
        entry.last_verified = infer_timestamps()

        total_suggestions += len(changes)
        change_summary = ", ".join(changes) if changes else "no changes"
        print(f"   ✓ {entry.path} ({change_summary})")
    print()

# Mark recently added files as reviewed
if recently_added:
    print(f"✅ Accepted {len(recently_added)} recently added files")
    now = infer_timestamps()
    for entry in recently_added:
        entry.needs_review = False
        entry.last_verified = now
        print(f"   ✓ {entry.path}")
    print()

# Save changes
index.last_updated = infer_timestamps()
index_path = project_root / MEANING_DIR / INDEX_FILENAME
save_yaml(index_path, index.to_dict())

# Validate
validation = validate_index(index, schema, config, project_root)

# Report
print("=" * 60)
print("📋 REVIEW COMPLETE")
print("=" * 60)
print(f"✓ Files reviewed: {len(auto_accept) + len(recently_added)}/{len(needs_review)}")
print(f"✓ Files still needing review: {len(manual_review)}")
if total_suggestions > 0:
    print(f"✓ Applied {total_suggestions} suggestions automatically")
print(f"✓ Validation: {validation.is_valid}")

if validation.errors:
    print(f"\n❌ Errors: {len(validation.errors)}")
    for e in validation.errors[:3]:
        print(f"   • {e}")

if manual_review:
    print(f"\n⚠️  {len(manual_review)} files need manual review (low confidence)")
    for entry, result in manual_review[:5]:
        print(f"   • {entry.path}")
        if result.intent:
            print(f"     Intent confidence: {result.intent.confidence:.2f}")
        if result.errors:
            print(f"     Errors: {', '.join(result.errors)}")
    print("\nRun '/meaning-review --interactive' to review these files manually")

print("=" * 60)

Interactive Mode (Manual Review)

For low-confidence files or manual control:

/meaning-review --interactive

This shows each file with suggestions and asks for your decision:

What would you like to do with src/complex_file.py?

1. Accept all suggestions
2. Accept intent only
3. Accept tags only
4. Accept relationships only
5. Edit manually
6. Skip (review later)
7. Mark as reviewed (no changes)

Type the number:

Arguments

Use Cases

Confidence Levels

Auto-accepted (≥0.8):

• Intent from clear docstrings/markdown headers
• Tags from filename patterns (test files, config files)
• Relationships from imports/links
• Recently added files (< 1 hour old)

Manual review (<0.8):

• Generated or unclear intents
• Files with inference errors
• Complex relationship inference
• Custom/unusual file types

Time Savings

Philosophy

Automation with safety:
- High confidence → auto-accept
- Low confidence → human review
- Always transparent
- Always reversible

This skill:

• ✓ Trusts high-confidence inference (≥0.8)
• ✓ Flags uncertain cases for human review
• ✓ Shows all changes made
• ✓ Validates after applying changes
• ✓ Provides escape hatches (interactive mode, dry-run)

Last updated: 2026-01-21