The Guided Spike Workbook

What It Is

The CF Agents evaluation began with “I want to build something better than CF Agents,” but no concrete differentiation. Working with the framework exposed problems that the initial comparison had not specified: granular streaming state, chat-first assumptions, missing generated client types and unclear reconnection behavior. Those encounters gave the evaluation positions to develop rather than a vague competitive ambition.

A Guided Spike Workbook arranges that kind of learning into small experiments. AI generates a phased document containing tasks, time limits and places to record evidence. Each phase requires an opinion about what the experiment revealed. The workbook holds the context so the person can use their attention to operate the system and judge what happens.

The written synthesis records an opinion grounded in the attempt, including friction and limits rather than only successes.

Read this diagram

Name the question → Run the small experiment → Keep the evidence → Write what you now think → Name the question.

The Simulation Trap

Documentation can become easy to explain before a system becomes easy to use. A reader learns the vocabulary and architecture, then discovers during implementation that the documentation omitted a constraint. The feeling of understanding arrived before that constraint had been tested.

Reading appears to engage different processes from building. Comprehension matches patterns in text, while using the system encounters what actually works or fails. The gap between understanding a description and having an informed opinion about the system often requires this friction.

The workbook makes experiments, evidence and synthesis required parts of progress. A person cannot complete a phase by continuing to simulate how the system probably behaves; they must encounter it and record what happened.

The Fundamental Distinction: Extraction vs Generation

Clarity Bear asks questions to uncover knowledge the person already has but cannot articulate. A spike acquires knowledge the person does not yet possess by arranging contact with an external system.

Clarity Bear: Extract → Process → Clarify (internal source)
Guided Spike: Structure → Experiment → Synthesize (external source)

Both use AI to provide structure and retain human judgment as the sensor. Applying Clarity Bear to missing external knowledge can make the confusion articulate without resolving it. Running experiments when the real need is to extract existing understanding can instead scatter attention across tests without a coherent synthesis.

Why Standard Learning Often Fails

Self-directed learning requires remembering the context, deciding what to try, resolving ambiguity and doing the work. Interruptions then require the context to be restored. Each operation has a separate cost, and together they can consume more than 6 willpower units before learning begins.

A workbook appears to reverse that cost structure by doing much of the preparation in advance. “Phase 2: Modify the Chat Agent (30 min)” identifies the next task, and “Add a mood property that persists and syncs” provides a concrete success condition. Opening the document restores the context without requiring it to remain in working memory.

The person reacts to an existing prompt rather than generating the next experiment from nothing. This is the distinction between discrimination and generation. Answering a multiple-choice question costs less than formulating a question, and trying a specified change costs less than deciding which change would be informative. The quality of the learning then depends more on workbook design and less on the person's ability to invent good questions while working.

The Human-as-Sensor Architecture

An ordinary self-directed session assigns almost all the preparation to the learner:

Human does: context loading + task definition + execution + synthesis
AI does: answers questions when asked

The workbook reallocates that preparation:

Human does: execution (small discrete tasks) + synthesis ("Opinion Formed")
AI does: context structure + task definition + forcing function design

Human generative capacity tends to deplete with use, while AI can repeatedly generate structure. The person supplies something the model does not have: the experience of friction, taste, judgment and fit while using the tool. The workbook records both the generated structure and those observations.

AI can explain React hooks without encountering a stale closure in the learner's codebase. Debugging that closure or seeing state synchronization break reveals where the description fails to predict production behavior. That sensor data appears to require contact rather than further conversation.

Anatomy of a Spike Workbook

Phase Structure

A spike contains three to five phases of increasing depth. The five-phase form gives each later experiment the familiarity established by the earlier one:

Installation precedes modification because the initial behavior must be visible before a change can be assessed. A real build then tests more than the shallow edit, and edge cases test what the successful build leaves unexamined.

The Opinion Formed Forcing Function

Every phase ends with a mandatory synthesis section:

**Opinion Formed — State Management:**

The framework's state approach feels:

The good:

The bad:

What I'd do differently:

The next phase remains unavailable until the assessment is written. “I looked at state management” does not establish a conclusion; explaining what was good, bad or worth changing requires a position. The resulting assessments accumulate into an overall view and leave a searchable record.

The opinions are the output of the learning process. Experiments collect the data needed to form them. Completing tasks without those opinions misses the reason for running the spike.

Evidence Collection via Paste Boxes

An assessment needs the work that supports it. The workbook supplies places for the actual code, observed outcome and friction:

**What I tried:**
```typescript
// Paste actual code here
```

**Did it work?**
Yes/No + what happened

**Friction encountered:**

Claiming to have tested state management is insufficient without the change that was made and what it produced. The completed workbook retains code, errors, observed behavior and recognized patterns. Those artifacts ground the opinion and make a claim of testing distinguishable from speculation.

Time-Boxing Prevents Rabbit Holes

A time box permits an initial opinion to be sufficient for the phase. State management need not be completely understood within 30 minutes because a later real build will test it more deeply. That permission prevents “one more thing” from turning a two-hour session into eight hours of wandering.

The limits also force breadth before depth and provide a completion every 30–60 minutes. Finishing a bounded phase maintains momentum while perfectionism would keep attention on one aspect indefinitely.

Spike vs Other Learning Modes

Spike vs Passive Research (Reading Docs)

Documentation supplies a mental model. Building tests that model against constraints that may be absent from the text. Passive reading can feel clear without producing an artifact, and the understanding is easy to forget. A spike leaves working code and opinions, with the encounter encoded through action.

