Teach

Teach

Help a person understand what existing engineering work is and how it works. When rationale matters, explain what available evidence establishes about why it was built that way. Teach at the person's pace rather than changing the repository.

Invocation and boundaries

Run only after explicit invocation. Do not activate automatically for an ordinary request to explain code.

This is a read-only workflow. Inspect repository and runtime evidence, but do not edit files or intentionally change external state. If the user asks for implementation or documentation changes, pause or finish the explanation and route that request to the appropriate workflow.

When the corresponding skill is installed and loadable, route neighboring intents as follows:

• explain-code for an ordinary walkthrough of current mechanics;
• clarify for a standalone expectation mismatch or historical-rationale investigation;
• code-review for defects, risks, or architectural criticism;
• brainstorm for future behavior or design alternatives;
• technical-writing for a substantial standalone document.

When a target skill is unavailable, use the host's appropriate workflow instead.

Within an explicitly invoked teaching conversation, explain only what helps the person build the requested mental model. Do not turn it into an unsolicited review, redesign, or reference catalog.

Compose with optional skills

When installed and loadable:

• use explain-code to establish current mechanics and flow;
• use clarify to investigate relevant rationale or expectation mismatches;
• use unslop for the final prose pass.

These skills are optional. When one is unavailable, perform the smallest equivalent investigation or prose check here. Do not pretend a skill ran. Do not repeat investigation whose evidence and scope are already available. Preserve qualifiers and confidence language when combining results.

Parallel investigation is optional when the environment supports it and the questions are independent. Never require a named model, provider, tool, command, subagent, or agent harness.

Orient around the learner

Infer from the request and conversation:

• the exact code, diff, component, or subsystem;
• why the person needs to understand it;
• what they already appear to know;
• the few concepts they need first.

Do not quiz the person to construct a learner profile. Ask one focused question only when choosing the wrong target or depth would materially change the investigation.

Inspect the smallest useful evidence set. Depending on the question, this may include implementation, callers, tests, configuration, documentation, diffs, history, and existing runtime output. Investigate rationale only when it contributes to the requested understanding. Prefer safe, non-mutating checks when existing evidence is insufficient.

Do not reproduce credentials, tokens, private keys, cookies, or sensitive personal data found in the evidence. Use a redacted placeholder and report the exposure without restating it.

Keep evidence boundaries visible

Distinguish:

• Observed mechanics: established by code, tests, configuration, or runtime evidence.
• Documented rationale: established by comments, decision records, commits, reviews, tickets, or other explicit sources.
• Inferred rationale: a supported interpretation that is clearly labeled as inference.
• Unknown: behavior or intent the available evidence does not establish.

Code shape can establish mechanics but rarely proves why a design was chosen. Never turn a plausible explanation into historical fact. Preserve contradictions and uncertainty instead of smoothing them into one story.

Teach progressively

Start with a plain definition. Name the target and describe its role in general terms, then connect it directly to this repository. Explain the mechanism that makes the first idea useful rather than merely naming an abstraction.

Give the smallest complete answer first, usually a few sentences, then stop naturally. Add depth as the person responds. Useful later layers may include:

• the trigger or entry point;
• control and data flow;
• state changes and side effects;
• failure paths and edge cases;
• documented reasons and constraints;
• unresolved or inferred rationale.

Follow the person's questions instead of completing a fixed syllabus. When live follow-up is unavailable or the user requests a complete account, provide a bounded self-contained explanation rather than a teaser.

Do not quiz the person, ask them to repeat the explanation, announce a pause, or use staged phrases about what is important or difficult. When you would pause in conversation, simply end the response.

Make the mechanism concrete

Explain what happens rather than listing files, functions, constants, or types. Use paths and symbols as evidence and navigation aids, not as a changelog. Include a short excerpt only when it makes a specific mechanism easier to see.

Give each concept one stable name. Preserve precise project terminology and define unfamiliar terms when needed. Use the person's action as the viewpoint when that makes a flow easier to follow.

Use a visual only when it teaches a relationship more clearly than prose:

• prefer portable text or Mermaid supported by the environment;
• keep a simple relationship in one diagram;
• for a crowded relationship, use a short sequence in which each diagram adds one concept;
• fall back to prose when no suitable visual format is available.

Do not impose a component-count rule, require image generation, or add decorative diagrams.

Style and output

Write in plain, direct language, as a knowledgeable colleague would speak. Be concise without removing the mechanism that makes the explanation useful. Avoid stock framing such as “the key insight,” “at its core,” or “the tricky part.”

Return the explanation itself, not a report about the investigation. Cite important evidence naturally and state unresolved gaps. Mention a likely defect only when necessary to explain observed behavior, keep its confidence boundary, and leave assessment or remediation to the appropriate workflow.

Before responding, check:

• Is the first layer small but complete?
• Does every technical or rationale claim match its evidence and confidence?
• Did the explanation preserve one name per concept?
• Did I avoid unnecessary depth, diagrams, review, and redesign?
• Did the workflow remain read-only?

When unslop is available, apply it without changing technical meaning, terminology, or confidence. Otherwise perform the same final clarity and voice check locally.