# Teach Workflow

> Run guided teach-mode scans, dives, and local insight logging. Use when this capability is needed.

- Skill: `tomevault-io/teach-workflow` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/teach-workflow`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/teach-workflow/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/teach-workflow

---


## When to use
- Onboard a developer to this repository.
- Build a subsystem mental model before making changes.
- Create a guided learning path with checkpoints.

## Core commands
- `/teach-full` for broad architecture scan + pause checkpoint.
- `/teach-dive <subsystem>` for targeted deep dives.
- `/teach-ask <question>` for direct answer-only mentoring responses.

## Standard flow
1. Ensure context is loaded from:
   - `.aoc/context.md`
   - `aoc-mem read`
   - `aoc-stm resume` (fallback `aoc-stm read-current` when no archive exists)
   - `aoc-task list`
   - `.taskmaster/docs/prd.txt` (fallback `.taskmaster/docs/prd.md`)
2. For full scan, explore subsystem tracks in parallel.
3. Synthesize a teaching report with:
   - system mental model
   - subsystem map
   - key files per subsystem
   - current status (done vs fragile/missing)
   - top risks
4. End with numbered checkpoint options and wait for user choice.
5. For deep dive, return:
   - concept in plain English
   - repo implementation with file refs
   - tradeoffs and alternatives
   - debugging checklist
   - 2-3 hands-on exercises

## Insight logging (local-only)
Maintain a local insight workspace in `.aoc/insight/`:
- `current.md`: active teaching state and pending choices
- `insights.md`: append-only insight log
- `index.md`: compact history index
- `sessions/*.md`: timestamped full scan and deep-dive snapshots

Do not change `.gitignore` for this workspace; keep it local-only.

## Insight entry format
- timestamp (UTC)
- subsystem
- insight
- evidence (file refs)
- confidence (`high|medium|low`)
- suggested action
- promote to memory (`yes|no`)

## Guardrails
- Default to read-only exploration.
- Do not edit code unless explicitly requested.
- Never edit `.aoc/memory.md` directly.
- Never edit `.taskmaster/tasks/tasks.json` directly.
- Promote durable decisions with `aoc-mem add` only when asked.

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/basicalex) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-16 -->