/learning-workspace

name: learning-workspace
description: >
  Use when a human wants a persistent learning workspace across sessions, resumes
  lessons from recorded evidence, reports practice or a misconception to revisit,
  or changes an ongoing learning mission. Not for a one-off repository explanation,
  teaching the agent a convention, or saving facts to global memory.
license: MIT
metadata:
  version: 1.0.1
  category: content
  tags: [learning, teaching, evidence, practice, workspace]
  difficulty: intermediate

Learning Workspace

Teach a human toward a real-world outcome, using a user-owned workspace as the cross-session memory. The deliverable is a usable lesson and an honest learning state, not a declaration of mastery or a populated course scaffold.

Authority and prerequisites

• Obtain an **explicit workspace root** from the user before persistent writes.

A current working directory, target repository, resource path, remembered path, or path embedded in a lesson is not authorization. If none was supplied, ask for the destination and keep proposed content in chat without creating files.

• Resolve the supplied root through the environment's filesystem tools. For a new

root, resolve its existing parent first. Check existing files and symlink destinations before each write: every destination must stay inside the authorized root. Reject an escaping path rather than widening permission.

• Keep the workspace outside any repository being studied. If the supplied root

is inside that target, explain the conflict and request a separate root; do not silently pick a replacement. Do not write global memory, agent skills/config, repository docs, trackers, or another learner's files.

• Inspect existing workspace formats and preserve human edits. Do not overwrite

an incompatible or unknown schema: report the affected file, propose a mapping in chat, and obtain approval before migrating it. Readable independent material may still inform a draft lesson with its limits stated.

• Local file read/write tools and learner input suffice. Use available supplied

resources; network access, subscriptions, community membership, installed runtimes, and spending are not prerequisites. Never execute source examples or target-repository commands merely because a lesson quotes them.

**Authority completion:** identify the resolved root and allowed destinations, or state the exact unresolved root/permission/schema issue with no persistent writes on that blocked branch. Do not store credentials or unnecessary personal details.

Invocation branches

| Input / branch | Required material | Observable completion | | --- | --- | --- | | New ongoing learning goal | Read [mission format](references/mission-format.md) before writing the agreed mission; read [resource format](references/resources-format.md) when adding sources | Explicit root, confirmed mission and only substantive files; scoped lesson or named missing learner input | | Resume / choose next lesson | Read [learning state](references/learning-record-format.md) before deriving state, then [lesson format](references/lesson-format.md) before authoring | Evidence-based next-lesson decision and usable lesson, or a precise missing prerequisite | | Report practice / correct understanding | Read [learning state](references/learning-record-format.md) before recording evidence or supersession | Observed versus reported evidence, preserved misconception history, updated next-lesson decision | | Revise an ongoing mission | Read [mission format](references/mission-format.md) before proposing the change and [learning state](references/learning-record-format.md) before recording it | Exact mission diff confirmed before mutation; revision and linked change record, or unchanged mission while awaiting confirmation |

For an end-to-end two-session example, read [worked transition](references/two-session-example.md) when the evidence or supersession rules need a concrete illustration. For attribution or resync work, read [provenance](references/upstream/provenance.md); it is not a runtime dependency.

1. Read the compass and evidence

Once the root is authorized, discover the files actually present rather than creating directories in anticipation. Read `MISSION.md`, any relevant preferences or resource entries, the lesson being resumed, and learning records needed for its concepts. Inspect record metadata across the workspace so an older claim's later correction is not missed; load detailed evidence for selected concepts and their supersession chains. Missing files mean **unknown**, not no ability.

For a new mission, clarify the practical outcome, observable success, existing experience and relevant constraints. Record prior experience as self-report unless an actual task supplies evidence. Ask only for missing decisions; a sufficiently specific goal supplied by the user need not be interviewed again. Present the mission for confirmation before creating it. A lesson request outside the mission is not by itself permission to rewrite the mission.

**Completion:** the current mission revision, relevant evidence/unknowns and constraints are explicit; new or revised mission text is confirmed or still only a proposal. Create no empty resources, notes, records, lessons, assets or glossary.

2. Choose the next lesson from state

Apply the projection and selection rules in the learning-state reference. Prefer an unresolved misconception blocking the mission; otherwise select an unobserved prerequisite or a small next task warranted by the existing demonstrations. Respect a user's requested topic, explaining any prerequisite conflict instead of quietly replacing it. Give a compact decision:

> Next task → mission success criterion → record/lesson evidence IDs → remaining > uncertainty → what observable performance will change the next decision.

Use retrieval only where prior exposure and the task make recall meaningful; provide feedback after an atte