zoom-out

name	zoom-out
description	Get broader context and a higher-level perspective before editing unfamiliar code. Use when entering an unknown module, when a change feels risky but scope is unclear, or when asked to refactor a section without a clear plan.

Zoom Out

Before touching unfamiliar code, get a mental model of the surrounding system. Prevents the "surgical change that broke three things" failure mode.

When to use

• About to edit a module you haven't read before
• Change feels risky but you're not sure why
• Asked to refactor without a clear plan
• Bug is in a subsystem you don't have a model for

Steps

1. Identify the module's role

Read the relevant section of .claude/skills/repo-guidelines/AGENTS.md file map first. Answer:

• What is this module responsible for?
• What calls it? What does it call?
• What does it NOT do (boundaries)?

2. Map the data flow

For chatbot tasks, trace the real path:

UI (static/js/) → route (routes/) → core logic (core/) → tool/provider → response

Sketch the path on paper or in a comment before editing.

3. Check contracts

• Response shapes: does this module have a defined output contract? (tool-response-contract skill)
• Env dependencies: what env vars does it read? (core/config.py)
• Blueprint registration: where is this blueprint registered? (chatbot_main.py)

4. Find the test coverage

cd services/chatbot && pytest tests/ -v --collect-only 2>&1 | grep <module_name>

If there are tests, read them — they describe intended behavior better than docs.

5. Identify blast radius

Before changing anything, list:

• Files that import this module
• Routes that call this function
• Frontend JS that depends on this response shape

Use grep: grep -r "from core.X import\|import core.X" services/chatbot/

6. State your model

In a comment or to the user, state:

"This module does X. It is called by Y. It must return Z. I plan to change W, which affects A and B."

If you can't complete that sentence, zoom out further before touching code.

Common zoom-out targets in this project

Module	Key thing to understand before touching
core/chatbot.py	The if/elif model routing chain — adding a provider breaks the chain if not inserted correctly
routes/stream.py	SSE generator lifecycle — yield order matters for client state
core/stream_contract.py	complete event payload shape — frontend depends on exact field names
core/tools.py	Auto-trigger keywords and fallback order — changing keywords affects routing
chatbot_main.py	Blueprint registration order — later blueprints can shadow earlier ones
routes/	Flask monolith route layer — primary request/response surface
services/shared_env.py	Loaded once per process — side effects at import time can cause hard-to-debug failures