Agentic Exploration Protocol

The Meta-Pattern

Your job is to:

1. Bound — Define what you're exploring and what's out of scope
2. Map — Build a structural overview before diving deep
3. Probe — Test your model with targeted investigations
4. Synthesize — Construct coherent understanding from fragments

Principle 1 Uncertainty Mapping

The Uncertainty Inventory

## Known Knowns
Things I understand and can explain.

## Known Unknowns
Specific questions I need to answer.

## Suspected Structure
Hypotheses about how things connect.

## Boundary Conditions
What's in scope vs out of scope.

## Unknown Unknowns (meta)
Areas where I don't even know what questions to ask.

Why This Matters

Exploration without structure becomes wandering. The inventory:

• Prevents revisiting already-understood areas
• Prioritizes high-uncertainty regions
• Tracks progress toward understanding
• Identifies when you're "done enough"

Uncertainty Types

Principle 2 Exploration Journal

Schema

## Session [N]: [Focus Area]

### Starting State
- What I thought I knew: [summary]
- Open questions: [list]
- Hypothesis: [what I expect to find]

### Explorations

#### Probe 1: [Description]
- Action: What I did
- Found: What I observed
- Implies: What this means for my model
- New questions: What this raises

#### Probe 2: [Description]
...

### Session Synthesis
- Model updates: How my understanding changed
- Confirmed: Hypotheses that held
- Refuted: Hypotheses that failed
- Deferred: Questions for later
- Connections: Links to other areas

Journal Discipline

1. Capture observations raw — Don't interpret while recording
2. Separate observation from inference — "I saw X" vs "This means Y"
3. Track model evolution — How did your understanding change?
4. Note surprises — Surprises reveal model gaps
5. Cross-reference — Link related discoveries

Principle 3 Exploration Modes

1. State prediction: "I expect X because [reasoning]"
2. Investigate: Look at actual behavior/code/data
3. Compare: Did reality match prediction?
4. If match: Confidence increases
5. If mismatch: WHY? Update model.

Principle 4 Agent Architecture

Role Decomposition

Coordination Protocol

while uncertainty > acceptable_threshold:

    # Phase 1: Survey (if entering new area)
    if new_territory:
        map = SURVEYOR.scan(territory)
        questions = extract_questions(map)
        priorities = rank_by_uncertainty(questions)

    # Phase 2: Investigate priority areas
    for question in priorities[:K]:

        if question.type == STRUCTURAL:
            finding = DIVER.investigate(question.target)

        elif question.type == FLOW:
            finding = TRACER.follow(question.scenario)

        elif question.type == BEHAVIORAL:
            finding = DIVER.probe(question.target)

        journal.record(question, finding)

    # Phase 3: Synthesize periodically
    if journal.entries > synthesis_threshold:
        model = SYNTHESIZER.integrate(journal)

        # Phase 4: Challenge the model
        holes = CHALLENGER.attack(model)
        if holes:
            priorities.extend(holes)
        else:
            uncertainty = estimate_remaining(model)

    # Phase 5: Decide next focus
    if stuck_in_one_area:
        switch_to_adjacent_area()
    if model.confidence > threshold:
        mark_area_understood()

Principle 5 Exploration Heuristics

Principle 6 The Depth Protocol

Depth Calibration Questions

1. Could I implement this from my understanding?
   No → probably too shallow

2. Could I explain this to someone in 2 minutes?
   No → might be too deep (or too shallow)

3. Do I know where this fits in the bigger picture?
   No → too deep without context

4. Can I predict what I'll find in adjacent areas?
   No → haven't extracted patterns yet

Principle 7 Exploration Patterns

Ring 0: Entry point / main concept
Ring 1: Direct dependencies / immediate context
Ring 2: Secondary dependencies / broader context
Ring 3: Ecosystem / external integrations

Each ring complete before next.

1. What is the #1 thing I need to understand?
2. Investigate until answered.
3. What's the next most critical question?
4. Repeat.

Let questions drive exploration path.

1. What does this remind me of?
2. How is it similar?
3. How is it different?
4. What explains the differences?

Build understanding through contrast.

1. What was version 0?
2. What changed and why?
3. What constraints shaped decisions?
4. What's vestigial vs. essential?

Git history, release notes, design docs.

1. What could go wrong?
2. What are the trust boundaries?
3. Where are the assumptions?
4. What happens at the edges?

Security/reliability mindset.

1. If I were building this, what would I need?
2. What problems would I face?
3. How would I solve them?
4. How does actual compare to my imagined version?

Predict then compare.

Principle 8 Synthesis Artifacts

Nodes: Key concepts, components
Edges: Relationships (uses, contains, depends-on, etc.)
Annotations: Brief descriptions

