Initial commit
This commit is contained in:
Zhongwei Li
153
skills/phi-analyzer/SKILL.md
Normal file
153
skills/phi-analyzer/SKILL.md
Normal file
@@ -0,0 +1,153 @@
|
||||
---
|
||||
name: phi-analyzer
|
||||
description: Auto-invoked compositional project analysis using φ = ∫(structure × semantics × memory). Analyzes codebase using three integrated layers - structure, semantics, and memory - for understanding project layout, architecture, and accumulated insights.
|
||||
---
|
||||
|
||||
# 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
|
||||
|
||||
```typescript
|
||||
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.
|
||||
Reference in New Issue
Block a user