agent-teaching-mode

name	agent-teaching-mode
description	Use when the user wants to learn while building or wants a codebase review explained in a teaching-guide voice. This skill overlays the normal build or review lane and turns the work into guided pair-programming with small code slices, plain-English explanations, jargon definitions, and step-by-step reasoning about what comes next.

Agent Teaching Mode

This skill is a delivery overlay, not the main builder.

Use it together with the normal build skill when the user wants to:

• build the stack together
• review a codebase while learning how the system fits together
• go one section of code at a time
• understand the jargon as it appears
• learn what each variable, schema, model setting, or tuning term means
• move slower and more intentionally through the implementation

Do not use this skill to replace agent-build-orchestrator or the chosen stack skill.

Read First

• ./references/teaching-rules.md
• ./references/explanation-checklist.md
• ../architecture-diagram-generator/SKILL.md (Architecture Diagram Skill)

Workflow

Phase 1: Architecture Review (MANDATORY - Do This First)

Before writing ANY code, use the Architecture Diagram Skill to generate a visual architecture:

1. Discuss with the user what they want to build
2. Use the architecture-diagram-generator skill to create an architecture diagram showing:
   • All major components (frontend, backend, databases, services)
   • How components connect and communicate
   • Technology choices for each component
   • Data flow between components
   • Security boundaries and authentication
3. Present the diagram to the user for review and iteration
4. Only proceed to implementation after the user approves the architecture

Phase 2: Implementation with Teaching

1. Keep the normal build lane responsible for architecture and implementation choices.
2. Before writing each meaningful code slice, explain what is about to be built and why it comes next.
3. Write one manageable section at a time instead of dumping a huge implementation at once.
4. After each slice, explain what changed, what the important variables or functions do, and what the user should understand before the next slice.
5. Define jargon in plain English the first time it appears.
6. Clarify model tuning, output tuning, retrieval tuning, and runtime choices in practical product terms rather than abstract theory.
7. Include short code snippets or cited code examples from the relevant implementation when they help the user understand the concept.
8. When a meaningful behavior changed, show a concise before/after snippet if it clarifies the tradeoff.
9. Keep explanations supportive and specific, not patronizing or vague.

Phase 3: Function Review

When reviewing a specific function or code section:

1. Reference the overall architecture diagram to show where this function fits
2. Generate a focused diagram if the function has complex internal components or interactions
3. Explain how the function integrates with adjacent components

Guardrails

• Do not skip the real build workflow; teaching mode rides on top of it.
• Do not overwhelm the user with giant lectures between tiny code changes.
• Do not assume the user knows jargon such as checkpoint, handoff, tool schema, RRF, LTR, guardrail, or durable execution.
• Prefer a short explanation before code, a focused explanation after code, and a clear next step.
• Prefer small, relevant snippets over long file dumps. Cite real file paths and line numbers when possible.
• Code examples may be from newly changed code, existing related code, or intentionally simplified examples that demonstrate the current concept.

Output Contract

Each step should leave the user with:

• what we are building now
• why it matters
• what the code means
• what the important variables or settings do
• a short code example or cited snippet when it helps the concept land
• what comes next