Spike: Trial _meta field in MCP servers for throughput-increasing feedback loops

## Overview
Deep exploration of how the `_meta` field from MCP 2025-06-18 can create feedback loops that increase throughput by making agent work more observable and aligned with our principles.

## Core Opportunity
The `_meta` field allows attaching metadata to tool results without polluting the main content. This creates a parallel data stream for observability without interfering with tool functionality.

## Principle Alignment

### Tracer Bullets 🎯
- Each tool call becomes a tracer round with trajectory data
- `_meta` can carry timing, decision points, alternatives considered
- Enables "walking fire onto target" by tracking what's working

### Transparency in Agent Work 👁️
- Agent reasoning becomes visible through metadata
- Decision paths and context preserved for post-PR retros
- Creates audit trail without cluttering output

### Throughput Definition 📈
- Measure actual throughput: execution time, files touched, complexity handled
- Track which operations compound vs create debt
- Data-driven identification of constraints

## Target MCP Servers for Trial

### 1. **Git MCP Server** (Highest Value)
```python
# Current output
return "Created branch feature/new-feature from main"

# With _meta
return {
"content": "Created branch feature/new-feature from main",
"_meta": {
"execution_ms": 45,
"base_commit": "abc123",
"worktree_path": "/home/user/worktrees/feature-new",
"principle": "versioning-mindset",
"issue_number": 456,
"parent_operation": "git_status_check"
}
}
```

**Why start here**:
- Git operations are the heartbeat of development flow
- Natural fit for tracking commit chains, branch relationships
- Supports worktree workflow isolation tracking

### 2. **File System Operations**
```python
# Track cognitive load and operation patterns
return {
"content": "File written successfully",
"_meta": {
"bytes_written": 1024,
"operation_chain": ["read", "modify", "write"],
"related_files": ["config.json", "README.md"],
"cognitive_load": "low", # simple edit vs complex refactor
"snowball_contribution": "added_procedure"
}
}
```

**Why valuable**:
- Track which files get modified together (hidden dependencies)
- Identify high-traffic files that might need refactoring
- Measure complexity of changes

## Feedback Loop Design

### 1. **Operation Chaining**
- Use `parent_operation` in _meta to track tool call sequences
- Identify common patterns that could become procedures
- Detect inefficient operation chains

### 2. **Principle Tracking**
- Tag operations with active principles
- Measure which principles drive which outcomes
- Create data for principle effectiveness

### 3. **Throughput Metrics**
```python
"_meta": {
"throughput_impact": {
"files_per_minute": 2.5,
"decisions_automated": 3,
"context_switches_avoided": 2
}
}
```

## Implementation Approach

### Phase 1: Minimal Trial (1-2 tools)
1. Add optional `_meta` to `git_status` and `git_commit`
2. Log metadata to `~/mcp-meta-analytics.jsonl`
3. Run for 1 week, analyze patterns

### Phase 2: Expand Based on Learning
1. Add to high-frequency tools identified in Phase 1
2. Create aggregation scripts for pattern analysis
3. Feed insights back into procedures

### Phase 3: Automate Insights
1. Daily analysis of metadata patterns
2. Auto-generate suggested procedure updates
3. Track throughput improvements over time

## Success Metrics

- **Leading indicators**: Tool calls per task, execution time trends
- **Lagging indicators**: PRs per day, reduced error rates
- **Principle metrics**: Which principles appear most in successful flows

## Questions to Explore

1. What metadata would reveal bottlenecks in our workflow?
2. How can _meta help identify the 20% of work that enables 80% productivity?
3. What patterns in _meta could trigger automatic procedure updates?

## Next Steps

- [ ] Choose 2 high-frequency tools for initial trial
- [ ] Design minimal metadata schema
- [ ] Create simple analytics script
- [ ] Run 1-week trial with daily reviews

**Principle**: `tracer-bullets`, `transparency-in-agent-work`, `throughput-definition`

Start by locating the MCP implementations for git_status and git_commit, then review how tool results are currently returned. Define the minimal optional _meta schema, logging to ~/mcp-meta-analytics.jsonl, and the simple analytics script; done means a one-week trial produces metadata that can be reviewed against the listed throughput metrics.

Written by the indexing model from the issue text.