Self-Improvement Skill

Capture feedback and corrections to continuously enhance repository knowledge.

Philosophy

This skill implements the “Continuous Improvement” principle: knowledge gained during work should be captured immediately, not lost. When users provide feedback, corrections, or new patterns emerge, this skill determines where that knowledge belongs and updates the appropriate documentation.

Key principle: Documentation updates should go hand-in-hand with the work that revealed them. Don’t create separate PRs for documentation – include them in the current branch.

Quick Start

Feedback Types:
- Correction      → Fix incorrect information in source
- Clarification   → Add missing context to existing docs
- New Pattern     → Add to appropriate CLAUDE.md or skill
- Anti-Pattern    → Add to root CLAUDE.md anti-patterns
- Workflow        → Update or create skill
- Preference      → Add to appropriate CLAUDE.md

Execution Flow

Phase 1: Feedback Classification

Analyze the user’s feedback to determine its type:

Phase 2: Target Location Discovery

Use this decision tree to find where the knowledge belongs:

Is this correcting existing documentation?
├─ YES → Find and update the source of the incorrect information
│        Search: CLAUDE.md files, skills, referenced docs
└─ NO → Continue

Is this about enterprise principles or universal processes?
├─ YES → Root CLAUDE.md
│        Sections: Core Principles, Anti-Patterns, Universal Standards
└─ NO → Continue

Is this specific to a subsystem?
├─ Infrastructure (terragrunt, modules, stacks) → infrastructure/CLAUDE.md
├─ Kubernetes Platform (helm, flux, resourcesets) → kubernetes/platform/CLAUDE.md
├─ Kubernetes Clusters (bootstrap, per-cluster) → kubernetes/clusters/CLAUDE.md
├─ Task Runner (taskfiles, commands) → .taskfiles/CLAUDE.md
└─ NO → Continue

Is this a procedural workflow with 5+ steps?
├─ YES → Skill (create new or update existing)
│        Check: Does a related skill already exist?
└─ NO → Continue

Is this a quick reference or simple pattern?
├─ YES → Add to appropriate module CLAUDE.md
└─ NO → Ask user for guidance

Phase 3: User Confirmation

ALWAYS use AskUserQuestion before making updates.

Present the proposed update:

1. Show the classified feedback type
2. Show the proposed target location
3. Show a preview of the proposed change
4. Offer alternatives if uncertain

Example confirmation flow:

I've identified this as a "New Pattern" that should be added to
infrastructure/CLAUDE.md in the "Testing Patterns" section.

Proposed addition:
───────────────────────────────────────────────────
When writing module tests, always include a negative test case
that verifies the module fails gracefully with invalid inputs.
───────────────────────────────────────────────────

Options:
1. Add to infrastructure/CLAUDE.md (Recommended)
2. Add to a different location
3. Create as a new skill
4. Skip - don't document this

Phase 4: Apply Update

After user confirmation:

1. For CLAUDE.md updates:

   • Read the target file
   • Find the appropriate section
   • Add the new content with proper formatting
   • Maintain existing style and structure

2. For skill updates:

   • Read the existing skill SKILL.md
   • Identify the relevant section
   • Add or modify content
   • Update references if needed

3. For new skills:

   • Use the skill-creator guidance
   • Create SKILL.md with proper frontmatter
   • Register in settings if needed

4. For corrections:

   • Find all occurrences of the incorrect information
   • Update each occurrence
   • Verify no broken references result

Integration with PR Workflow

Documentation updates are part of the current work, not separate.

When working on a branch:

• Include documentation updates in the same commits
• Group related code and doc changes together
• Don’t create separate “update docs” commits unless substantial

When completing work:

• Review what was learned during implementation
• Proactively suggest documentation updates for new patterns
• Capture user feedback immediately, in the same PR

Content Formatting Guidelines

For CLAUDE.md additions

Match the existing style:

• Use tables for structured comparisons
• Use bullet points for lists
• Use code blocks for examples
• Keep entries concise – this is reference material
• Use Mermaid diagrams for flows, architectures, and decision trees — never create new ASCII art diagrams
• See root CLAUDE.md “Diagram Standards” section for Mermaid type selection and formatting rules

For skill additions

Follow skill patterns:

• Procedural, step-by-step guidance
• Include error handling
• Add examples with context
• Reference supporting docs

For anti-pattern additions

Format consistently with existing anti-patterns:

## Anti-Pattern Category

- **NEVER** do X because Y
- **NEVER** do Z without explicit human approval

Examples

Example 1: User Correction

User: “Actually, you should use task tg:plan-dev not task tg:plan dev“

Classification: Correction Target: Search for incorrect command usage Action: Find and fix all occurrences of the incorrect command format

Example 2: New Pattern

User: “When adding a new Helm release, always check kubesearch first for examples”

Classification: New Pattern Target: kubernetes/platform/CLAUDE.md or flux-gitops skill Action: Add to the appropriate location after confirmation

Example 3: Preference

User: “I prefer smaller, focused commits over large combined ones”

Classification: Preference Target: Root CLAUDE.md, Universal Standards section Action: Add or update commit guidelines

Example 4: Anti-Pattern Discovery

User: “Never use kubectl apply directly, always go through GitOps”

Classification: Anti-Pattern Target: Root CLAUDE.md, Anti-Patterns section Action: Add to Kubernetes Safety anti-patterns

Proactive Self-Improvement

This skill should also be invoked proactively when:

1. After completing implementation work: Review what was learned and suggest documentation updates

2. When patterns repeat: If explaining the same concept twice, suggest capturing it

3. When user corrects an approach: Immediately offer to document the correction

4. When discovering undocumented behavior: Offer to add it to relevant docs

Error Handling

If uncertain about placement:

• Always ask the user via AskUserQuestion
• Provide multiple options with explanations
• Default to asking rather than guessing wrong

If the target file doesn’t exist:

• For CLAUDE.md: Check if it should be created (new module?)
• For skills: Offer to create a new skill
• For other docs: Ask user for guidance

If the update would be substantial:

• Preview the full change before applying
• Consider if it should be a separate skill instead
• Break large updates into logical chunks