Graduate

Graduate a common mistake

Target item: $ARGUMENTS

Step 1 — Read common-mistakes.md

Read .claude/rules/common-mistakes.md. Show the current list.

Step 2 — Identify the item to graduate

From $ARGUMENTS:

• If a number → graduate that numbered item
• If a keyword → find the item that matches, confirm with user
• If no argument → list all items and ask which to graduate

If the list has fewer than 8 items, ask: "The list isn't full yet — are you sure you want to graduate this now, or is it no longer relevant?"

Step 3 — Check docs/learnings/ template

Read docs/learnings/README.md if it exists to understand the expected format.

Step 4 — Ask for context before writing

Before I graduate "", a few things:

1. Why is this being graduated?
   a) It's fully resolved — we fixed the root cause
   b) It happened enough times that it needs a proper write-up
   c) It's no longer relevant to this project

2. Is there a specific incident or PR where this came up?
   (optional — helps future readers understand the severity)

3. Any additional detail beyond what's in the mistake entry?

Wait for answers.

Step 5 — Write docs/learnings/YYYY-MM-DD-.md

Use today's date. Slug = kebab-case version of the mistake title.

# 

**Graduated**: 
**Source**: common-mistakes.md

## The mistake

## Why it matters

## Root cause

## How to avoid it

## Reference

Step 6 — Remove from common-mistakes.md

Edit .claude/rules/common-mistakes.md:

• Remove the graduated item
• Renumber the remaining items (1, 2, 3...)
• Do not leave a gap or placeholder

Step 7 — Print summary

Graduated: ""
Written to: docs/learnings/YYYY-MM-DD-.md
Removed from: .claude/rules/common-mistakes.md
Remaining items: /10

The learning is now in Tier 2 (docs/learnings/) — loaded when relevant,
not every session. This frees up a slot in common-mistakes.md.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: enbiyagoral
• Source: enbiyagoral/.claude
• License: MIT

Install and usage instructions live in the source repository linked above.