Explore-Reason-Act Methodology

Before modifying code, always follow the Explore -> Reason -> Act cycle. Modifying without exploration is the #1 cause of incorrect fixes and repeated failures.

Phase 1: Explore (Read Before Write)

Mandatory exploration patterns before code changes:

# 1. Understand error context (failing file + surrounding lines)
grep -rn "ERROR_SYMBOL" core/ tests/ --include="*.py" -l

# 2. Find all usage sites of the target symbol
grep -rn "ClassName\|function_name" core/ tests/ --include="*.py"

# 3. Check the dependency chain
grep -rn "from.*import.*ClassName" core/ --include="*.py"

# 4. Check test expectations
grep -rn "ClassName\|function_name" tests/ --include="*.py"

Rules:

• Do not edit a file you have not read
• Do not assume a symbol exists without grep verification
• Read the entire function/class, not just the error line
• Check at least 2 levels of callers/callees
• If 10+ files have the same error, find the common root cause

Phase 2: Reason (Hypothesis Formulation)

State the following before writing fix code:

1. Observation: "I confirmed X in files A, B, C"
2. Hypothesis: "The root cause is Y. Evidence: Z"
3. Prediction: "Fixing Y will simultaneously resolve errors in A, B, C"
4. Impact scope: "This change affects N files / M call sites"

Prohibited patterns:

• Fixing compiler errors individually when a common root cause exists
• Guessing API signatures without reading source or documentation
• Assuming dependency versions without checking pyproject.toml/config

Phase 3: Act (Apply Minimal Changes)

1. Apply only the minimal change for the root cause
2. Run build/test immediately after the change
3. If new errors occur, return to Phase 1 (no stacking fixes)
4. Escalate if unresolved after 3 iterations

Output Contract

Every fix attempt must include:

• exploration_summary: What was read and what was discovered
• hypothesis: Evidence-based root cause hypothesis
• change_description: What was changed and why
• verification: Build/test results after the change

GEODE Application

Scenario	Explore	Reason	Act
Hook handler modification	Read core/hooks/system.py + bootstrap registration entirely	Handler-exists-but-unregistered hypothesis	Wire one handler, fire-path test
Tool addition	Read core/tools/definitions.json, the category handler, core/tools/registry.py, and core/tools/composition.py	Trace schema, registration, and execution ownership; CLI handlers live under core/cli/tool_handlers/	Implement following the existing path, test schema/execution parity
Memory change	Read core/memory/context.py + identity/profile/org/project/session hierarchy	Verify five-tier assembly order and budgets	Modify only the relevant tier, assembly test

For current package boundaries and context ownership, use naming conventions, not the retired six-layer or service-locator DI model.