ericmjl 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:
- Identify what kind of system it is (database? CLI? API? file format?)
- Look up the authoritative source for that system type (see table above)
- Retrieve the structure (schema, help text, spec, manifest)
- 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.