teach-me
Post-run learning workflow that generates a visual teaching report, builds a human mental model of the session, and verifies mastery through restatement, explanation, and quizzes.
- License 许可
- Apache-2.0
- 最近更新
- 2026-07-13
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- teach-me
- description
- Post-run learning workflow that generates a visual teaching report, builds a human mental model of the session, and verifies mastery through restatement, explanation, and quizzes.
03 SKILL.md 正文
Teach Me
Use this skill after an implementation session, successful run, or partial run when the human wants to understand what happened and be able to explain the project status to others.
This skill is not part of /build-auto. It runs after the build loop or at an explicit learning checkpoint.
Purpose
Convert run evidence into human understanding.
The human should leave able to explain:
- what problem was being solved;
- why the problem existed;
- what branches or alternatives existed;
- what was implemented;
- why it was implemented that way;
- how it works end to end;
- what edge cases and failure modes matter;
- what evidence proves the work;
- what the current project status is;
- what remains to be done.
Required evidence
Before teaching, gather:
tasks/run_manifest.jsontasks/run_state.jsontasks/feature_list.json- IDSD artifacts referenced by the manifest:
- intent
- context
- expectations
- task contracts
docs/session-reports/<run-id>/final.json, if presentdocs/run-reports/<run-id>.md, if presentdocs/implementation-results/**docs/reviews/**docs/validation-results/**docs/pull-requests/**, if present- project-pack review evidence, if present
docs/learning/<run-id>-teach-me-checklist.md, if present
Then generate or refresh the teaching report:
python -B scripts/teach_me_report.py
Teaching sequence
Stage 1 — Restatement first
Ask the human to restate their current understanding before explaining.
Use prompts such as:
- “Explain what you think happened in this run.”
- “What goal was the session trying to satisfy?”
- “Which tasks do you think were completed?”
- “What part still feels unclear?”
Do not start with a lecture unless the human explicitly asks for one.
Stage 2 — Gap diagnosis
Compare the human restatement against the checklist.
Classify each area as:
masteredpartialmissingincorrectnot_covered_yet
Use the checklist file as the durable source:
docs/learning/<run-id>-teach-me-checklist.md
Stage 3 — Incremental teaching
Teach one stage at a time.
Recommended order:
- Problem and intent
- Context and constraints
- Expectations and boundaries of done
- Task-by-task execution
- Solution design and key decisions
- Code path / data path / workflow walkthrough
- Edge cases and failure modes
- Test, review, validation, and domain-review evidence
- Current status, risks, blockers, deferred work, and next steps
Do not move to the next stage until the human can explain the current stage.
Stage 4 — Drill-down
For each important point, ask why at least once.
Examples:
- “Why did this problem exist?”
- “Why was this design chosen?”
- “Why does this edge case matter?”
- “Why does this test prove the behaviour?”
- “Why would an alternative have been riskier?”
Support different explanation levels when requested:
- ELI5: non-technical, analogy-first
- ELI14: simple technical model
- ELII: explain like an intern joining the project
- Senior engineer: architecture/trade-off level
- Stakeholder: business outcome and risk level
Stage 5 — Use evidence, not memory
Ground explanations in files and reports.
Show relevant snippets when useful:
- task contract excerpts;
- code changed;
- test added;
- validation result;
- review finding;
- domain invariant;
- run report section.
Use the debugger or file navigation when it would improve understanding.
Stage 6 — Quiz
Ask open-ended or multiple-choice questions.
Rules:
- Do not reveal multiple-choice answers before submission.
- Rotate the correct answer position.
- Ask at least one “why” question.
- Ask at least one edge-case question.
- Ask at least one current-status question.
Examples:
Open-ended:
- “Explain the end-to-end flow from intent to completed task commit.”
- “What evidence proves task X is complete?”
- “What would fail if the domain invariant were violated?”
Multiple-choice:
- “Which artifact is the implementation authority: A) intent, B) run manifest, C) HTML report, D) README?”
- “Which role validates proof against the task contract: A) build-agent, B) validator-agent, C) delivery-agent, D) teacher-agent?”
Only mark mastery after the human answers correctly or self-corrects after explanation.
Stage 7 — Report update
At the end, regenerate the report if the checklist changed:
python -B scripts/teach_me_report.py
The HTML report must make the mental model visually clear.
Checklist requirements
The checklist must cover:
- Problem
- Intent and constraints
- Expectations
- Context
- Completed tasks
- Implementation flow
- Design decisions
- Edge cases
- Tests and validation
- Reviews and repairs
- Current status
- Remaining risks and next steps
Completion statuses
Use these statuses:
LEARNING_COMPLETE: human demonstrated mastery across all configured dimensions.LEARNING_IN_PROGRESS: human made progress but some checklist items remain partial/missing.LEARNING_BLOCKED: evidence is missing or the run state is too incomplete to teach reliably.
Never mark LEARNING_COMPLETE just because the human says “got it.”
Output
End with:
- learning status;
- mastered topics;
- remaining gaps;
- generated HTML report path;
- generated Markdown report path;
- checklist path;
- recommended next teaching session, if needed.
04 同仓库更多 Skills
invoice-domain-review
Domain review for contractor invoice governance, ingestion, reconciliation, attendance attribution and billing evidence.
python-domain-review
Reviews generic Python implementation against task intent, API expectations, simplicity and maintainability.
verified-commit
Creates a task-scoped commit only after validator and exact-tree postflight pass.
using-agent-skills
Selects and applies the smallest relevant set of skills for a task, preventing generic prompting and unused specialist guidance. Use at the start of every command, task, review, or repair cycle.
testing-patterns
Designs focused, hierarchical, regression, boundary, integration, and end-to-end tests for vertical-slice implementation. Use before and after implementation, and during test review.
test-hierarchy
Classifies and enforces the required unit, integration, local E2E, and cloud E2E test tier for a task or run.