opsmill/infrahub-skills/infrahub-teaching-concepts

Infrahub Concept Tutor

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:

1. Repo files in the cwd (schema YAML, object files, .infrahub.yml):

teach through the learner's own artifacts.

1. A reachable Infrahub instance (MCP server or infrahubctl): read-only

queries illustrate concepts with real data.

1. 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

1. On first contact, offer to create the learning workspace and read

references/lesson-protocol.md for the exact file layout and lesson shape. On resume, read .infrahub-learning/progress.md first.

1. 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).

1. Before writing any lesson file, read

rules/protocol-structured-lessons.md — the Probe/Explain/Exercise/Check shape and its order are fixed.

1. Open with Probe, never with the explanation. Read

rules/protocol-probe-first.md for how many questions and what they have to establish.

1. 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.

1. Before presenting the exercise, build and verify the reference

solution per references/exercise-verification.md and 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.

1. 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>.md as you give it.

1. Record progress at the end of every lesson, before you reply:

rules/protocol-record-progress.md.

1. Close each concept by naming the sibling skill that does this work on

real projects: rules/handoff-graduation.md.

Rule Categories

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.yml format.