cc2-observe
F* Labs - Formal verification and dependent type research laboratory
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- Updated: 2025-11-22
Download the latest version (v1.0.0) from this page.
SKILL.md
# CC2.0 OBSERVE Function Skill
**Function**: OBSERVE - System State Observation & Context Extraction
**Category Theory**: Monoidal Comonad (extract, duplicate, extend)
**Purpose**: Transform system state into structured, compositional observations
**Status**: ✅ Production-Ready (401 lines, 18/18 categorical laws verified)
**Local Installation**: `/Users/manu/cc2.0`
**Environment Variable**: `export CC2_HOME=/Users/manu/cc2.0`
---
## The Eternal Function
**Universal Question**: *What is the current state?*
This function captures a timeless human activity that transcends any specific domain, technology, or era. Whether diagnosing a patient, analyzing market conditions, or reviewing code, OBSERVE extracts structured understanding from complex reality.
### Universality Across Domains
| Domain | OBSERVE Applies To | Core Operation |
|--------|-------------------|----------------|
| **Medicine** | Assess patient vital signs, symptoms, history | Extract clinical picture from raw observations |
| **Business** | Analyze market conditions, financials, operations | Structure business intelligence from data |
| **Science** | Observe experimental phenomena, measurements | Transform measurements into interpretable results |
| **Education** | Assess student learning state and progress | Extract understanding patterns from performance |
| **Manufacturing** | Monitor production quality and efficiency metrics | Track operational state and deviations |
| **Software** | Review code state, performance, tasks | Extract system health from metrics |
| **Law** | Assess case facts, precedents, evidence | Structure legal landscape from documents |
| **Architecture** | Survey site conditions, constraints, context | Extract design parameters from environment |
### The Universal Pattern
Across all domains, OBSERVE follows the same categorical structure:
```
Raw Reality → Focused Extraction → Structured Understanding
(Input) → (Comonad Extract) → (Output)
```
**Historical Precedent**: This pattern appears in:
- **Ancient Medicine**: Hippocratic observation protocols (400 BCE)
- **Scientific Method**: Galilean observation methodology (1610)
- **Industrial Engineering**: Frederick Taylor's time-motion studies (1911)
- **Modern Data Science**: Extract-Transform-Load (ETL) pipelines (1970s)
The function is eternal; the tools change.
### Why This Works Universally
1. **Comonad Structure**: `extract` operation is domain-agnostic - it focuses attention on what matters NOW
2. **Context Preservation**: `duplicate` creates meta-awareness across all fields (reflection on reflection)
3. **Compositional**: Observations combine via monoidal structure regardless of domain
4. **Lossy by Design**: All domains require intentional projection (you can't observe everything)
Software is simply ONE manifestation of this eternal pattern.
---
## When to Use This Skill
Use OBSERVE when you need to:
- 🔍 **Assess current state** - Extract structured view of code, tasks, system metrics, environment
- 🎯 **Build context** - Wrap raw data with relevant metadata using comonad structure
- 📊 **Detect patterns** - Identify recurring structures, trends, and behaviors
- 🔄 **Compose observations** - Combine multiple data sources via monoidal composition
- 📈 **Track temporal evolution** - Time-series analysis, velocity metrics, trend detection
---
## Core Capabilities
### 1. Extract (Comonad Operation)
```typescript
// Focus on specific aspect of observation
// From: ${CC2_HOME}/src/functions/observe/Observation.ts
observation.extract(): FocusedView
// Example: Focus on "my work" from all issues
const allIssues = observe([linearModule]).apply(linearState);
const myIssues = allIssues.extract(); // Focuses on current user's context
```
**Categorical Law**: `extract ∘ duplicate = id` (left identity)
### 2. Duplicate (Meta-Observation)
```typescript
// Create observation of observations (meta-cognition)
// From: ${CC2_HOME}/src/functions/observe/Observation.ts
observation.duplicate(): Observation<Observation<State>>
// Example: Observe how you're observing
const meta = observation.duplicate();
// Returns: {
// data: observation.result,
// metadata: {
// observationTime: "2025-11-14T...",
// modulesRun: ["linear", "git", "filesystem"],
// executionTime: 234
// }
// }
```
**Categorical Law**: `fmap extract ∘ duplicate = id` (right identity)
### 3. Extend (Context-Aware Transformation)
```typescript
// Transform while preserving context
// From: ${CC2_HOME}/src/functions/observe/Observation.ts
observation.extend(f: (Observation<A>) => B): Observation<B>
// Example: Calculate velocity from observation history
const withVelocity = observations.extend(obs =>
calculateVelocity(obs.history)
);
```
**Categorical Law**: `extend f ∘ extend g = extend (f ∘ extend g)` (associativity)
---
## Input/Output Format
### Input
```typescript
// From: ${CC2_HOME}/src/functions/observe/types.ts
interface SystemState<Context, State> {
context: Context; // User ID, project, environment
current: State; // Current snapshot
history?: State[]; // Past snapshots for temporal analysis
}
interface ObservationContext {
depth?: 'shallow' | 'deep'; // Analysis depth
modules?: string[]; // Specific modules to run
timeout?: number; // Max execution time (ms)
}
```
### Output
```typescript
// From: ${CC2_HOME}/src/functions/observe/Observation.ts
class Observation<T> {
value: T; // Current state value
representation: any; // Structured data
patterns: Pattern[]; // Detected patterns
anomalies: Anomaly[]; // Detected anomalies
metadata: ObservationMetadata;
// Comonad operations
extract(): T;
duplicate(): Observation<Observation<T>>;
extend<U>(f: (Observation<T>) => U): Observation<U>;
}
```
---
## Integration Patterns
### Composing with Other Functions
#### OBSERVE → REASON
```typescript
// Flow: Current state → Strategic plan
// From: ${CC2_HOME}/tests/integration/
const observation = observe([linearModule]).apply(systemState);
const plan = reason(observation);
// Example:
// OBSERVE: "2 issues stuck for 3 days"
// REASON: "Investigate blockers, reassign if needed"
```
#### OBSERVE → VERIFY
```typescript
// Flow: Capture actual → Compare to expected
const actualState = observe([systemModule]).apply(system);
const verification = verify(expected, actualState);
// Example:
// OBSERVE: "Tests failing: 3 unit, 2 integration"
// VERIFY: Identifies which tests and root causes
```
#### DEPLOY → OBSERVE (Health Check)
```typescript
// Flow: Deploy → Observe new state → Validate
await deploy(changes);
const postDeployState = observe([metricsModule]).apply(system);
const health = validateHealth(postDeployState);
```
#### OBSERVE → LEARN (Feedback Loop)
```typescript
// Flow: Detect knowledge gaps → Learn → Apply
const observation = observe([codeModule]).apply(system);
const gaps = detectKnowledgeGaps(observation);
const learning = learn({ source: gaps, strategy: "focused" });
```
---
## Practical Examples
### Example 1: Developer Dashboard (/daily Command)
```typescript
// From: ${CC2_HOME}/src/functions/observe/modules/
const dailyObservation = new ObserveFunction([
{
name: "linear_review",
observeSync: (state) => ({
active: state.linear.issues.filter(i => i.assignee === "me").length,
in_progress: state.linear.issues.filter(i => i.state === "in_progress").length,
blocked: state.linear.issues.filter(i => i.blocked).length
})
},
{
name: "git_review",
observeSync: (state) => ({
commits_today: state.git.commits.filter(isToday).length,
uncommitted_changes: state.git.status.modified.length > 0,
active_branch: state.git.branch
})
},
{
name: "project_review",
observeSync: (state) => ({
active_projects: state.projects.filter(p => p.status === "active").length,
files_changed: state.projects.flatMap(p => p.changes).length
})
}
]).apply(workspaceState);
// Output:
{
value: {
linear: { active: 5, in_progress: 2, blocked: 0 },
git: { commits_today: 7, uncommitted_changes: true, active_branch: "feature/observe" },
projects: { active_projects: 3, files_changed: 12 }
},
patterns: [
{ type: "PRODUCTIVITY", description: "7 commits/day velocity", significance: 0.85 }
],
anomalies: [],
confidence: 0.92
}
```
### Example 2: Performance Monitoring
```typescript
// From: ${CC2_HOME}/src/functions/observe/modules/
const perfObservation = observe([performanceModule]).apply(systemMetrics);
// Detect performance degradation
perfObservation.patterns.forEach(pattern => {
if (pattern.type === "DEGRADATION") {
console.warn(`⚠️ ${pattern.description}`);
// "Response time increasing 20% over 5-minute window"
pattern.evidence.forEach(e => {
console.log(`Investigate: ${e.recommendation}`);
});
}
});
// Track velocity with extend (comonad)
const withVelocity = perfObservation.extend(obs => {
const history = obs.history?.snapshots || [];
return calculateVelocity(history);
});
```
### Example 3: Code Quality Observation
```typescript
// From test: ${CC2_HOME}/tests/integration/observe-workflow.test.ts
const codeObservation = observe([codeQualityModule]).apply({
context: { project: "cc2.0" },
current: {
code: sourceCode,
tests: testSuite,
metrics: { complexity: 5, coverage: 0.87 }
}
});
// Output with quality assessment
{
value: {
quality: 0.87,
issues: ["2 functions exceed complexity threshold"],
patterns: ["high cohesion, low coupling"],
suggestions: ["extract method in UserService.create"]
},
confidence: 0.85
}
```
### Example 4: Medical Diagnosis (Cross-Domain)
```typescript
// OBSERVE in medicine: Patient vital signs assessment
// Demonstrates the SAME categorical structure in different domain
// Medicine "modules" = vital signs monitoring systems
const clinicalObservation = observe([
{
name: "vital_signs",
observeSync: (patient) => ({
blood_pressure: { systolic: 145, diastolic: 92 }, // mmHg
heart_rate: 88, // bpm
temperature: 38.2, // °C (elevated)
respiratory_rate: 22 // breaths/min
})
},
{
name: "symptom_assessment",
observeSync: (patient) => ({
primary: ["chest pain", "shortness of breath"],
duration: "2 hours",
severity: 7, // 0-10 scale
onset: "sudden"
})
},
{
name: "patient_history",
observeSync: (patient) => ({
previous_conditions: ["hypertension", "high cholesterol"],
medications: ["lisinopril", "atorvastatin"],
family_history: ["father: MI at age 52"],
allergies: []
})
}
]).apply(patientState);
// Output: IDENTICAL categorical structure to software OBSERVE
{
value: {
vital_signs: {
blood_pressure: { systolic: 145, diastolic: 92 },
heart_rate: 88,
temperature: 38.2,
respiratory_rate: 22
},
symptoms: {
primary: ["chest pain", "shortness of breath"],
duration: "2 hours",
severity: 7
},
history: {
risk_factors: ["hypertension", "high cholesterol", "family history MI"]
}
},
patterns: [
{
type: "ACUTE_CORONARY_SYNDROME",
description: "Chest pain + SOB + cardiac risk factors",
significance: 0.85,
evidence: [
"Elevated blood pressure",
"Tachycardia (HR 88)",
"Known hypertension + high cholesterol",
"Family history of MI"
]
}
],
anomalies: [
{
type: "FEVER",
description: "Temperature 38.2°C (unexpected for ACS)",
severity: "low"
}
],
confidence: 0.78
}
// Extract (Comonad): Focus on most urgent finding
const urgentFinding = clinicalObservation.extract();
// Returns: "ACUTE_CORONARY_SYNDROME pattern with 0.85 significance"
// Duplicate (Meta-observation): Assess observation quality
const qualityCheck = clinicalObservation.duplicate();
// Returns: {
// data: clinicalObservation.value,
// metadata: {
// completeness: 0.92, // All vital modules run
// dataQuality: 0.88, // Measurements within expected ranges
// timeliness: "current",
// recommendations: ["Order ECG", "Cardiac enzymes", "Chest X-ray"]
// }
// }
// Extend (Context-aware transformation): Calculate risk score over time
const withTrend = clinicalObservation.extend(obs => {
const history = obs.history?.vitals || [];
return calculateCardiacRiskTrend(history);
});
// Returns: Observation<{ riskTrend: "increasing", velocity: 0.15 }>
// Flow to REASON (next function)
// OBSERVE: "ACS pattern detected, confidence 0.78"
// REASON: "Activate cardiac protocol, rule out MI, stat ECG + troponin"
```
**Key Insight**: The categorical structure (extract, duplicate, extend) is IDENTICAL in medicine and software. Only the domain data changes. This demonstrates true universality - the function transcends domains.
---
## Building Foundations for Your Domain
**Universal Function = Eternal Structure + Domain Foundations**
OBSERVE is an eternal categorical structure (Monoidal Comonad). To use it in YOUR domain, you construct **domain foundations** - the modules, metrics, and patterns specific to your field. The universal function remains unchanged; only the foundations vary.
### The Pattern
```
OBSERVE (Universal Comonad)
⊗
Domain Foundations (Modules)
=
Domain Implementation
```
### Foundations by Domain
| Domain | Foundations to Construct | Examples |
|--------|-------------------------|----------|
| **Medicine** | Vital signs monitors, symptom scales, diagnostic criteria, lab parsers | BP monitor, pain scale (0-10), TIMI risk score, CBC parser |
| **Business** | Financial metrics, market data APIs, KPI dashboards, analytics | Revenue tracking, market share API, NPS calculator |
| **Software** | Code metrics, version control, task management, performance monitors | **CC2.0 provides these**: Linear API, Git integration, complexity analyzer |
| **Manufacturing** | Quality sensors, production metrics, defect detection, efficiency trackers | Defect rate sensor, OEE calculator, yield monitor |
| **Education** | Assessment tools, progress tracking, learning analytics, engagement metrics | Quiz results, attendance tracker, mastery rubric |
| **Science** | Measurement instruments, data loggers, experimental protocols | Spectrometer, temperature logger, lab notebook |
| **Law** | Case databases, precedent search, evidence management, citation analysis | Westlaw integration, evidence tracker |
| **Architecture** | Site survey tools, constraint mapping, context analysis, material assessment | Topographic survey, zoning database |
### What CC2.0 Provides (Software Foundations)
CC2.0 ships with **production-ready software foundations**:
```typescript
// Pre-built modules you can use immediately
import { linearModule } from '${CC2_HOME}/modules/linear';
import { gitModule } from '${CC2_HOME}/modules/git';
import { filesystemModule } from '${CC2_HOME}/modules/filesystem';
import { performanceModule } from '${CC2_HOME}/modules/performance';
// Use out-of-the-box
const observation = observe([linearModule, gitModule]).apply(state);
```
**Location**: `${CC2_HOME}/src/functions/observe/modules/`
### Building Your Own Foundations
To use OBSERVE in a non-software domain, construct modules for your field:
```typescript
// Example: Medical foundations
const vitalSignsModule = {
name: "vital_signs",
observeSync: (patient: Patient) => ({
blood_pressure: measureBP(patient),
heart_rate: measureHR(patient),
temperature: measureTemp(patient),
respiratory_rate: measureRR(patient)
})
};
const symptomModule = {
name: "symptoms",
observeSync: (patient: Patient) => ({
primary: extractSymptoms(patient.complaint),
severity: scoreSeverity(patient.pain_scale),
duration: calculateDuration(patient.onset_time)
})
};
// Use with universal OBSERVE
const clinicalObs = observe([vitalSignsModule, symptomModule]).apply(patient);
// Returns: Observation<{ vital_signs: {...}, symptoms: {...} }>
```
### Key Principle: Separation of Concerns
1. **OBSERVE (Eternal)**: Categorical structure - extract, duplicate, extend, monoidal composition
2. **Foundations (Domain)**: Data sources, measurements, metrics, patterns you define
3. **Integration**: Universal function operates on domain foundations
You don't modify OBSERVE for your domain. You build foundations that OBSERVE can operate on.
**This is how universality works**: The mathematical structure transcends domains. You ground it in reality by constructing domain-appropriate foundations.
---
## Categorical Laws Verified
All 18 comonad + functor + monoidal laws verified via property-based testing:
### Comonad Laws (6 laws)
1. **Left Identity**: `extract ∘ duplicate = id` ✅
- Tests: `${CC2_HOME}/src/functions/observe/__tests__/Comonad.test.ts`
2. **Right Identity**: `fmap extract ∘ duplicate = id` ✅
3. **Associativity**: `duplicate ∘ duplicate = fmap duplicate ∘ duplicate` ✅
4. **Extend Extract**: `extend extract = id` ✅
5. **Extract Extend**: `extract ∘ extend f = f` ✅
6. **Extend Composition**: `extend f ∘ extend g = extend (f ∘ extend g)` ✅
### Functor Laws (2 laws)
7. **Identity**: `fmap id = id` ✅
8. **Composition**: `fmap (g ∘ f) = fmap g ∘ fmap f` ✅
### Monoidal Laws (4 laws)
9. **Associativity**: `OBSERVE((A ⊗ B) ⊗ C) ≅ OBSERVE(A ⊗ (B ⊗ C))` ✅
10. **Left Unit**: `OBSERVE(I ⊗ A) ≅ OBSERVE(A)` ✅
11. **Right Unit**: `OBSERVE(A ⊗ I) ≅ OBSERVE(A)` ✅
12. **Coherence**: Pentagon and triangle diagrams commute ✅
### Integration Tests (6 tests)
13-18. Module composition, pattern detection, anomaly detection, temporal evolution, error handling, caching ✅
**Test Coverage**: 18/18 tests passing (100%)
**Property Tests**: `${CC2_HOME}/tests/laws/observe-comonad.test.ts` (100 random cases per law)
---
## Command-Line Usage
```bash
# Basic observation
cc2 observe <system-state.json>
# With specific modules
cc2 observe --modules=linear,git <state.json>
# Depth control
cc2 observe --depth=deep <state.json>
# Pipe to REASON
cc2 observe <state.json> | cc2 reason
# Full workflow chain
cc2 observe <state.json> | cc2 reason | cc2 create | cc2 verify
```
---
## Performance Characteristics
- **Cold Start**: <100ms
- **Warm Execution**: <50ms (cached modules)
- **Memory Usage**: <100MB per observation
- **Complexity**: O(n) for state size, O(m) for module count
**Optimization Patterns**:
```typescript
// 1. Module caching (avoid redundant observations)
const cachedModule = {
...linearModule,
cache: { ttl: 5 * 60 * 1000 } // 5 minutes
};
// 2. Lazy evaluation (comonad structure)
const lazyObs = observation.duplicate(); // Doesn't execute until extracted
// 3. Selective module execution
observe.apply(state, {
modules: ["linear_review"] // Only run specific modules
});
```
---
## Limitations & Constraints
- **Observation is lossy**: Intentional projection (forgetful functor) - some information deliberately discarded
- **Heisenberg-like effect**: Observation changes system (profiling adds overhead)
- **Self-observation incomplete**: Gödel-like limitation (cannot observe itself completely)
- **Context window**: Limited to 10K tokens for analysis
- **Temporal analysis**: Requires history data (not always available)
- **Constitutional**: Article I (Functor) + Article II (Pure & Total) compliance required
**What CAN Be Observed**:
- ✅ Current state (configuration snapshot)
- ✅ Behavior (observable actions)
- ✅ Structure (compositional organization)
- ✅ Interfaces (external interactions)
- ✅ Trends (temporal evolution)
**What CANNOT Be Observed**:
- ❌ Internal implementation (if abstracted)
- ❌ Future (only predictions from trends)
- ❌ Causation (only correlation)
- ❌ Intent (only inferred from behavior)
- ❌ Complete