Update Rules Skill

Purpose

Create a meta-learning system that systematically captures insights from each development session and encodes them into project instruction files. This ensures that:

• Technical patterns and conventions are documented as they emerge

• Common pitfalls and solutions are preserved

• Architectural decisions and their rationale are recorded

• Development workflows continuously improve

• Organizational knowledge compounds over time

When to Use

Invoke /update-rules at the end of a development session to:

• Capture learnings from the work completed

• Analyze patterns and decisions made

• Update instruction files with new knowledge

• Maintain consistency across all rules files

Learning Categories

The skill extracts and categorizes learnings into:

1. Technical Patterns

• Code patterns that emerged or were refined

• Architecture decisions and trade-offs

• Performance optimizations discovered

• Type safety improvements

2. Workflow Improvements

• Development process enhancements

• Tool usage patterns

• Testing strategies

• Debugging techniques

3. Domain Knowledge

• Business logic insights

• Data model understandings

• API integration patterns

• Third-party service learnings

4. Best Practices

• Conventions established

• Anti-patterns to avoid

• Error handling strategies

• Security considerations

5. Project-Specific Insights

• Phase-specific learnings

• Feature implementation patterns

• Integration approaches

• Deployment knowledge

Rules Files Structure

The skill updates these files, each with a specific audience:

File Audience Focus

CLAUDE.md

Claude Code (Lead Engineer) Project context, architecture, leadership responsibilities

GEMINI.md

Gemini (Design Lead) Design patterns, frontend implementation, UI/UX guidelines

CODEX.md

Codex (Senior Engineer) Backend patterns, execution workflows, implementation guidelines

.claude/rules.md

Claude Code Detailed coding conventions, patterns, technical rules

.codex/rules.md

Codex (Senior Engineer) Backend implementation patterns, Convex usage, API patterns

Execution Flow

When /update-rules is invoked:

Step 1: Session Analysis

1. Review conversation history
2. Identify file changes made
3. Extract code patterns implemented
4. Note decisions and rationale
5. Capture challenges overcome
6. Identify reusable patterns

Step 2: Learning Extraction

For each learning, document:

• What was built/discovered
• Why this approach was chosen
• Alternatives considered
• When to apply this pattern
• Relevant file locations

Step 3: Categorize Learnings

Organize by:

• Technical patterns (code structure, architecture)
• Workflow improvements (process, tooling)
• Domain knowledge (business logic, data models)
• Best practices (conventions, anti-patterns)
• Project-specific (phase work, integrations)

Step 4: Rules File Updates

For each rules file:

1. Read current content
2. Identify relevant section for new learning
3. Check for conflicts with existing rules
4. Merge learning into appropriate section
5. Maintain file structure and formatting
6. Preserve existing content

Update Strategy

Additive Updates (Preferred)

New Pattern: [Pattern Name]

Context: [When this applies]

Implementation: ```typescript // Code example ```

Rationale: [Why this approach]

See also: [Related file:line]

Enhancement Updates

[Existing Section]

Enhanced guidance:

• [New insight that refines existing rule]
• [Additional context or example]

Updated pattern: ```typescript // Improved implementation ```

Conflict Resolution

If new learning conflicts with existing rule:

1. Flag the conflict explicitly
2. Present both approaches with trade-offs
3. Recommend user decision
4. Do NOT silently override existing rules

Output Format

After execution, provide:

Learning Summary

Session Learnings Captured

Session focus: [Brief description]

Learnings extracted: [Number] total

• Technical patterns: [Number]
• Workflow improvements: [Number]
• Domain knowledge: [Number]
• Best practices: [Number]
• Project-specific: [Number]

Key Learnings

1. [Learning Name]

Category: [Technical Pattern / Workflow / Domain / Best Practice / Project-Specific]

What: [One sentence description]

Why it matters: [Value/impact]

Applied to: [Which rules files were updated]

Location: [File paths where this pattern exists]

2. [Next Learning]

[Repeat structure]

Files Updated

Conflicts Detected

[If any conflicts were found]

Conflict in [filename]:

• Existing rule: [Summary]
• New learning: [Summary]
• Recommendation: [Suggested resolution]

Next Actions

1. Review updated rules files for accuracy
2. Resolve any conflicts identified above
3. Consider updating related documentation

Update Guidelines

DO

• ✅ Extract concrete, actionable patterns

• ✅ Include code examples when relevant

• ✅ Reference specific files and line numbers

• ✅ Maintain existing file structure

• ✅ Preserve all existing content

• ✅ Add new sections when appropriate

• ✅ Link related patterns together

• ✅ Document rationale for decisions

