notebook-guidance

Notebook Guidance

When to Use a Notebook

Before choosing to use a notebook, evaluate the task complexity using these heuristics.

Use a notebook if you meet at least one of these criteria:

• 📈 Data Insights & Storytelling: Use a notebook for any request to "give insights", "find trends", "explore data", or "analyze data". These tasks benefit from using visualizations to present the data.
• 📊 Visualizations are requested: The user explicitly asks for charts or plots.
• 🔄 Stateful / Iterative Exploration: You need to run a query, inspect results, and decide the next query based on those results while keeping state in memory.

Do NOT use a notebook ONLY if:

• 📝 Simple Fact/Status: The request only requires a single number (e.g., "how many rows") or a status check (e.g., "when was this table updated").
• 🏃‍♂️ Schema Preview: The request is only about the schema or field types.

Golden Rule of Data Storytelling: If any analytical insight, trend, or comparison is involved, favor a notebook and a visualization. A notebook is the "standard" environment for our developer workflow; do not avoid it because of "overhead".

Notebook Best Practices

[!IMPORTANT]

Agent execution rules: Your behavior MUST depend on whether the notebook_execute_cell tool is available in your current context: * If notebook execute_cell tool is available: You MUST follow the incremental GENERATE CELL -> EXECUTE CELL -> VALIDATE flow. * If notebook execute_cell tool is NOT available: You MUST generate the complete notebook and request user execution.

1. CONDITIONAL EXECUTION FLOW:
   • If notebook execute_cell tool is available: Follow the STEP BY STEP GENERATE CELL -> EXECUTE CELL -> VALIDATE OUTPUT flow. Generate ONE cell, execute it, then verify the output. If the output is data (e.g. a dataframe), you MUST inspect it to confirm the logic is correct before generating the next step. Batch generation of an entire notebook is strictly prohibited because error propagation in notebooks is expensive to fix.
   • If notebook execute_cell tool is NOT available:
     • Create the whole notebook at once.
     • Tell the user to run the notebook.
     • Tell the user to let you know once the notebook run is completed so you can check the outputs to verify it's correct and fix any errors.
2. IDENTIFY DATA EARLY: Use @skill:discovering-gcp-data-assets or BigQuery list tools to find the correct project.dataset.table before writing ANY code. If the table ID is missing, ask the user.
3. CLEAN FINAL STATE: The final notebook MUST NOT have failed cells. If a cell fails, you MUST fix it. If you tried several versions, delete the failed attempts before you present the notebook to the user.
4. LOGICAL CHUNK FIDELITY: Keep cells small. One logical transformation or visualization per cell. Group related cells into logical units (e.g., a BigQuery %%bqsql magic cell followed immediately by a Python visualization cell for those results). Use descriptive markdown cells to separate and document different logical sections.
5. GENERATE VISUALIZATIONS: Always accompany data insights with visualizations; charts are often more effective than raw numbers for communicating trends and comparisons.