Visual representation of system structure.

Term: Definition in context of this system.

Build shared vocabulary.
Important: Note where this system's usage
differs from common usage.

Decision: What choice was made
Context: What constraints existed
Alternatives: What was considered
Rationale: Why this choice

Captures the "why" that code can't show.

Trigger: What initiates the flow
Steps: Numbered sequence through system
Data: What transforms at each step
Result: What outcome

Executable understanding of key flows.

Question: What I still don't understand
Attempts: What I tried to find out
Blocker: Why I couldn't answer
Priority: How important to resolve

Explicit acknowledgment of gaps.

Principle 9 Knowing When You're Done

Completion Criteria

• Can explain the system's purpose in one sentence
• Can identify the 3-5 key abstractions
• Can trace the primary use case end-to-end
• Can predict behavior for new scenarios
• Predictions match reality when tested
• Can explain why it's designed this way
• Know where to look for any specific question
• Diminishing returns on further exploration

"Good Enough" Thresholds

The "Teach Test"

Try to explain your understanding.
Where does the explanation:
- Feel confident?    → Actually understood
- Get hand-wavy?     → Partially understood
- Require hedging?   → Not understood

The explanation reveals your actual knowledge.

Principle 10 Memory System

Architecture: SQLite + Embeddings + Links

Schema for Exploration

-- Exploration findings/observations
CREATE TABLE findings (
    id INTEGER PRIMARY KEY,
    session_id TEXT NOT NULL,
    area TEXT NOT NULL,         -- module, file, concept
    finding_type TEXT,           -- structural|behavioral|causal|boundary|conceptual
    content TEXT NOT NULL,
    implications TEXT,
    questions TEXT,              -- JSON array of new questions
    confirmed INTEGER,           -- has this been validated?
    created_at TIMESTAMP,
    embedding BLOB               -- for semantic search
);

-- Zettelkasten-style links between findings
CREATE TABLE links (
    from_id INTEGER,
    to_id INTEGER,
    relation TEXT,              -- supports|contradicts|refines|questions|similar
    note TEXT
);

-- Fast tag-based filtering
CREATE TABLE tags (
    finding_id INTEGER,
    tag TEXT
);

Usage

from agent_memory import AgentMemory

mem = AgentMemory("./exploration.db")

# Log a finding
finding_id = mem.log_finding(
    session_id="codebase_explore_001",
    area="src/encoder",
    finding_type="structural",
    content="Encoder uses varint for all integer types",
    implications="Space-efficient but CPU cost on decode",
    questions=["Why not fixed-width for small ints?"],
    tags=["encoder", "varint", "design-decision"]
)

# Link to related finding
mem.add_link(
    from_id=finding_id, from_type="finding",
    to_id=3, to_type="finding",
    relation="supports",
    note="Both relate to space optimization"
)

# Query: all structural findings in encoder
findings = mem.get_findings(
    area="encoder",
    finding_type="structural"
)

# Query: unconfirmed findings (need validation)
uncertain = mem.get_findings(confirmed_only=False)

# Semantic search
related = mem.search_text("memory allocation")

Finding Types Map to Uncertainty Types

Why This Works

• Queryable: SQL queries beat grep through markdown files
• Linkable: Zettelkasten connections reveal patterns across areas
• Searchable: Embeddings find semantically related findings
• Exportable: Generate markdown reports when needed for humans
• Portable: Single SQLite file, no server required

Appendix: Domain Instantiation

Survey:     File tree, README, entry points
Dive:       Core module, critical path
Trace:      Main user flow, error handling
Probe:      "If I change X, what breaks?"
Synthesize: Architecture diagram, module responsibilities

Survey:     Survey papers, key authors, major conferences
Dive:       Seminal papers, foundational techniques
Trace:      Citation chains (forward and backward)
Probe:      "Can I reproduce this result?"
Synthesize: Research map, open problems, key debates

Survey:     Documentation, endpoint list, data models
Dive:       Core resources, authentication, rate limits
Trace:      Complete request lifecycle
Probe:      "What happens if I send malformed X?"
Synthesize: Mental model of system behavior, gotchas

Survey:     Existing solutions, stakeholder needs, constraints
Dive:       Specific failure modes, edge cases
Trace:      User journeys, data flows
Probe:      "Would approach X handle scenario Y?"
Synthesize: Problem decomposition, solution space map

Survey:     Schema, row counts, column types, missingness
Dive:       Distributions, outliers, specific fields
Trace:      Relationships between tables/fields
Probe:      "If X is true, what should Y look like?"
Synthesize: Data quality assessment, feature hypotheses