ericmjl/epistemic-resourcefulness

Epistemic Resourcefulness

Before interacting with any unfamiliar system, find the authoritative source of truth about its structure. Do not guess, scan blindly, or trial-and-error your way to an answer when a definitive source exists.

The Core Rule

For every structured system, there is an authoritative description of that structure. Locate it first. Then act.

Quick Reference: Authoritative Sources by System Type

| System | Authoritative source | How to access | |--------|---------------------|---------------| | SQLite database | Schema | sqlite3 file.db ".schema" | | Any SQL DB | Table/column info | DESCRIBE table / information_schema | | CLI tool | Help text | tool --help or man tool | | REST API | OpenAPI/Swagger spec | /docs, /openapi.json, or repo | | Python package | Installed interface | python -c "import pkg; help(pkg)" | | File format | Format library docs | Check PyPI/npm for a parser library | | Config system | Schema/defaults | Config file comments, --show-config | | Running process | Its own API | Check docs for management interface | | Codebase | Entry points | README, AGENTS.md, __init__.py, index.ts | | npm/Python project | Dependencies | package.json, pyproject.toml |

The Anti-Pattern: Brute-Forcing

Brute-forcing looks like:

• Reading a binary file byte-by-byte without knowing its format
• Querying a DB with guessed column names
• Scanning every file in a directory when a manifest exists
• Repeating variations of a failed command hoping one works
• Trying API endpoints at random

Brute-forcing is wasteful and unreliable. It signals that the agent skipped the investigation step.

The Pattern: Investigate First

When facing an unfamiliar system:

1. Identify what kind of system it is (database? CLI? API? file format?)
2. Look up the authoritative source for that system type (see table above)
3. Retrieve the structure (schema, help text, spec, manifest)
4. Then act with knowledge of the actual structure

Worked Example

Task: Read conversation history from the OpenCode SQLite database.

Brute-force approach (wrong):

cat ~/.local/share/opencode/opencode.db   # binary garbage
ls ~/.local/share/opencode/               # scanning around

Resourceful approach (correct):

# Step 1: Identify - it's SQLite
# Step 2: Authoritative source = schema
sqlite3 ~/.local/share/opencode/opencode.db ".tables"
sqlite3 ~/.local/share/opencode/opencode.db ".schema session"
# Step 3: Now query with known column names
sqlite3 ~/.local/share/opencode/opencode.db \
  "SELECT id, title FROM session ORDER BY time_created DESC LIMIT 5;"

A Note on "Obvious" Systems

Even systems you think you know may have changed or have non-obvious quirks in this specific environment. When something isn't working as expected, resist the urge to iterate blindly - treat it as an unfamiliar system and re-run the investigation step.