ai-counsel: Skill for Claude Code

Decision Graph Analyzer Skill

Overview

The decision graph module (decision_graph/) stores completed deliberations and provides semantic similarity-based retrieval for context injection. This skill teaches you how to query, analyze, and troubleshoot the decision graph effectively.

Core Components

Storage Layer (decision_graph/storage.py)

• DecisionGraphStorage: SQLite3 backend with CRUD operations
• Schema: decision_nodes, participant_stances, decision_similarities
• Indexes: Optimized for timestamp (recency), question (duplicates), similarity (retrieval)
• Connection: Use :memory: for testing, file path for production

Integration Layer (decision_graph/integration.py)

• DecisionGraphIntegration: High-level API facade
• Methods:
  • store_deliberation(question, result): Save completed deliberation
  • get_context_for_deliberation(question): Retrieve similar past decisions
  • get_graph_stats(): Get monitoring statistics
  • health_check(): Validate database integrity

Retrieval Layer (decision_graph/retrieval.py)

• DecisionRetriever: Finds relevant decisions and formats context
• Key Features:
  • Two-tier caching (L1: query results, L2: embeddings)
  • Adaptive k (2-5 results based on database size)
  • Noise floor filtering (0.40 minimum similarity)
  • Tiered formatting (strong/moderate/brief)

Maintenance Layer (decision_graph/maintenance.py)

• DecisionGraphMaintenance: Monitoring and health checks
• Methods:
  • get_database_stats(): Node/stance/similarity counts, DB size
  • analyze_growth(days): Growth rate and projections
  • health_check(): Validate data integrity
  • estimate_archival_benefit(): Space savings simulation

Common Query Patterns

1. Find Similar Decisions

When: You want to see what past deliberations are related to a new question.

from decision_graph.integration import DecisionGraphIntegration
from decision_graph.storage import DecisionGraphStorage

# Initialize
storage = DecisionGraphStorage("decision_graph.db")
integration = DecisionGraphIntegration(storage)

# Get similar decisions with context
question = "Should we adopt TypeScript for the project?"
context = integration.get_context_for_deliberation(question)

if context:
    print("Found relevant past decisions:")
    print(context)
else:
    print("No similar past decisions found")