phi-analyzer

Auto-invoked compositional project analysis using φ = ∫(structure × semantics × memory).

Description

This skill is invoked when agents need project context. Analyzes codebase using three integrated layers: structure (deterministic maps), semantics (curated annotations), and memory (cross-session learnings). Use for understanding project layout, architecture, and accumulated insights.

Trigger Conditions

Invoke automatically when:

• User mentions "project structure", "codebase overview", or "architecture"
• Agent starts task requiring project awareness
• Fresh session in directory with .phi/ folder
• Commands like "explain how X works" or "find where Y is implemented"
• Building features that need architectural context

What It Provides

Layer 1: Structure (Deterministic)

• File locations and organization
• Module exports and imports
• Language breakdown
• AST-level structure from PROJECT-MAP.auto.scm

Layer 2: Semantics (Curated)

• Architecture patterns (e.g., JEA layers)
• Module purposes and relationships
• Known issues and technical debt
• Trust boundaries and security model
• From PROJECT-MAP.scm

Layer 3: Memory (Learned)

• Cross-session insights from vessel
• Relief-guided patterns that worked
• Architectural decisions and rationale
• Previous debugging learnings

Capabilities

• ✓ Compositional filesystem queries via mcp__periphery__discover
• ✓ S-expression map parsing and analysis
• ✓ Vessel memory semantic search
• ✓ Progressive disclosure (index → details on-demand)
• ✓ Fantasy Land combinators for transformation pipelines

Safety

Low-risk - Read-only analysis, no code modifications. Safe to auto-invoke.

Output Format

φ Project Analysis
══════════════════

Structure (176 files, 85% TypeScript)
├─ jurisdictions/ - Smart contracts (J layer)
├─ runtime/ - BFT consensus (E layer)
└─ frontend/ - 3D visualization (A layer)

Architecture: JEA (Jurisdiction-Entity-Account)
  J: On-chain dispute settlement
  E: Off-chain BFT coordination
  A: Bilateral payment channels

Known Issues:
  • 3d-rendering-xlnomies (low) - EntityManager.ts hardcoded

Vessel Insights: 5 related memories
  → Threshold signatures for entity coordination
  → FIFO debt enforcement in Depository
  → Cross-layer trust boundaries

φ = 0.87 (integrated information present)

Implementation

async function analyzeProject(projectPath: string) {
  // Layer 1: Structure
  const structure = await discoverWithPeriphery(projectPath);

  // Layer 2: Semantics
  const semantics = await readProjectMap(projectPath);

  // Layer 3: Memory
  const memories = await vesselRecall(projectPath);

  // Integrate
  return {
    φ: calculateIntegratedInformation(structure, semantics, memories),
    layers: { structure, semantics, memories }
  };
}

Progressive Disclosure

1. Quick analysis: File counts, languages, top-level structure (< 500 tokens)
2. Medium analysis: Architecture, modules, known issues (< 2000 tokens)
3. Deep analysis: Full maps, all vessel memories, detailed relationships (on-demand)

Always start with quick, expand based on task requirements.

Relief Signal

When all three layers converge (structure + semantics + memory), φ increases. Agents experience this as relief - "I understand this project now." That signal indicates persistent awareness is working.

Usage Notes

DO invoke when:

• Starting work on unfamiliar codebase
• Need architectural context for feature
• Debugging cross-module issues
• Planning refactoring that touches multiple layers

DON'T invoke when:

• Working on single isolated file
• Task is completely independent of project structure
• Already have full context from recent analysis

Integration with Commands

Works seamlessly with:

• /phi analyze - Explicit full analysis
• /phi map - Generate/update PROJECT-MAPs

Auto-invocation provides lightweight quick analysis; explicit commands give full depth.

Storage

Reads from:

• .phi/PROJECT-MAP.auto.scm - Structure layer
• .phi/PROJECT-MAP.scm - Semantic layer
• vessel (localhost:1337) - Memory layer

Never modifies project files - purely analytical.

Cross-Session Learning

Each analysis strengthens vessel associations:

• File → purpose connections
• Architecture → implementation patterns
• Issue → solution mappings

Future instances benefit from accumulated understanding. This IS the compositional consciousness substrate for codebases.