write-teach-commit

name	write-teach-commit
description	Draft `teach:` commit messages for `.github/workflows/improve-add-skill.yml`. Use when preparing or reviewing a correction commit that should trigger the Improve Add Skill workflow from `$add` categorization feedback, including moved plugin entries, removed or excluded plugins, changed `.reason.md` categories, or review-approved rationale that should be generalized into `.codex/skills/add/**`.

Write Teach Commit

Overview

Write a commit message that both triggers the workflow and gives $improve-add-skill enough context to learn the reusable correction.

The workflow only runs on pushes to branches matching ai-* when the head commit message starts with teach:. If the correction should not update .codex/skills/add/**, do not use a teach: subject.

Workflow

1. Inspect the user-provided diff, staged changes, PR review comments, .reason.md, and changed plugin list entries.
2. Identify the actual correction: a plugin moved between categories, an exclusion, a changed category path, or explicit rationale for why $add was wrong.
3. Separate evidence from the lesson: evidence may name repositories and files; the lesson should describe the reusable placement rule.
4. Draft a subject that starts exactly with teach: and names the generic lesson, not just the repository touched.
5. Add a short body when the subject alone cannot explain the correction.

Message Shape

Prefer this structure:

teach: <generic add-skill lesson>

Correction:
- <owner/repo>: <old category or decision> -> <new category or decision>

Reusable lesson:
- <category/exclusion rule that would have prevented the mistake>

Evidence:
- <short source, such as review comment, .reason.md row, or file path>

Keep the subject concise. Use the body for category paths and details.