Overview
A tutor protocol, not a textbook. It measures what the learner already knows, explains each concept through the learner's own schema, objects, and instance where they exist, sets a hands-on exercise the learner solves themselves, and records progress so a later session resumes instead of restarting. Exercises are verified solvable before they are shown.
When to Use
- "Teach me how relationships work" or any concept question asked to learn rather than to delegate.
- "Why does my instance behave this way?" when the goal is understanding.
- "What's the NetBox/Nautobot equivalent of X in Infrahub?" taught as a
translation (see
rules/grounding-competitor-mapping.md). - "Where were we?" to resume from
.infrahub-learning/progress.md.
Environment Detection
Detect once per session, in this order, and prefer the richest source:
- Repo files in the cwd (schema YAML, object files,
.infrahub.yml): teach through the learner's own artifacts. - A reachable Infrahub instance (MCP server or
infrahubctl): read-only queries illustrate concepts with real data. - Neither: use the generic examples in
references/concept-map.md.
Before writing the first Explain section, read rules/grounding-own-artifacts.md — a generic example when the learner has their own file is a violation, not a fallback.
Instance safety has three tiers; the full ladder is in
rules/safety-instance-writes.md.
Read it before any command that could write, which includes the steps
you tell the learner to run. The short form: read-only by default,
author in local files, and write to the instance only after explicit
consent, only in a learning-* branch, never merged, always deleted.
Workflow
- On first contact, offer to create the learning workspace and read
references/lesson-protocol.mdfor the exact file layout and lesson shape. On resume, read.infrahub-learning/progress.mdfirst. - Pick the concept with
references/concept-map.md: it orders concepts by prerequisite and carries per-concept probe questions, exercise specs, verification methods, and doc anchors. A topic with no row is taught off-map through the shared docs fallback (rules/grounding-off-map-lookup.md). - Before writing any lesson file, read rules/protocol-structured-lessons.md — the Probe/Explain/Exercise/Check shape and its order are fixed.
- Open with Probe, never with the explanation. Read rules/protocol-probe-first.md for how many questions and what they have to establish.
- Write Explain against the learner's own artifacts, and cite the docs page for every behavior claim: rules/grounding-cite-docs.md. For a "what's the NetBox/Nautobot equivalent" lesson, the credibility gate is in rules/grounding-competitor-mapping.md.
- Before presenting the exercise, build and verify the reference
solution per
references/exercise-verification.mdand rules/exercise-verify-solution.md — an exercise you have not solved yourself cannot ship. Assign the work; do not do it: rules/exercise-learner-authors.md. - When the learner struggles, follow the hint ladder in
rules/exercise-hint-ladder.md
before revealing anything, and log each rung to
.infrahub-learning/hints/<concept>.mdas you give it. - Record progress at the end of every lesson, before you reply: rules/protocol-record-progress.md.
- Close each concept by naming the sibling skill that does this work on real projects: rules/handoff-graduation.md.
Rule Categories
| Priority | Category | Prefix | Description |
|---|---|---|---|
| CRITICAL | Protocol | protocol- |
Probe before teaching, the fixed lesson shape, progress recording |
| CRITICAL | Safety | safety- |
Instance writes: opt-in, learning-* branch only, cleanup, never the default branch |
| HIGH | Exercise | exercise- |
Verified reference solutions, learner-authored artifacts, the hint ladder |
| HIGH | Grounding | grounding- |
Teach through the learner's own artifacts, cite docs for behavior claims, off-map lookup, sourced comparisons |
| MEDIUM | Handoff | handoff- |
Graduation pointers to the sibling skills |
Full scope per prefix is in rules/_sections.md. Read the rules for the
lesson phase you are in; they are short and binding.
Supporting References
references/lesson-protocol.md: the workspace contract and lesson shape. This file is the single home for those values.references/concept-map.md: the curriculum.references/exercise-verification.md: how to prove an exercise is solvable before showing it.../infrahub-common/: shared GraphQL syntax and.infrahub.ymlformat.