python-explore

Python Explore

Build a structural model of Python code with pyeye before reading or changing it — orient cheap, drill on demand.

The Model: Progressive Disclosure

pyeye answers questions in three widening steps. Start at the cheapest that answers your question; only go wider when you need to.

1. Orient (cheap): resolve a name to a canonical handle, then inspect it for structure, or outline a module/class for its skeleton.
2. Drill (on demand): expand one edge from a handle to see its immediate neighbours (members, callees, importers, subclasses…).
3. Trace (across hops): trace follows edges multiple hops to see structure across a call chain, import closure, or member tree.

Canonical handles are the currency. A handle is Python's own dotted notation — a.b.c.Name — anchored at the definition site, stable across edits, and the same no matter which import alias you arrived through. Everything downstream takes a handle. pyeye returns pointers and structured facts, never source — when you need the actual code, Read the file:line it points you at.

Skill Type: Mixed Rigid/Flexible

Rigid gates (non-negotiable):

• Your first move on unfamiliar Python is pyeye, not a blind Read().
• Never re-explore what pyeye already surfaced in this conversation.

Flexible (use judgement):

• How deep to go (a single inspect, or a multi-hop trace).
• Which primitives and edges to call.
• Whether to write out a mental-model summary — do it when it helps the user, not as ceremony (see Stating Your Mental Model).

Do NOT Trigger When

• User says "show me", "print", "display", "read this file" — respect explicit requests, use Read().
• User says "run", "execute" — that is not exploration.
• User asks "what's the syntax for" — a language question, not a codebase question.
• Single-line typo/string fix where the user gives the exact location.
• Adding a new test case only (not modifying the code under test).
• pyeye output for this symbol is already visible in conversation context — skip straight to using it.