lesson-iteration

Files (3)

• LESSON-TEMPLATE.md
• SKILL.md
• openai.yaml · agents/

SKILL.md (first lines)

# Lesson iteration

## Contract and authorities
Prevents: unsolicited execution, language drift, imitation without structure, and invented repository assumptions.

Run only when explicitly invoked. Treat the argument as the lesson topic. Resolve ordinary ambiguity by choosing a useful scope and recording assumptions; do not stall for clarification.

This operating manual is English. Everything the learner receives must be Russian: planning summaries, lesson prose, task briefs, reviews, delivery notes, authored code comments, and example explanations. Keep industry terms such as mutex, goroutine, and deadlock in their native form; explain them in Russian rather than inventing calques. Preserve language syntax, identifiers, commands, URLs, and official names.

Read `LESSON-TEMPLATE.md` beside this file before planning. It is the structural source of truth. If repository-root `fable-output.md` exists, read it for depth, register, and explanatory technique—not for a mandatory Go-specific curriculum or fixed part count.

Inspect:
- `portfolio/projects/practice-map/lessons/`;
- `portfolio/projects/practice-map/web/curriculum.ts`, its actual types, and neighboring cards;
- the deep reader's rendering behavior;
- applicable repository instructions, package scripts, lockfiles, and test conventions.

Use the supplied Practice Map schema as the expected contract; verify it against the checkout. Do not guess missing fields, commands, or renderer capabilities. If a genuine incompatibility prevents integration, finish the authoring work where possible and report the blocker without claiming completion.

The lesson document is the source of truth. Never improve only the migrated copy.

## Ordered gates
Prevents: prose-first execution, skipped reviews, and premature “done.”

Execute these gates in order:

1. Intake and planning.
2. Complete draft.
3. Depth audit and repair.
4. Consistency audit and repair.
5. Practice Map integration and validation.
6. Explicit delivery.

Maintain an inspectable work record in Russian: the plan, coverage ledger, audit findings, and validation results. Use the workspace's established task-log/scratch convention, or a clearly designated non-published working artifact. Record decisions and evidence, not private reasoning. Do not put these artifacts into the published essay or curriculum.

Do not seek approval between gates. A failed gate requires repair, not a disclaimer followed by publication. If work is interrupted, preserve the draft and the next unresolved gate; label the result incomplete.

## 1. Intake and planning
Prevents: shallow scope, missing dependencies, arbitrary examples, and programming-only adaptations.

Before writing lesson prose, record:

- Topic boundaries, assumed reader knowledge, intended mastery, relevant versions/environment, and assumptions.
- The exact ordered list of `##` headings, with final consecutive part numbers and planned `### N.M.` subsections.
- A coverage ledger with one row per progressive part:
  `part | why-questions | prerequisite | mechanism and internal representation | rule → consequence | demonstration | bad/good trap | mental model and its limit | exercise`.
- Candidate misconceptions, numbered pivotal traps, diagrams, convention tables, and canonical maxims.
- A resource/evidence shortlist and an eight-week progression mapped to the planned parts.
- The intended area/card integration target, identified from actual repository data.

Each progressive part needs at least one substantial mechanism explanation, one causal “Почему это важно” passage, and one diagnosed bad/good comparison. Plan at least three distinct reusable mental models across the lesson; introduce them where useful and consolidate them at the end.

For a narrow topic, teach its prerequisites only as far as its mechanisms require; do not silently expand “PostgreSQL indexes” into all of PostgreSQL.

Adapt the curriculum, not the skeleton:
- Installation/first run becomes first observation, setup, or reproducible experiment when appropriate.
- Syntax becomes notation, operations, primitives, or conventions.
- “From source to process” becomes the subject's physical or operational substrate.
- The advanced “main force” becomes the field's hardest central capability.
- Organization/testing/toolbox becomes composition, verification, diagnosis, and working instruments.

For networking, databases, design, or non-programming subjects, use inspectable artifacts, protocols, measurements, or before/after decisions where source code would be artificial. Keep the same explanatory burden.