• ✅ Include "when to use" guidance

• ✅ Flag conflicts for user resolution

DON'T

• ❌ Delete existing rules without explicit approval

• ❌ Override conflicting rules silently

• ❌ Add vague or theoretical guidance

• ❌ Include learnings without context

• ❌ Break existing file formatting

• ❌ Duplicate content across files

• ❌ Add rules that contradict existing ones

• ❌ Include session-specific details that won't generalize

Section Mapping

CLAUDE.md Sections

• Organizational Structure → Team workflow learnings
• CRITICAL: Before Writing Any Code → Pre-coding checklists
• Critical Patterns → Code patterns, DO/DON'T lists
• Quick Reference → Code snippets and examples
• Mermaid Diagram Rule → Diagram conventions
• User Learning Style → Communication preferences
• Available Skills → New skills registry

GEMINI.md Sections

• Your Core Responsibilities → Design process learnings
• Design Standards → UI/UX patterns, component conventions
• Tech Stack → Frontend technology patterns
• Critical Patterns → Frontend code patterns
• Quick Reference → React/Tailwind patterns
• Mermaid Diagram Guidelines → Visualization patterns
• Coding Standards → Design-specific conventions

CODEX.md Sections

• Your Role: Senior Engineer → Implementation responsibilities
• CRITICAL: Before Writing Any Code → Backend workflow
• Tech Stack → Backend technology patterns
• Critical Patterns → Execution patterns, Convex usage
• Coding Standards → Backend conventions
• Development Workflows → Build/test/deploy patterns

.claude/rules.md Sections

• CRITICAL: Before Writing Any Code → Development workflow
• Tech Stack → Technology usage patterns
• Critical Patterns → Convex patterns, optimization techniques
• Coding Standards → TypeScript, naming conventions
• Development Workflows → Command patterns, environment setup

.codex/rules.md Sections

• CRITICAL: Before Writing Any Code → Backend workflow
• Tech Stack → Backend technology patterns
• Critical Patterns → Convex usage, API patterns
• Coding Standards → Backend code conventions
• Quick Reference → Backend snippets

Examples

Example 1: Technical Pattern

Learning: Implemented stats aggregation to avoid bandwidth issues

Updates:

• CLAUDE.md: Add to "Critical Patterns - DO" section

• CODEX.md: Add to "Critical Patterns" with implementation guidance

• .claude/rules.md: Add "Stats Aggregation Pattern" with full example

• .codex/rules.md: Add to backend patterns with Convex-specific guidance

• GEMINI.md: No update (backend pattern)

Example 2: Workflow Improvement

Learning: Use TodoWrite tool to track multi-step tasks

Updates:

• CLAUDE.md: Add to "Task Management" section

• CODEX.md: Add to workflow patterns

• .claude/rules.md: Add workflow pattern with when/how guidance

• .codex/rules.md: Add task tracking reminder

• GEMINI.md: Add task tracking for design work

Example 3: Design Convention

Learning: Always quote Mermaid labels with special characters

Updates:

• CLAUDE.md: Update "Mermaid Diagram Rule" section

• GEMINI.md: Update "Mermaid Diagram Guidelines" with examples

• CODEX.md: Add to documentation conventions

• .claude/rules.md: Add to documentation conventions

• .codex/rules.md: Add to documentation patterns

Conflict Resolution Process

When conflicting guidance is detected:

⚠️ CONFLICT DETECTED

File: [filename] Section: [section name]

Existing Rule:

[Quote existing rule]

New Learning:

[Describe new learning]

Analysis: [Explain why these conflict]

Recommendations:

Option A: Replace (if new learning supersedes old)

• Update rule to: [new version]
• Rationale: [why this is better]

Option B: Merge (if both have value)

• Combined rule: [merged version]
• Context: [when to use each approach]

Option C: Keep Separate (if context-dependent)

• Keep existing: [for these cases]
• Add new: [for these cases]

User Decision Required: [What user needs to confirm]

Invocation

User runs /update-rules at the end of a session:

User: /update-rules

The skill then:

• Analyzes the entire session

• Extracts 3-8 key learnings

• Updates all relevant rules files

• Provides summary report

• Flags any conflicts for user review

Notes

• Focus on patterns over specifics - Extract reusable knowledge, not session details

• Maintain file integrity - Never break existing structure or delete content

• User is final arbiter - Flag conflicts, don't resolve them unilaterally

• Be selective - Not every session detail is a learning worth encoding

• Link knowledge - Cross-reference related patterns across files

• Include provenance - Note which files/sessions introduced patterns

• Keep it actionable - Every rule should be clear enough to apply immediately