Spike: Resource Links in MCP tools for snowball knowledge accumulation

## Overview
Explore how Resource Links from MCP 2025-06-18 can create compound knowledge effects by connecting tool outputs to related resources, building on the snowball method principle.

## Core Opportunity
Resource Links allow tools to reference other resources (files, URLs, previous operations) creating a web of connected context that compounds over time. This isn't just linking - it's building a knowledge graph of your development work.

## Principle Alignment

### Snowball Method ❄️
- Each operation adds to accumulated knowledge
- Links create explicit connections between related work
- Knowledge persists and compounds through references

### Systems Stewardship 🏛️
- Links document the "why" by connecting to issues/PRs
- Create breadcrumbs for future maintainers
- Build institutional memory into tool outputs

### OSE (Outside and Slightly Elevated) 🦅
- Links provide the elevated view by showing relationships
- Connect micro-operations to macro-objectives
- Enable pattern recognition across operations

## Target MCP Servers for Trial

### 1. **Git MCP Server** (Natural Fit)
```python
# When creating a commit
return {
"content": "Committed: fix: resolve config parsing error",
"links": [
{"rel": "issue", "href": "github:atxtechbro/dotfiles/issues/456"},
{"rel": "parent", "href": "git:commit:abc123"},
{"rel": "procedure", "href": "file:knowledge/procedures/git-workflow.md"},
{"rel": "worktree", "href": "file:/home/user/worktrees/fix-config"}
]
}

# When creating a PR
return {
"content": "Created PR #789",
"links": [
{"rel": "commits", "href": "git:log:feature/fix-config"},
{"rel": "issue", "href": "github:atxtechbro/dotfiles/issues/456"},
{"rel": "diff", "href": "git:diff:main...feature/fix-config"},
{"rel": "retro", "href": "file:retros/2025-01-16-fix-config.md"}
]
}
```

### 2. **Slash Commands Integration**
```python
# /close-issue command result
return {
"content": "Working on issue #456",
"links": [
{"rel": "issue", "href": "github:atxtechbro/dotfiles/issues/456"},
{"rel": "worktree", "href": "file:/home/user/worktrees/issue-456"},
{"rel": "context", "href": "claude:conversation:abc123"},
{"rel": "previous", "href": "github:atxtechbro/dotfiles/issues/455"}
]
}
```

### 3. **File Operations with Context**
```python
# When editing a procedure
return {
"content": "Updated git-workflow.md",
"links": [
{"rel": "implements", "href": "github:atxtechbro/dotfiles/pull/789"},
{"rel": "previous-version", "href": "git:blob:abc123:git-workflow.md"},
{"rel": "related", "href": "file:knowledge/principles/versioning-mindset.md"},
{"rel": "examples", "href": "git:log:--grep='Principle: versioning-mindset'"}
]
}
```

## Feedback Loop Design

### 1. **Cross-Reference Discovery**
- Links reveal hidden dependencies between files/features
- Track which resources cluster together
- Identify knowledge gaps (resources with few inbound links)

### 2. **Context Preservation**
- Every operation links to its originating issue/PR
- Create audit trail without manual documentation
- Enable "time travel" through operation history

### 3. **Pattern Mining**
```python
# Analyze link patterns to discover:
- Common operation sequences (could become procedures)
- Frequently co-edited files (hidden coupling)
- Knowledge hubs (highly-linked resources)
- Orphaned work (operations with no links)
```

## Implementation Ideas

### Link Types Vocabulary
- `issue`: GitHub issue that triggered work
- `pr`: Related pull request
- `parent`: Previous operation in chain
- `implements`: What this operation implements
- `procedure`: Relevant procedure being followed
- `principle`: Guiding principle
- `worktree`: Physical location of work
- `context`: AI conversation or decision context

### URI Schemes
- `github:owner/repo/type/id` - GitHub resources
- `git:object-type:ref` - Git objects
- `file:path` - Local files
- `claude:conversation:id` - AI conversation context
- `mcp:operation:id` - Previous MCP operations

## Compound Benefits

1. **Automatic Documentation**: Work documents itself through links
2. **Learning Acceleration**: New patterns discovered through link analysis
3. **Reduced Context Switching**: Links maintain context across sessions
4. **Principle Reinforcement**: Operations explicitly link to guiding principles

## Success Metrics

- **Link density**: Average links per operation (more = richer context)
- **Link traversal**: How often links are followed/useful
- **Pattern emergence**: New procedures discovered through link analysis
- **Time-to-understanding**: How quickly can you understand past work

## Implementation Approach

### Phase 1: Basic Linking (Week 1)
- Add issue links to git operations
- Link commits to their PRs
- Track link usage

### Phase 2: Context Web (Week 2)
- Add procedure/principle links
- Link related operations
- Create link visualization tool

### Phase 3: Mining Insights (Week 3)
- Analyze link patterns
- Generate suggested procedures
- Identify optimization opportunities

## Questions to Explore

1. What link patterns indicate high-throughput workflows?
2. How can we auto-generate links without manual work?
3. What visualizations would make link patterns actionable?
4. Can links help identify the critical path in development?

## Next Steps

- [ ] Define minimal link schema for trial
- [ ] Add links to 1-2 critical operations
- [ ] Create simple link-following utility
- [ ] Measure impact on context recovery time

**Principle**: `snowball-method`, `systems-stewardship`, `ose`

No implementation files or tests are named. Start by reviewing the Git MCP Server, slash-command integration, and file-operation examples, then define the minimal link schema and trial scope; done means the listed Phase 1-3 steps and success metrics have been evaluated.

Written by the indexing model from the issue text.