## 2. Complete draft
Prevents: outlines presented as lessons, API catalogues, invented authority, and unsafe demonstrations.

Draft the entire essay using `LESSON-TEMPLATE.md`. Keep the working draft outside the numbered final lesson path until both authoring audits pass.

Write a comprehensive essay: target 6,000–12,000 Russian prose words, with a floor of 5,000 excluding code, URLs, and template instructions. Length is a backstop, not proof of depth. Every planned part must be substantive; never meet the floor by padding some parts while reducing others to summaries.

For every taught mechanism, expose its components/state, the sequence of operations, the governing invariant or constraint, and observable consequences. Explain why a rule exists before asking the reader to memorize it.

Examples must be real, idiomatic, and reproducible:
- State environment, prerequisites, commands, and expected observations.
- Give complete runnable code or an explicitly identified fragment attached to a complete setup.
- Use Russian comments and authored diagnostic/output text where controllable.
- For nondeterministic behavior, describe possible outcomes or invariants; do not invent a guaranteed output.
- Isolate destructive, hanging, or failure demonstrations; include cleanup, limits, or timeouts.
- Outside programming, supply an equally reproducible procedure and inspectable result.

Verify historical claims, version-dependent behavior, quotations, and concrete numbers against authoritative sources where tools permit. State architecture, units, version, and conditions where they affect a number. Mark estimates as estimates; do not fabricate benchmark results. If verification is unavailable, narrow the claim or flag the uncertainty in the work record and lesson where relevant.

Practitioner callouts should express usable judgment. Do not invent quotations or attribute your own maxim to a famous person.

## 3. Depth audit and repair
Prevents: fluent but shallow prose, unexplained rules, decorative traps, and slogan-only mental models.

Audit the actual draft against every coverage-ledger row. Record a location and verdict for each item:

- **Mechanism:** Can the reader trace an input through internal components/state to an outcome? Are implementation/version-dependent details distinguished from guarantees?
- **Causality:** Does every prescriptive rule explain its reason, consequence, and boundary of applicability?
- **Demonstration:** Does the example reveal the mechanism, rather than merely name an API?
- **Trap:** Are there both bad and good variants, the failing assumption, the resulting symptom, and an explanation of why the repair works? For non-code subjects, use equivalent contrasting artifacts or procedures.
- **Mental model:** Does it help predict a new case, and is its limit stated? Are at least three distinct models actually developed?
- **Transfer:** Do exercises require explanation, prediction, or diagnosis as well as execution?
- **Substance:** Is any planned part a stub, a list of tips, or repeated material masquerading as depth?

Repair every failure in the source draft. Re-run failed checks and affected ledger rows. Do not use a high word count to waive a depth failure.

## 4. Consistency audit and repair
Prevents: invocation-to-invocation drift, tutorial-speak, missing closing material, and unresolved scaffolding.

Review the draft skeptically against the complete template:

- Exact title pattern; complete Part 0; progressive parts in dependency order.
- Consecutive part/subsection numbers; required summary, mental-model, exercise, resource, and closing sections.
- Horizontal rule after every part.
- All four exercise levels and “Вызовы на понимание”; each exercise has a bold title, a concise brief, and a named professional requirement.
- All five resource categories; usable URLs for canonical documentation.
- Exactly eight weeks, each mapped to existing parts and an observable result.
- Russian direct address to someone who already writes code; native industry terms explained in context.
- Why/pain before how; concrete bounded claims; bold key terms; tables for conventions.
- No childish metaphors, academic padding, fake quotations, untranslated authored comments, placeholders, empty headings, or “expand later.”
- Word floor and substantive coverage of every planned part.

Record pass/fail evidence and repair failures. If consistency repair changes explanations or examples, repeat the affected depth checks before proceeding.

## 5. Practice Map integration and validation
Prevents: source/curriculum divergence, overwritten lessons, lossy migration, invalid TypeScript, and unsupported success claims.

From vasyapym/vasyapym.github.io, MIT.

More from vasyapym/vasyapym.github.io