Turn project code into annotated learning lessons

Why use this

1. A developer learning from their own project may recognize familiar code without understanding why its abstractions or dependencies work. A lesson that assumes too much can reinforce confusion, while one that silently edits the project changes the thing being studied.

2. A source-linked lesson plan could connect explanations, vocabulary and questions to a fixed code snapshot. The learner could reveal prerequisite gaps through answers without having progress inferred solely from reading or lesson completion.

Why an agent / simpler alternative

Useful judgment

Choose relevant code examples and adapt explanations to demonstrated prerequisite gaps.

Simpler alternative

Read a maintained tutorial or pair with a developer when the topic is standard.

Unsuitable when

The project cannot be shared safely or the explanation requires unsupported runtime assumptions.

Proposed inputs

1. Name

   Project excerpt

   Owner

   Developer

   Minimum scope

   Relevant files and dependency/version context without secrets

   Quality check

   Confirm the snapshot and exclude unrelated proprietary material.

2. Name

   Learning state

   Owner

   Learner

   Minimum scope

   Stated goals, prior answers and known vocabulary

   Quality check

   Distinguish self-reported familiarity from demonstrated understanding.

Access and setup — proposed or unknown

Proposed minimum

1. Read-only code and learner notes; separate private lesson files.

Compatibility unknowns

1. Unknown: exact runtime, repository access and progress-record tooling.

External actions requiring approval

1. Changing project code, sharing proprietary material or writing shared learner records.

Expected deliverable and review checks

Proposed artifact

Annotated lesson draft with pre/post questions, vocabulary and prerequisite-review prompts.

Critical checks

1. Explanations point to the actual supplied code version.

2. Progress claims depend on reviewed responses rather than automatic completion labels.

Missing output evidence

No new workflow run or output inspection is performed for this editorial layer. The linked implementation evidence retains the original source-specific outcome and artifact limits.

Failure signals and proposed responses

1. Signal

   The lesson explains behavior from an older code revision.

   Why it matters

   The learner may form an incorrect model of the current project.

   Proposed response

   Align examples with the supplied snapshot and flag changed behavior.

2. Signal

   A wrong answer is treated as mastery because the lesson finished.

   Why it matters

   Progress tracking could hide the prerequisite gap.

   Proposed response

   Record the specific misunderstanding and propose a smaller follow-up exercise.

Effort and cost — unknown

Setup work

1. Select code scope and identify learning objectives.

Ongoing review

1. Review answers and update lessons when code changes.

Unknowns

1. Unknown: explanation accuracy, study effort and actual comprehension gains.

First check — proposed, unexecuted

Status

proposed_unexecuted

Synthetic fixture

An invented lesson references a renamed function, while a sample answer confuses input validation with error handling.

Acceptance checks

1. The stale reference is flagged.

2. The misunderstanding becomes a prerequisite prompt, not a mastery badge.

Stop conditions

1. Secret exposure, code mutation or an unsupported learning claim is required.

Limits

1. Editorial learning aid; an available lesson artifact does not establish improved understanding.