learn-from-feedback

name	learn-from-feedback
description	Reflect on a developer correction and update skills or CLAUDE.md so the same mistake isn't made twice. Trigger whenever the user says you made a mistake, that code needs reworking, that an approach was wrong, or pushes back on a pattern you used. Before continuing the fix, decide whether existing guidance should be updated or a new skill is needed.
metadata	{"version":"1.0"}
allowed-tools	Read Write Edit Glob Grep

Learn From Feedback

The goal: turn a one-time correction into permanent guidance so the same mistake never happens again.

When to trigger

Whenever the developer pushes back on something you did or wrote:

• "You made a mistake"
• "This needs reworking"
• "We don't do that here"
• "Wrong approach / wrong file / wrong pattern"
• "Why did you do X instead of Y?"

Before fixing the code, take 30 seconds to ask: would another agent (or future-me) make this same mistake without different guidance? If yes, the guidance is the bug, not just the code.

Steps

1. Understand the correction

What exactly was wrong? Be precise:

• A code pattern (e.g., used ternary instead of early return)
• A workflow step (e.g., paused for approval that wasn't wanted)
• An assumption (e.g., assumed a service existed)
• A skipped check (e.g., didn't read CLAUDE.md first)
• A naming/path/structure choice

2. Trace the root cause

Why did you do it the wrong way?

• A skill told you to → that skill is wrong or outdated
• A skill was silent on the topic → the skill is incomplete
• CLAUDE.md was silent or unclear → CLAUDE.md needs the rule
• No skill or doc covers this area → a new skill may be warranted

3. Decide the right artifact to update

Situation	Action
Existing skill gave wrong instructions	Edit that skill's SKILL.md
Existing skill missed an edge case	Add the case to that SKILL.md
Rule is broad / cross-cutting (style, conventions, workflow)	Edit root CLAUDE.md
No skill covers this whole area	Suggest a new skill — propose name, description, scope; wait for confirmation before creating
One-off mistake with no general lesson	Skip — just fix the code

4. Make the edit minimal and durable

• Lead with the rule. State the do/don't in one sentence at the top.
• One-line "why". Give the reason so future readers can judge edge cases — not just blindly follow.
• Don't bury it in examples. A long code block hides the rule.
• Update the description field if it's a SKILL.md and the trigger conditions changed.
• wl-hopper has a single root CLAUDE.md — all cross-cutting rules go there. Package-specific rules can be noted in context (e.g., "this applies to packages/components") but still live in root CLAUDE.md.

5. Commit to the current branch

Skill / CLAUDE.md self-improvements always commit to the active branch — never a separate PR. The improvement was triggered by the work in flight, so it ships with that work. Stage the edited skill/doc files alongside (or as a follow-up commit on) the feature commit. Don't ask the dev to choose between branches; don't open a side PR.

6. Confirm with the developer

In one or two sentences: name the file you updated and the rule you added. Example: "Updated root CLAUDE.md to add a rule that component styles must use token CSS variables — caught by your earlier comment."

When NOT to use this skill

• Typos, misread paths, mechanical errors with no pattern behind them
• Pure user preference for this specific task, not a durable rule
• Something already covered — re-read the existing guidance instead of editing it
• The mistake was caused by skipping a doc you should have read; the fix is to read it next time, not to duplicate the rule

Where new skills live

All skills for wl-hopper go in a single location:

Scope	Location	Index in
Any skill	.claude/skills/<name>/SKILL.md	root CLAUDE.md Skills table

Note: .agents/skills is a git-tracked symlink pointing to .claude/skills — either path works.

When creating a new skill, also add a row to the Skills table in root CLAUDE.md so it's discoverable.

Suggesting a new skill (template)

When proposing a new skill, give the developer:

Proposed skill: <kebab-case-name>
Trigger: <when should this skill activate?>
Purpose: <what does it do? one or two sentences>

Wait for confirmation before creating the file.