Skip to main content

SOP: Tutorial Coach Agent — Memory, Session, and KB Policy

Purpose​

Make the Tutorial Coach Agent reliable and non-confusing by defining:

  • what belongs in prompt context vs session state vs long-term memory
  • where to store progress and evidence
  • how to avoid cross-learner and cross-project contamination

This SOP applies to coaching done in Mattermost with GitHub (KB repo) as system-of-record.

Scope​

In scope​

  • Learner coaching for tutorial projects (ESP-IDF, DWIN, etc.)
  • Logging + tracking within docusaurus-kb
  • Evidence handling + evaluation questions

Out of scope​

  • Storing secrets (API keys, passwords)
  • Public internet publication of learner data

Architecture (state separation)​

The agent must treat “state” as 3 different things:

  1. Short-term context (NOW)
  • What’s needed to answer the current message
  • OK to include temporarily in the prompt
  • Examples: current error log, the learner’s last command output
  1. Session state (THIS PROJECT, THIS LEARNER)
  • Structured progress within a specific tutorial project
  • Stored in repo logs / tracker files
  • Examples: checkpoint status, evidence links, which questions were asked
  1. Long-term memory (PREFERENCES / STABLE FACTS)
  • Only stable preferences or facts that should persist
  • Stored sparingly
  • Examples: learner prefers Bangla explanations; Arif preference: “ask which project if ambiguous”

Hard rule: Do not keep adding old chat history into the prompt. Retrieve only the minimal state needed.

Prereqs​

  • Mattermost channel ready (recommended: #tutorial-coaching)
  • docusaurus-kb repo is accessible and is the system-of-record

Inputs​

  • Learner identity (Mattermost username)
  • Project slug (e.g., esp32-esp-idf-vscode-hello-world)
  • Evidence pack items (repo link, screenshots/logs)

Procedure​

1) Onboard a learner (create tracker)​

Create a tracker file (one per learner per project):

  • sessions/learners/<learner>/<project>/tracker.md

Populate it using docs/templates/LEARNER_TRACKER_TEMPLATE.md.

2) Logging policy (what gets written where)​

A) Mattermost thread​

Use for:

  • conversation
  • quick questions
  • evidence submission

Do NOT rely on it as the only record.

B) GitHub (docusaurus-kb) — system-of-record​

Write/append to:

  • sessions/learners/<learner>/<project>/YYYY-MM-DD.md

Include:

  • current status (state machine)
  • evidence links
  • Q&A asked + pass/fail
  • next actions + deadlines

C) Docusaurus docs pages​

Use for:

  • the tutorial itself
  • SOPs and evaluation packs

Do NOT put learner-specific personal data into public-ish docs pages.

3) Evidence handling policy​

Evidence must be one of:

  • Git repo link (preferred)
  • pasted terminal output (small)
  • screenshot/photo (if allowed)

When evidence is large:

  • store in GitLab/Git or a file store; link to it

4) Questioning / evaluation policy​

  • Ask questions per checkpoint.
  • Do not ask everything at once.
  • If failed:
    • provide one remediation step
    • request new evidence
    • re-ask 1–2 targeted questions

5) Memory writing policy (what we remember long-term)​

Allowed long-term memory items (examples):

  • learner language preference (Bangla/English)
  • learner board type (ESP32 vs ESP32-S3) if stable
  • team-wide conventions (project slug format)

Not allowed in long-term memory:

  • temporary errors
  • transient ports (COM7) unless it’s a fixed lab setup
  • secrets

6) Cross-project isolation rules​

  • Every message must be tagged internally by (learner, project).
  • If ambiguous, ask:
    • “Which tutorial project is this for?”
  • Never use another learner’s logs as context.

Config (repo structure)​

Recommended paths:

  • Tutorials: docs/projects/*.md
  • Eval packs: docs/projects/<tutorial>/eval-pack (slug) or dedicated file
  • Templates: docs/templates/*.md
  • Logs:
    • sessions/tutorial-coach-agent/YYYY-MM-DD.md (ops notes)
    • sessions/learners/<learner>/<project>/... (learner tracking)

Verification​

  • A new learner can be onboarded in < 5 minutes
  • Progress status is always visible in tracker
  • Coach agent can answer:
    • “Where is the evidence for Flash OK?”
    • “Which questions did we ask?”
  • No cross-project confusion occurs (agent asks when ambiguous)

Rollback​

If process becomes noisy/too heavy:

  • disable daily check-ins
  • reduce logs to only milestone updates

Troubleshooting​

  • Agent confused across projects → enforce (learner, project) tagging + ask clarifying question
  • Missing evidence → do not advance state
  • Learner stuck repeatedly → switch to a small, concrete “do this next command” step

References​

Changelog​

  • 2026-02-14: Initial SOP created.