Spike vs Tutorial Following

A tutorial follows the author's route through the author's use case and usually aims for a working result. A spike explores the learner's use case, including the edges the tutorial did not cover. Explicit assessment matters when the learner must decide something the tutorial never asked.

Spike vs "Just Build Something"

Unstructured building leaves the next move, stopping point and synthesis to the learner. Context must remain in their head, and important aspects can be missed while another aspect absorbs the session. A workbook supplies phases, completion conditions and coverage of the dimensions that matter. It suits a limited period in which the learner needs informed opinions rather than unrestricted exploration.

When to Use a Spike

A known missing fact can be researched directly or asked of AI. A spike addresses two different uncertainties: unknown gaps in a mental model and the risk that an assumed implementation will not be feasible.

Optimal Use Cases

A new tool or framework needs an assessment of how it behaves in use. A risky technical commitment benefits from finding a blocker in a two-hour spike rather than during a two-week implementation. Comparing alternative tools works by running a spike for each and comparing their Opinion Formed sections. Learning a system that later work will depend on also requires understanding that survives actual use.

Not Optimal For

Known unknowns call for research. A vague direction whose details are already implicit calls for Clarity Bear. A well-specified technical task can proceed to implementation, and a time-sensitive decision may need a quick investigation rather than a full spike.

The Cold Start Problem Eliminated

“I want to learn X” leaves the starting point, learning path and stopping condition unspecified. AI can generate the phases, tasks, success criteria and synthesis prompts before the session begins. Opening the workbook then presents the first action and its time limit immediately.

The stated activation-cost change is from more than 6 units to about 1 because the ambiguity has been removed. Like The Braindump and a morning routine, the workbook provides external structure when the internal state cannot generate it. Here the structure supports learning. Working memory holds 4–7 items; the document has no corresponding limit on retained context.

Generating a Spike Workbook

The generation prompt includes what the learner needs to understand, what they need an opinion about and which assumption needs a feasibility test:

I want to learn [X]. Generate a spike workbook with:

**Learning goals:**
- Understand [core concept A]
- Form opinion on [aspect B]
- Validate feasibility of [assumption C]

**Constraints:**
- Total time: [2-4 hours]
- Prior knowledge: [what I already know]
- Ultimate goal: [why I'm learning this]

Structure it as phases with time-boxes, paste boxes for code/evidence,
and "Opinion Formed" synthesis sections after each phase.

Quality Markers of a Good Spike Workbook

Tasks need to be concrete enough to complete within their time boxes, with an observable answer to whether they worked. Later phases need to test understanding built earlier. Opinion formation is mandatory, edge cases are explicit, and the final synthesis returns to the learning goals.

What AI Should Generate

The resulting document contains phases of increasing depth, typically with 30–60-minute time boxes, specific tasks and evidence boxes. “Add a mood property that persists” gives a task a verifiable result. “What happened?” collects an observation, “Opinion Formed” requires an assessment, and “What this means for my project” connects the assessment to the decision the spike serves.

Integration with AI Stack

Clarity Bear extracts latent knowledge. The spike creates encounters that internalize knowledge from outside the person. Gradient extraction turns an outcome into a suggested direction, and the braindump makes implicit complexity explicit. Each operates on a different missing part of the reasoning.

The Learning Pipeline

Vague interest → Braindump → Clarity Bear → Spike → Implementation

1. "I think I should learn X" (vague)
2. Braindump what you know and don't know (externalize)
3. Clarity Bear to identify specific learning goals (clarify)
4. Generate spike workbook for those goals (structure)
5. Execute spike, collect opinions (contact)
6. Build on verified understanding (implement)

When Each Tool Activates

“I don't know what I think about this” calls for externalization in a braindump. “I know something's wrong but can't articulate it” calls for extraction through Clarity Bear. “I don't know if this will work” or “I don't understand this system” calls for a spike. When a decision remains uncertain after the experiments, gradient extraction can examine their outcomes for direction.

Example: CF Agents Spike Results

The CF Agents experiments replaced the initial vague competitive position with specific observations. “The setState way isn't great for granular streamable state” identified a state-management problem. Chat-first assumptions, missing automatically generated client types and unclear reconnection handling identified other parts of the system to reconsider.

The friction led to a proposed primitive:

interface StreamingVar<T> {
  current: T;
  status: 'streaming' | 'done' | 'error';
  value(): Promise<T>;
}

Streams could be treated as first-class values. “Streams are values, not side effects” expressed that position, alongside “Next.js for agentic systems” and “Write agents like classes.” The code and encountered friction gave those phrases a concrete design to refer to.

The initial anxiety was “I'm behind, I don't know enough.” After the experiments, there was a new primitive and a clearer direction, providing practical support for the method. The question of what would work better arose from using the system, where the friction could be encountered rather than anticipated from documentation alone.

Related Concepts

• Clarity Bear extracts implicit understanding that the learner already has.
• Reality Contact supplies information through the actual system.
• Forcing Functions explains the workbook's requirement to experiment and synthesize before progressing.
• Activation Energy concerns the starting cost reduced by predefined structure.
• Working Memory explains why the context belongs in the document.
• Experience Extraction draws learning from the high-information experiences a spike creates.
• Question Theory explains the value of bounded prompts.
• The Braindump makes complexity explicit before learning goals are chosen.
• Effective AI Usage describes the consultant role in which AI supports human judgment.
• Skill Acquisition treats each experiment as a discrete practice instance.
• Gradients examines the direction suggested by an experiment's result.
• Discretization divides learning into bounded phases.