@erclx/aitk 0.99.1 → 0.101.0

package/standards/index.md

@@ -26,5 +26,6 @@ Reference docs for consistent authoring across the toolkit and target projects.
 - [Slug reference](slug.md): Transform from a git branch name to a slug, and the three responses to an empty result
 - [Standard reference](standard.md): Shape and content rules for authoring a standard
 - [Tasks reference](tasks.md): Folder layout, filename convention, readiness groups, and content rules for .claude/tasks/
+- [Teach reference](teach.md): Workspace layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats for a learning workspace
 - [Versioning reference](versioning.md): Phase label vs semver discipline across tasks, PRs, reviews, issues, commits, and tags
 - [Wireframe reference](wireframes.md): Shape and content rules for .claude/wireframes/<surface>.md files

package/standards/teach.md

@@ -0,0 +1,155 @@
+---
+title: Teach reference
+description: Workspace layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats for a learning workspace
+---
+
+# Teach reference
+
+Applies to a learning workspace at `.claude/teach/<nn>-<topic>/`. One workspace holds one subject studied across sessions, and it carries both halves of what studying produces: the durable reference material a reader consults later, and the disposable lessons a learner works through once.
+
+The folder is gitignored. Its markdown half is written in a format the authoring gates read, so a page promoted out of it later needs no conversion.
+
+## Scope
+
+Governs a learning workspace under `.claude/teach/<nn>-<topic>/`: folder layout, ordinal naming, frontmatter, and the mission, learning-record, and glossary formats.
+
+Does not govern:
+
+- What a lesson teaches, how it sequences difficulty, and what makes one worth returning to, which belong to the surface driving the workspace
+- Where a durable page goes once it leaves the workspace, which belongs to the routing test the destination surface states
+- One question measured in depth before anyone can plan against it: `groundwork.md`
+- A dump of many findings filed by domain, each carrying its own verdict: `intake.md`
+- Voice and word choice: `prose.md`
+- Headings, punctuation, and file references: `markdown.md`
+- When a workspace opens at all, and the procedure that runs one, which belong to the surface driving it
+
+## What a working workspace looks like
+
+A workspace works when a session returning after weeks can resume from the folder alone:
+
+- Which subject is being learned, and what will the learner be able to do when the mission is finished?
+- Which sources stand behind the material, and which were found and never opened?
+- What has the learner already been through, and what did they get wrong?
+- Which pages here are durable reference material, and which are disposable?
+
+A workspace failing these is non-conforming even when it satisfies every shape rule below.
+
+## Folder name
+
+- Name the folder `<nn>-<topic>`, a two-digit zero-padded ordinal followed by a kebab-case topic slug.
+- Take the ordinal from the highest one already present, incremented. A listing then sorts by when each workspace opened rather than alphabetically.
+- Use two digits on the folder and four inside it. A person opens far fewer workspaces than one workspace holds lessons.
+- Never renumber an existing folder. The ordinal is the order it opened, and a later reader cites it by that name.
+
+## Layout
+
+| Path                  | Holds                                                  | Required |
+| --------------------- | ------------------------------------------------------ | -------- |
+| `MISSION.md`          | The subject, the learner's starting point, and success | Always   |
+| `RESOURCES.md`        | Sources read and sources found but not opened          | Always   |
+| `GLOSSARY.md`         | Terms the subject defines, one entry each              | Always   |
+| `NOTES.md`            | Session scratch that belongs to no other file          | Optional |
+| `reference/<slug>.md` | Durable reference pages, the promotable half           | Optional |
+| `learning-records/`   | Numbered records of what the learner was taken through | Optional |
+| `lessons/`            | Numbered lessons, generated and disposable             | Optional |
+| `assets/`             | Files several lessons share, including the stylesheet  | Optional |
+
+Only the markdown half answers to a conformance check: `MISSION.md`, `RESOURCES.md`, `GLOSSARY.md`, `NOTES.md`, `reference/`, and `learning-records/`. A lesson is generated markup that nothing downstream cites, so this standard fixes its filename and its location and says nothing about what it contains.
+
+## Frontmatter
+
+Every markdown file carries `title` and `description`. `MISSION.md` carries one field the others do not.
+
+- `title` (required): what the file covers, in sentence case
+- `description` (required): one line naming what a reader gets from it
+- `date` (required, `MISSION.md` only): the day the workspace opened, as `YYYY-MM-DD`
+
+Date the workspace once rather than every file. A per-file date leaves every other file stale the first time one is edited, and the opening date never rots.
+
+## File naming
+
+- Number a lesson and a learning record `0001` upward, as `<nnnn>-<slug>.html` and `<nnnn>-<slug>.md`. The number is read order and never changes.
+- Name a reference page for its subject alone, with no number. A reference page is looked up rather than worked through, so an ordinal on one implies an order no reader follows.
+- Keep one shared stylesheet under `assets/` and link it from every lesson. A lesson restating its own styles makes a workspace read as a pile of one-offs rather than as one course.
+
+## MISSION.md
+
+Fixes what the workspace is for. Everything else in the folder answers to it.
+
+- A one-line statement of the subject
+- A `## Starting point` section stating what the learner already knows, so difficulty has a floor to sit above
+- A `## Success looks like` section listing specific observable things the learner will be able to do
+- A `## Out of scope` section naming what this workspace deliberately does not cover
+
+Write each success line as something a learner can be asked to do rather than something they will understand. A line nobody can test is a line nothing can report progress against.
+
+## Learning records
+
+One record per session the learner worked through, holding what happened rather than what was taught.
+
+- The lessons covered, by number
+- What the learner retrieved correctly without help
+- What they got wrong, and what the wrong answer was
+- What to revisit, and roughly when
+
+Record the wrong answer rather than the fact of an error. A wrong answer names the misconception, and the count alone names nothing.
+
+## GLOSSARY.md
+
+One entry per term the subject defines, sorted alphabetically.
+
+- Lead each entry with the term as a bolded span, then the definition in one or two sentences
+- Define the term without using it
+- Name the lesson or reference page where the term first appears
+- Keep an entry to the meaning. Worked detail belongs on a reference page.
+
+## RESOURCES.md
+
+Splits what was read from what was found.
+
+- List every source that stands behind the material, each with a link
+- List under a leads heading any source found and not opened, and never cite one
+- Say which claims in the workspace rest on which source
+
+A source found and not read is listed as a lead because a link attached to a page nobody opened is worse than no link. Listing it still pays, since it stops a later session searching for what this one already surfaced.
+
+## Conventions
+
+- Write the markdown half in the format the authoring gates read, so a page promoted later needs no conversion.
+- Keep a reference page free of the learner. A page carrying a second person or a quiz is a lesson wearing the wrong extension, and it cannot be promoted.
+- Revise a file the subject has moved under rather than appending a second version narrating the change.
+
+## Anti-patterns
+
+- **The mission with no test.** Success stated as understanding rather than as a task leaves nothing able to say the mission is finished.
+- **The lesson filed as reference.** A page written to be worked through once sits in `lessons/`, and putting it in `reference/` puts disposable output in the half that gets promoted.
+- **The record that counts errors.** A tally of how many were missed carries none of the misconception, which is the only part a later session can act on.
+- **The date left in the body.** A frontmatter field and a sentence both claiming the opening date resolve to whichever a reader happens to hit, and only one of them is readable by a walker.
+- **The renumbered folder.** Closing a gap in the ordinals moves every name a reader or a record already cited.
+
+## Template
+
+```markdown
+---
+title: <Subject>
+description: <one line naming what a learner gets from this workspace>
+date: <YYYY-MM-DD>
+---
+
+# <Subject>
+
+<One line stating the subject.>
+
+## Starting point
+
+<What the learner already knows.>
+
+## Success looks like
+
+- <a specific thing the learner will be able to do>
+- <a specific thing the learner will be able to do>
+
+## Out of scope
+
+- <what this workspace deliberately does not cover>
+```