context-network

What this skill does

# Context Network Lifecycle

You help users build and maintain context networks—structured frameworks for organizing project knowledge that persist across sessions and support both human and agent work. Your role is to diagnose context network state, generate appropriate scaffolding, and coach users on content decisions.

## Core Principle

**Context networks make relationships explicit.** Implicit knowledge doesn't survive session boundaries. Structure enables discovery. The goal is not completeness but navigability.

## Quick Reference

Use this skill when:
- Starting a new project that needs persistent context
- Existing documentation feels scattered or hard to navigate
- Agent effectiveness is degrading due to missing context
- Context-retrospective identified gaps to address

Key states:
- **CN0:** No Network - Project has no context network
- **CN1:** Scattered Docs - Documentation exists but isn't organized as a network
- **CN2:** Siloed Structure - Structure exists but connections missing
- **CN3:** Navigation Broken - Connections exist but hard to traverse
- **CN4:** Guidance Unclear - Structure works but agent instructions fail
- **CN5:** Relationships Missing - Impacts/dependencies undocumented
- **CN6:** Maintenance Failing - Network exists but drifts from reality

---

## The States

### State CN0: No Network
**Symptoms:** No `.context-network.md` file. No `context/` directory. Documentation scattered in README or absent entirely. Agent asks same questions each session.

**Key Questions:**
- What type of project is this? (software, research, creative, personal knowledge)
- Who will use this context? (solo, team, agents)
- What's the expected lifespan?

**Interventions:**
- Run Bootstrap Mode (see below)
- Generate discovery file and initial structure
- Coach on minimal viable content

### State CN1: Scattered Docs
**Symptoms:** README.md has grown unwieldy. docs/ folder exists but files aren't connected. Architecture decisions buried in comments or commit messages. Agent finds partial info but misses connections.

**Key Questions:**
- What documentation already exists?
- Which docs are still accurate?
- What relationships exist between these documents?

**Interventions:**
- Scan for existing documentation
- Propose migration plan to context network structure
- Generate relationship mappings for migrated content

### State CN2: Siloed Structure
**Symptoms:** Context network exists with clear directory structure. Files are well-organized within domains. But cross-references are sparse. Agent finds info within domains but misses cross-domain implications.

**Key Questions:**
- Which domains affect each other?
- What changes in A typically require changes in B?
- Are there shared concepts with different names in different domains?

**Interventions:**
- Generate relationship templates
- Coach on identifying cross-domain connections
- Create hub documents that bridge domains

### State CN3: Navigation Broken
**Symptoms:** Information exists and is connected, but hard to find. status.md is stale. No clear entry points for common tasks. Agent reads many files to find what it needs.

**Key Questions:**
- What are the most common tasks agents perform?
- Which files get read most often? Least often?
- Are there orphan documents no one accesses?

**Interventions:**
- Create/update hub documents
- Establish task-based navigation guides
- Prune or consolidate orphan content

### State CN4: Guidance Unclear
**Symptoms:** Context network is well-structured. CLAUDE.md exists but agents still make wrong decisions. Instructions exist but aren't followed. Agent behavior inconsistent with documented patterns.

**Key Questions:**
- Which agent behaviors are problematic?
- Are instructions ambiguous or contradictory?
- Is guidance too abstract to act on?

**Interventions:**
- Refine CLAUDE.md with specific, actionable instructions
- Add examples to abstract guidance
- Create decision trees for common choices

### State CN5: Relationships Missing
**Symptoms:** Changes in one area unexpectedly break another. Dependencies discovered mid-task. Impact of decisions unclear until after implementation. Agent doesn't know what else to check.

**Key Questions:**
- What recent changes had unexpected ripple effects?
- Which components share data, state, or interfaces?
- What implicit contracts exist between areas?

**Interventions:**
- Document dependency maps
- Create impact relationship documentation
- Add "affects" and "affected-by" sections to key nodes

### State CN6: Maintenance Failing
**Symptoms:** Context network was once useful but now drifts from reality. status.md describes old state. Decisions documented but not updated. Agent references outdated information.

**Key Questions:**
- When was the network last meaningfully updated?
- What triggers should cause updates?
- Who/what is responsible for maintenance?

**Interventions:**
- Establish maintenance cadence
- Define update triggers
- Integrate with context-retrospective skill for continuous improvement

---

## Operational Modes

### Bootstrap Mode (CN0/CN1 → CN2)

Use when starting fresh or organizing scattered documentation.

**Process:**

#### 1. Existing Documentation Scan

Automatically scan for:
- `README.md`, `docs/`, `documentation/`
- Architecture decision records (ADRs, `adr/`, `decisions/`)
- Design docs, planning files
- Package files (`package.json`, `Cargo.toml`, `pyproject.toml`) for project metadata
- Existing `.claude/` or memory bank structures

Report findings:
```
Found existing documentation:
- README.md (2.3kb) - Project overview, setup instructions
- docs/architecture.md (5.1kb) - System design
- docs/api.md (3.2kb) - API reference

Recommendation: Migrate architecture.md to context/architecture/,
keep README.md in place as user-facing doc.
```

#### 2. Project Discovery Questions

Ask:
- **Project type?** Software / Research / Creative / Personal Knowledge
- **Primary domains?** (For software: frontend, backend, data, infra, etc.)
- **Stakeholders?** Solo / Team / Agents / Mixed
- **Expected lifespan?** Short-term / Long-term / Indefinite
- **Which discovered docs to incorporate vs. leave in place?**

#### 3. Structure Generation

Generate based on project type:

**For software projects:**
```
context/
├── status.md           # Current state, active work
├── decisions.md        # Architecture decisions
├── glossary.md         # Domain vocabulary
├── architecture/       # System design docs
├── domains/            # Domain-specific context
│   ├── [domain-1]/
│   └── [domain-2]/
└── processes/          # Workflows, procedures
```

**For research projects:**
```
context/
├── status.md           # Current research state
├── decisions.md        # Methodology decisions
├── glossary.md         # Technical vocabulary
├── sources/            # Source tracking
├── findings/           # Research discoveries
└── questions/          # Open questions, hypotheses
```

**For creative projects:**
```
context/
├── status.md           # Current project state
├── decisions.md        # Creative decisions
├── glossary.md         # World/project vocabulary
├── world/              # Worldbuilding, setting
├── characters/         # Character information
└── structure/          # Plot, outline, structure
```

**For personal knowledge:**
```
context/
├── status.md           # Current focus areas
├── decisions.md        # System decisions
├── glossary.md         # Personal vocabulary
├── areas/              # Life areas (PARA-style)
├── projects/           # Active projects
└── resources/          # Reference material
```

Also generate:
- `.context-network.md` discovery file in project root
- `CLAUDE.md` with basic agent instructions (if not present)

#### 4. Migration Execution

For docs user wants to incorporate:
- Copy/move to appropriate context network location
- Convert format if needed (e.g., flatten ADRs into decisions.md entries)
- Update internal cross-references
- Add relationship metadata

####