Improve

Improve

Target area: $ARGUMENTS

Step 0 — System health check

Before analyzing feedback, check the overall lifecycle health:

1. Common-mistakes capacity: Read .claude/rules/common-mistakes.md and count items.

• At 10 (full): "common-mistakes.md is at capacity. Before adding new patterns, let's graduate resolved items to docs/learnings/." Then for each item, ask if it's still active or can be graduated. Graduate resolved ones using the format in docs/learnings/README.md before proceeding to Step 1.
• At 8-9: Note that capacity is almost full. Continue to Step 1 but flag this.

1. Old learnings: Glob docs/learnings/*.md (exclude README.md). Check file dates in filenames (YYYY-MM-DD prefix).

• Any older than 6 months? List them and ask: "These learnings are older than 6 months. Are any no longer relevant? I can archive them to docs/archive/."
• If user says yes → move the files to docs/archive/ and continue.

1. Duplicate memories: Glob memory/*.md. Check for files with overlapping descriptions or topics.

• If found → suggest merging into a single memory file.

After health check, proceed to feedback analysis.

---

Step 1 — Collect feedback memories

Glob memory/*.md. For each file, read the YAML frontmatter. Keep only files where type: feedback.

If no feedback memories exist, stop:

No feedback memories found in memory/.
Feedback memories are created automatically when you correct Claude during a session.
Nothing to improve yet — keep working and check back later.

Step 2 — Group by area

Read the content of each feedback memory. Extract the area/topic from:

• The description field in frontmatter
• Keywords in the content (testing, imports, lint, naming, formatting, security, etc.)

Group feedback files by area. Count entries per area.

Step 3 — Filter by argument

If $ARGUMENTS is not empty, filter to only the matching area. If no match, list available areas and ask which one.

If $ARGUMENTS is empty, continue with all areas.

Step 4 — Analyze and recommend

For each area, apply thresholds:

| Count | Recommendation | | ----- | ---------------------------------------------------- | | 1-2 | Skip — not a pattern yet, memory is sufficient | | 3-4 | Suggest adding to common-mistakes.md | | 5+ | Suggest creating a permanent control via /new-rule |

Print a summary:

=== Feedback Analysis ===

:  feedback entries → 
:  feedback entries → 
:  feedback entries → Skip (not a pattern yet)

Which area do you want to act on? (or "all" for batch processing)

If only one area qualifies (3+), print the recommendation and proceed directly to Step 5 without asking.

Step 5 — Pre-flight checks

Before acting, verify constraints:

1. Read .claude/rules/common-mistakes.md — count current items

• If at 10 items and action is "add to common-mistakes" → suggest /graduate first
• If at 8-9 items → warn that capacity is almost full

1. Glob .claude/rules/*.md — estimate total token budget

• If approaching ~500 tokens → warn before creating a new rule file

1. Check if a control already exists for this area

• Glob .claude/rules/ for files matching the area keyword
• If found → suggest updating the existing control instead of creating a new one

Step 6 — Execute action

For common-mistakes (3-4 feedback entries)

1. Synthesize the feedback entries into a single, concise mistake description
2. Show the proposed entry to the user:

```text Proposed common-mistakes entry:

N. **** —

Source: feedback memories ()

Add this to common-mistakes.md? ```

1. Wait for user approval. If rejected, stop — leave memories unchanged.
2. Edit .claude/rules/common-mistakes.md — append the new numbered item
3. Proceed to Step 7 (cleanup)

For controls (5+ feedback entries)

1. Synthesize feedback entries into a control description
2. Show the proposed control to the user:

```text Proposed control from feedback entries:

Name: -conventions Surface: Scope: Content:

• ...

Create this control? (I'll use /new-rule to scaffold it properly) ```

1. Wait for user approval. If rejected, stop — leave memories unchanged.
2. Provide the control details so the user can invoke /new-rule with context,

or directly apply changes following /new-rule surface classification

Step 7 — Clean up resolved feedback

After successfully creating a control or common-mistake entry:

1. List the feedback memory files that were consumed
2. Ask the user:

```text These feedback memories are now captured as a :

• memory/.md
• memory/.md
• ...

Delete them? (They're redundant now — the rule enforces the behavior every session) ```

1. If yes → delete the files and remove their entries from memory/MEMORY.md
2. If no → leave them (user may want to keep for reference)

Step 8 — Print summary

=== Done ===

Action: >
Source:  feedback memories from 
Cleaned up: 

Remaining feedback areas with patterns:
  :  entries (run /improve  to process)

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.