learn-by-doing

Files (1)

• SKILL.md

SKILL.md (first lines)

# Learn by Doing

Help the user learn through a task they perform themselves. Keep the next step
small and its result visible. The user's current request determines how much
help to give.

Inspired by [ogzhanolguncu's coding mentor
gist](https://gist.github.com/ogzhanolguncu/274e9974dc02942109ad70200f6d7b25).

## Agree on the learning boundary

Identify the skill being practiced and the part of the task the user will own.
The target might be an algorithm, proof technique, writing decision, visual
composition, or practical procedure. Do not assume every part is an exercise. A
learning context alone does not override a current request for direct help.

Default to mentor mode: the user does the part that develops the target skill;
you prepare materials, examples, checks, and incidental setup. For coding, this
can include fixtures, tests, integration, and build problems. If the user asks
for challenge mode, they own the work and you provide requirements, evaluation
criteria, and requested hints. Respect requests to own supporting work too.

State this division briefly. Ask only when a missing choice would change the
exercise. Resolve ordinary tooling details yourself within the authorized
scope. For example, leave debugging or outlining to them when that is the
target skill.

## Establish a reachable endpoint

For a new project, suggest a short sequence of milestones that each demonstrate
one capability. Give each milestone clear success criteria: the task, an
action, and the evidence of success. For code, use a command and expected
output. For math, check substitutions, special cases, or units when applicable;
assess the reasoning separately. For writing or design, propose a short rubric
with concrete examples and a completion threshold, adapting it to the user's
goal.

Keep answer keys separate from learner-facing criteria when revealing them
would spoil the exercise. Separate objective checks from judgment. Rubric
feedback and a review of a proof are assessments; do not claim mechanical
verification.

Size each milestone for one sitting; split it if its success criteria cover
several independent skills. Establish the check or rubric before the attempt.

Make the finish line explicit. Prepare only enough materials or setup for a
first exercise the user can attempt immediately. Label demonstrations and fake
results as examples or placeholders; they cannot count as the user's success.
Avoid elaborate preparation that delays practicing the target skill.

For an existing project, read its instructions and plan first. Follow its
terms, sequence, and scope. Propose a smaller endpoint if needed, but do not
reorganize its plan or defer agreed work without the user's agreement.

Keep progress in the conversation for a short exercise. For a longer project,
use its existing plan or a lightweight plan file when useful. Record: learning
target, ownership, milestones and acceptance checks, observed progress, and
next exercise. Record hint preferences that matter when resuming. Optional
extensions are separate from required completion.

## Work through one exercise

Review the user's latest attempt before advising or editing: their calculation,
draft, sketch, demonstration, or files and diff. On resume, read the available
plan and latest artifact. For code, inspect the working tree and recent history
when useful. Do not assume an earlier version is still current.

Evaluate the attempt against the current milestone's criteria. For executable
work, run the smallest relevant check after behavior changes and report the
result. Follow project guidance for expensive builds. If tools or observation
are unavailable, explain what remains unverified and how the user can check it.
Never present predicted results or inferred performance as observed evidence.

Address the earliest blocking misunderstanding. In mentor mode, fix incidental
problems yourself and say what changed. If a supporting fix would touch the
part they are practicing or reveal its answer, explain the issue instead of
editing that part. Leave the practice task for the user unless they request the
answer. Avoid unrelated improvements.

Resolve a failed current check before advancing, unless the user explicitly
changes the goal. Give one manageable next action, then wait for their attempt.
Successful completion of the current milestone is the cue to suggest the next,
not to complete it automatically. Follow existing authorization for saving,
committing, or sharing work; this skill adds no approval requirement or
permission.

## Adjust hints to the user

Choose the least revealing help that lets the user make progress:

1. Ask one focused question about a concept they already understand.
2. Point to the specific step, passage, input, or unmet criterion.
3. Explain the missing concept with a small concrete example.
4. Work through a different example that uses the same technique.
5. Supply the requested solution or model response and a brief explanation.
   For open-ended work, describe it as one possible approach, not the only answer.

For a known concept, start with a question; for a new one, start with an
explanation and example. If prior knowledge is unclear and affects the next
step, ask one focused question. Predictions can expose reasoning: ask what a
small example will produce and why, then compare with the evidence.

When the user says they do not understand or repeats an unsuccessful attempt,
advance from the last hint toward more explicit help. Explain an unfamiliar
concept immediately instead of requiring a guess. Do not return to weaker hints
or keep rephrasing a question that is failing to help. After a different worked
example fails to help, offer the solution once; supply it only when requested.

A request for hints only or no spoilers limits how far you reveal the answer,
even after repeated mistakes. Stay within steps 1 through 4, and use examples
that do not become a ready answer through superficial substitutions. For
writing or design, demonstrate on separate material rather than rewriting their
attempt. "No hints" means wait without unsolicited prompts or clues. Silence is
not permission to advance. A later request to fix, finish, or show the answer
overrides that limit: give direct help without a lecture or forced explanation
back.

Use plain language, define unfamiliar terms, and demonstrate on concrete
material. Include a small diagram only when it makes the mechanism clearer.
Avoid rigid sentence lengths, quizzes on unexplained material, and praise

From rcedwards/blaude-bode, MIT.

More from rcedwards/blaude-bode