context-surfing

What this skill does

# Context Surfing

## Install

```bash
gh skill install pskoett/pskoett-skills context-surfing
```

Fallback using the Agent Skills CLI:

```bash
npx skills add pskoett/pskoett-skills/skills/context-surfing
```

The agent rides the wave of peak context. When the wave crests, it commits. When it detects drift, it pulls out cleanly — saving state, handing off, and letting the next session catch the next wave.

No wipeouts. No zombie sessions. Only intentional, high-fidelity execution.

---

## Mental Model

Think of context like an ocean wave:

- **Paddling in** = loading the intent frame, plan, and initial context. Energy is building.
- **The peak** = full context coherence. The agent knows exactly what it's doing and why. This is when to execute.
- **The shoulder** = context starting to flatten. Still rideable, but output density is dropping.
- **The close-out** = drift. Contradiction, hedging, second-guessing, or hallucinated details. Wipe-out territory.

The skill's job: ride as long as the wave is good, exit before it closes out.

---

## Lifecycle Position

```
[plan-interview] → [intent-framed-agent] → [context-surfing ACTIVE] → [simplify-and-harden] → [self-improvement]
```

Context Surfing is the execution layer. It wraps all work between intent capture and post-completion review. Simplify-and-harden and self-improvement are the next steps in the pipeline — they run after context-surfing completes, not as conditions that end it.

### Relationship with intent-framed-agent

Both skills are live during execution. They monitor different failure modes:

- **intent-framed-agent** monitors *scope* drift — am I doing the right thing? It fires structured Intent Checks when work moves outside the stated outcome.
- **context-surfing** monitors *context quality* drift — am I still capable of doing it well? It fires when the agent's own coherence degrades (hallucination, contradiction, hedging).

They are complementary, not redundant. An agent can be perfectly on-scope while its context quality degrades (e.g., it's doing the right thing but starting to hallucinate details). Conversely, scope drift can happen with perfect context quality (the agent deliberately chases a tangent). Intent-framed-agent's Intent Checks continue firing alongside context-surfing's wave monitoring.

**Precedence rule:** If both skills fire simultaneously (an Intent Check and a drift exit at the same time), context-surfing's exit takes precedence. Degraded context makes scope checks unreliable — resolve the context issue first, then resume scope monitoring in the next session.

**Cadence separation:** Intent checks fire at scope boundaries — *"before touching a new area/file, before starting a new logical work unit, when current action feels tangential"* (`intent-framed-agent/SKILL.md`). Context-surfing's pre-commit anchor check fires at side-effecting-action moments — specific tool calls, writes, commits, commit-level output. Don't run both in the same beat: if an Intent Check has just fired and resolved cleanly, the next side-effecting action inside that same work unit doesn't need a fresh anchor check — you already re-grounded.

### When to Use the Full Pipeline

Not every task needs all five skills. Match pipeline depth to task complexity:

| Task Type | Skills to Use |
|-----------|---------------|
| Trivial (rename, typo fix) | None — just do it |
| Small (isolated bug fix, single-file change) | `simplify-and-harden` only |
| Medium (feature in known area, multi-file) | `intent-framed-agent` + `simplify-and-harden` |
| Large (complex refactor, new architecture, unfamiliar codebase) | Full pipeline |
| Long-running (multi-session, high context pressure) | Full pipeline with `context-surfing` as the critical skill |

When in doubt, start light. Add skills if you notice drift or quality issues mid-task.

---

## Activation

This skill is live the moment the intent frame and plan are established. No explicit invocation needed.

At activation, load whatever anchors are available:

1. The intent frame (from intent-framed-agent output) — if available
2. The plan (from plan-interview output) — if available
3. The current session state from the Entire CLI (if available)
4. All project context files (see below)

If neither an intent frame nor a plan exists (standalone mode), use the user's original task description combined with project context files as the wave anchor. This is sufficient — the skill degrades gracefully, not catastrophically.

### Entire CLI Integration

Entire CLI ([github.com/entireio/cli](https://github.com/entireio/cli)) provides persistent session state that serves as external ground truth for drift checks and handoff files.

At activation, detect Entire:

```bash
entire status 2>/dev/null
```

- If it succeeds, Entire captures the session passively via hooks — every prompt, tool call, file modification, and checkpoint is recorded to the shadow branch. You don't need to call Entire directly; the harness handles it. Use `entire status` and `entire explain --session <id>` to read back session state when needed.
- If unavailable or failing, continue without it. Use the intent frame and plan file as the wave anchor instead. Track progress via structured comments in your output rather than Entire CLI commands. Do not block execution and do not nag about installation.

The **wave anchor** is not held mentally. It is built from whatever external, persistent artifacts are available — every drift check reads from them directly, never from reconstructed memory.

### Handoffs become learning signals

When context-surfing writes a handoff file on drift exit, that handoff is also captured in the Entire session transcript (via the `Stop` / `SessionEnd` hooks). At cadence, `learning-aggregator --deep` reads those transcripts and extracts:

- Which drift signals most commonly trigger handoffs → potential session design issues
- How many sessions hit drift exit vs completed cleanly → session health baseline
- What context artifacts were missing when drift occurred → promotion candidates for project instruction files

Structured handoff files (`.context-surfing/handoff-<slug>-<timestamp>.md`) with predictable section headers make this parseable. You don't need to do anything special — just keep the handoff format consistent.

- **Full pipeline:** intent frame + plan file + Entire CLI session state
- **Partial pipeline:** whichever of intent frame or plan exists, plus project context files
- **Standalone:** the user's original task description + project context files (CLAUDE.md, AGENTS.md, README.md, etc.)

The anchor is weaker in standalone mode — fewer artifacts to cross-check against — but it is always present. A weak anchor is better than no anchor.

---

## Project Context Files

Before executing anything, scan the project for `.md` files that carry standing context. These are not documentation to skim — they are constraints, decisions, and architectural truth that must stay in the wave at all times.

### Always load at activation
- `CLAUDE.md` — agent configuration, conventions, constraints
- `AGENTS.md` — multi-agent setup, role definitions
- `README.md` — project intent and structure
- Any `.md` in the project root

### Load on demand (when relevant to the current task)
- `.md` files in `skills/`, `docs/`, `.learnings/`, or similar directories
- `SKILL.md` files for any skill being invoked alongside this one

### Rules for context files
1. **They are always part of the wave anchor.** If output contradicts a project `.md` file, that is a drift signal — treat it as a strong one.
2. **Re-read them if the task changes domain or scope.** Don't assume you remembered correctly 20 steps in.
3. **Include their key constraints in the handoff file.** The next session needs to reload them too — note which files were active and whether any were updated during the session.
4. **If a `.md` file is modified during the session**, flag it explicitly in the handoff under a "Modified Context