---
name: knowledge-graduation
description: Graduated knowledge system - corrections become temporary lessons that can graduate to permanent CLAUDE.md rules
---

# Knowledge Graduation Skill

A graduated knowledge system where corrections from review cycles become temporary lessons that can graduate to permanent CLAUDE.md rules after proving their value.

## When to Use

Use this skill when:
- A review correction reveals a pattern worth remembering
- You want to review accumulated lessons for promotion or archival
- A lesson has proven its value and should become a permanent rule
- Stale lessons need cleanup

## Phases

### Phase 1: Capture

When invoked after a review correction, create a lesson:

```bash
~/.claude/skills/afx-knowledge-graduation/knowledge-manager.sh add "<description>" "<ticket_id>"
```

This creates a lesson file in `.artifex/lessons/` with:
- Auto-generated lesson ID (L001, L002, ...)
- Description of the correction
- Source ticket ID
- Creation date
- Application count: 0
- Status: active

After creation, prompt the user to provide additional context:
- **Context:** What happened during the review that surfaced this lesson?
- **Rule:** What is the specific rule to follow?
- **When to apply:** Under what circumstances should this rule be checked?

Then update the lesson file with the additional details.

### Phase 2: Review

When invoked with the `review` argument, scan all active lessons:

```bash
~/.claude/skills/afx-knowledge-graduation/knowledge-manager.sh list
~/.claude/skills/afx-knowledge-graduation/knowledge-manager.sh check
```

This will:
1. List all active lessons with their age and application count
2. Identify lessons ready for graduation (14+ days old AND applied 3+ times)
3. Identify stale lessons (not applied in 30+ days)
4. Suggest promotions and archival actions

Present the results to the user and ask which actions to take.

### Phase 3: Graduate

When invoked with the `graduate` argument and a lesson ID:

```bash
~/.claude/skills/afx-knowledge-graduation/knowledge-manager.sh graduate <lesson_id>
```

This will:
1. Read the lesson file
2. Extract the rule description
3. Append it as a permanent rule to the project's CLAUDE.md file
4. Move the lesson file to `.artifex/lessons/graduated/`

The graduated rule is added to CLAUDE.md under a `## Graduated Lessons` section with:
- The rule description
- Origin reference (lesson ID and source ticket)

### Phase 4: Archive

When invoked with the `archive` argument:

```bash
~/.claude/skills/afx-knowledge-graduation/knowledge-manager.sh archive <lesson_id>
```

This moves stale or irrelevant lessons to `.artifex/lessons/archived/` without adding them to CLAUDE.md.

## Applying Lessons

When working on any ticket, check active lessons for applicability. If a lesson is relevant and followed, increment its application count:

```bash
~/.claude/skills/afx-knowledge-graduation/knowledge-manager.sh apply <lesson_id>
```

This updates the `application_count` and `last_applied` date in the lesson file.

## Lesson File Format

Lessons are stored as markdown files with YAML frontmatter in `.artifex/lessons/`:

```markdown
---
id: L001
description: "Always check for null before accessing nested properties"
source_ticket: "2.3"
created: 2026-04-11
last_applied: 2026-04-11
application_count: 0
status: active
---

## Lesson: Always check for null before accessing nested properties

**Context:** During implementation of ticket 2.3, the review caught a null reference...

**Rule:** Before accessing `obj.nested.property`, always verify `obj.nested` exists.

**When to apply:** Any time code accesses properties more than one level deep.
```

## Integration with Ticket Implementation

During the ticket-implementation workflow:
1. **Before implementation:** Review active lessons for any that may apply to the current ticket
2. **During review:** If a correction is made, capture it as a lesson
3. **After completion:** Run a periodic review to check for graduation candidates

## Directory Structure

```
.artifex/
  lessons/
    L001.md          # Active lesson
    L002.md          # Active lesson
    graduated/
      L003.md        # Graduated to CLAUDE.md
    archived/
      L004.md        # Archived (stale or irrelevant)
```

## Initialization

Before first use, initialize the directory structure:

```bash
~/.claude/skills/afx-knowledge-graduation/knowledge-manager.sh init
```

## Example Usage

**Capture a lesson after review:**
```
/afx-lesson "Always validate API response status before parsing body" 2.3
```

**Review all lessons:**
> "Review my lessons for graduation candidates"

Claude will run `check` and present:
- Lessons ready for graduation
- Stale lessons to consider archiving
- Summary statistics

**Graduate a proven lesson:**
> "Graduate lesson L001 to CLAUDE.md"

**Archive a stale lesson:**
> "Archive lesson L004"