Skip to content

Commit 466b9b7

Browse files
Copilotnathanjmcdougall
Copilot
and
nathanjmcdougall
authored
Make agent lessons more action-oriented (#1894)
* Initial plan * Make agent lessons more action-oriented Update usethis-lesson-create skill to emphasize concrete action items (skill updates, automated checks, code refactors) over recording what was done. Replace Resolution/Follow-up template sections with a single Recommended action section. Update procedure, examples, and AGENTS.md. Resolves #1876 Agent-Logs-Url: https://github.com/usethis-python/usethis-python/sessions/859e0b40-f4a8-4952-8ef9-1f30295ff64e Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: nathanjmcdougall <18602289+nathanjmcdougall@users.noreply.github.com>
1 parent 5f17d9a commit 466b9b7

2 files changed

Lines changed: 35 additions & 12 deletions

File tree

‎.agents/skills/usethis-lesson-create/SKILL.md‎

Lines changed: 34 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -4,14 +4,18 @@ description: Create a lesson from a development difficulty, covering root cause
44
compatibility: usethis, GitHub, gh CLI
55
license: MIT
66
metadata:
7-
version: "1.1"
7+
version: "1.2"
88
---
99

1010
# Creating a Lesson
1111

1212
Lessons are how this project improves over time. When you encounter a difficulty, a
1313
surprising failure, or unexpected user feedback, a lesson captures not just what happened
14-
but _why_ — so the same mistake is not repeated by future agents or developers.
14+
but _why_ — and proposes a concrete action to prevent the same mistake from recurring.
15+
16+
A lesson is **not** a record of what was done to fix a one-off problem. It is a proposal
17+
for a lasting improvement: an update to an agent skill, a new or improved linting/prek
18+
hook, or a code refactor that structurally prevents the class of issue.
1519

1620
## Why root cause analysis matters
1721

@@ -25,6 +29,8 @@ A well-formed lesson answers:
2529
1. **What** went wrong (the observable symptom).
2630
2. **Why** it went wrong (the root cause, not the symptom).
2731
3. **What principle** this reveals (something actionable for the future).
32+
4. **What concrete action** would prevent recurrence (a skill update, a hook, or a
33+
refactor — not just "be more careful next time").
2834

2935
## Self-containment and abstraction
3036

@@ -75,10 +81,22 @@ cause is self-evident and offers no transferable principle.
7581
even if the exact code, file, or function name changes. Avoid naming specific
7682
implementation details unless the principle is truly about that specific thing.
7783
See the "Self-containment and abstraction" section above for guidance.
78-
4. **Fill in the lesson template** — see the template below.
79-
5. **File as a GitHub issue** using the `usethis-github-issue-create` skill, with
84+
4. **Propose a concrete action** — every lesson must recommend at least one specific
85+
improvement. Choose from these categories (in order of preference):
86+
- **Skill update** — add or revise guidance in an existing agent skill so future
87+
agents avoid the mistake. This is the most common and preferred action.
88+
- **Automated check** — propose a new or improved linting rule, prek hook, or CI
89+
check that catches the mistake automatically.
90+
- **Code refactor** — suggest a structural change to the code that makes the mistake
91+
impossible or much harder to make.
92+
93+
Do **not** simply record what was done to fix the immediate instance. The action must
94+
prevent the _class_ of problem, not just the single occurrence.
95+
96+
5. **Fill in the lesson template** — see the template below.
97+
6. **File as a GitHub issue** using the `usethis-github-issue-create` skill, with
8098
label `agent` and any other relevant labels (e.g. `bug`, `documentation`).
81-
6. **Report the lesson** in your PR description or final progress report so reviewers
99+
7. **Report the lesson** in your PR description or final progress report so reviewers
82100
are aware.
83101

84102
## Root cause analysis
@@ -103,6 +121,7 @@ allows it" is not actionable).
103121
| Why 2 | There was no automated check enforcing that sync. |
104122
| Root cause | Sync between two authoritative sources was manual with no enforcement. |
105123
| Principle | Any two artefacts that must stay in sync need an automated check; manual sync drifts. |
124+
| Action | Add a prek hook that verifies the skills table in AGENTS.md matches the directory. |
106125

107126
## Lesson template
108127

@@ -126,15 +145,19 @@ situation. Phrase it as actionable guidance: "Always ...", "Never ...", "When X,
126145
do Y ...". Avoid naming specific functions, classes, or files unless the principle is
127146
truly about that specific thing. Do not reference memories or prior sessions.>
128147

129-
## Resolution
148+
## Recommended action
130149

131-
<How the problem was resolved in this instance, including any code or config changes
132-
made. Brief — a sentence or two is enough.>
150+
<One or more concrete improvements to prevent this class of problem from recurring.
151+
Each action should fall into one of these categories:
133152

134-
## Follow-up
153+
- **Skill update:** which skill to update and what guidance to add or revise.
154+
- **Automated check:** a new or improved linting rule, prek hook, or CI check to add.
155+
- **Code refactor:** a structural change that makes the mistake impossible or harder.
135156

136-
<Any work that remains, such as adding an automated check, updating documentation, or
137-
creating a related issue. Leave blank if none.>
157+
Do not record what was done to fix the immediate instance — focus on what should change
158+
to prevent recurrence. If the recommended action has already been completed as part of
159+
the current session, say so, but still describe the action clearly so the issue can be
160+
verified and closed.>
138161
```
139162

140163
## Filing the issue

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -478,4 +478,4 @@ External skills can be installed if they are not present — see the `usethis-sk
478478

479479
## Lessons
480480

481-
When you are working on a problem, you are almost always going to encounter a difficulty. This is great — it's an opportunity for learning. ALWAYS make a note explicitly of what lessons you are drawing as you complete a task or when receiving user feedback. After finishing work on a task, report back all your lessons. Use the `usethis-lesson-create` skill to perform root cause analysis, generalise the principle at play, and file each lesson as a GitHub issue so it can be triaged and tracked.
481+
When you are working on a problem, you are almost always going to encounter a difficulty. This is great — it's an opportunity for learning. ALWAYS make a note explicitly of what lessons you are drawing as you complete a task or when receiving user feedback. After finishing work on a task, report back all your lessons. Use the `usethis-lesson-create` skill to perform root cause analysis, generalise the principle at play, propose a concrete action (skill update, automated check, or code refactor), and file each lesson as a GitHub issue so it can be triaged and tracked. Lessons should recommend lasting improvements, not just record what was done.

0 commit comments

Comments
 (0)