Skill Maintenance Guide

This skill helps development agents know when and how to update the ChainGraph skill tree after making codebase changes.

Core Principle: Balanced Updates

Skills should stay current but not churn constantly. Update skills for meaningful changes that affect how future agents should work.

                    ┌─────────────────────────────────────┐
                    │         SKILL UPDATE DECISION       │
                    └─────────────────────────────────────┘
                                     │
                    ┌────────────────┴────────────────┐
                    │                                 │
                    ▼                                 ▼
            ┌──────────────┐                 ┌──────────────┐
            │   UPDATE     │                 │  DON'T UPDATE │
            └──────────────┘                 └──────────────┘
            • New architecture               • Bug fixes
            • New patterns                   • Small features
            • New anti-patterns              • Refactoring
            • API changes                    • Test changes
            • Critical constraints           • Documentation

When to UPDATE Skills

Architectural Changes

• •New store domain added
• •New component pattern established
• •New file organization structure
• •New package added to monorepo

Pattern Discovery

• •Found a better way to do something common
• •Discovered a pattern that should be standard
• •Created a reusable hook/utility worth documenting

Anti-Pattern Discovery

• •Found code that causes bugs/issues
• •Discovered performance problems from certain patterns
• •Identified security concerns

API/Interface Changes

• •tRPC procedure signature changed
• •Store API changed (new events, effects)
• •Decorator API changed
• •DBOS workflow patterns changed

Critical Constraints

• •New rule that MUST be followed
• •Breaking change that affects existing code
• •Deprecation of old patterns

When NOT to Update Skills

Routine Development

• •Bug fixes (unless revealing anti-pattern)
• •Small feature additions
• •Refactoring that doesn't change patterns
• •Test additions/modifications

Documentation Changes

• •README updates
• •Code comments
• •JSDoc additions

Cosmetic Changes

• •Renaming (unless widespread)
• •Code formatting
• •Import reorganization

Work in Progress

• •Experimental features
• •Incomplete implementations
• •Features behind feature flags

How to Update Skills

Step 1: Identify Affected Skills

Ask: "Which skills would an agent need to know about this change?"

Step 2: Determine Update Type

Add Pattern: New recommended way to do something

## Patterns

### New: Using usePortValue hook
Prefer `usePortValue(portKey)` over direct store subscription...

Add Anti-Pattern: New thing to avoid

## Anti-Patterns

### Avoid: Direct $portValues subscription in components
❌ Bad: `useUnit($portValues)` - causes re-render on ANY port change
✅ Good: `usePortValue(portKey)` - subscribes to single port

Update Example: Code example is outdated

// Updated: Now uses ports-v2 API
const value = usePortValue(portKey)

Update File Reference: File moved or renamed

| `src/store/ports-v2/stores.ts` | Port value stores (was ports/stores.ts) |

Deprecate Pattern: Old way is no longer recommended

### Deprecated: Legacy port stores
The `ports/` store is deprecated. Use `ports-v2/` instead.
Migration guide: [link to migration docs]

Step 3: Make Minimal Changes

• •Add new information, don't rewrite everything
• •Keep existing structure
• •Add date/context in comments if helpful:
  markdown

  ### Using CommandController (added after dd543528)
  

Step 4: Verify Consistency

• •Does this change conflict with other skills?
• •Should other skills reference this new pattern?
• •Is the skill still under 500 lines?

Skill Update Checklist

After significant development work, ask:

• • Did I introduce a new pattern that should be documented?
• • Did I discover an anti-pattern that others should avoid?
• • Did I change architecture that affects how agents work?
• • Did I add new files/folders that should be in Key Files?
• • Did I create new constraints that MUST be followed?
• • Did I deprecate something that skills still recommend?

If any are YES, update the relevant skill(s).

Update Frequency Guidelines

Example: When to Update

Scenario: Added new echo detection mechanism

Changes made:

• •Added echo-detection.ts in ports-v2/
• •New 3-step detection: mutation match → staleness → duplicate
• •Added $pendingPortMutations store

Skills to update:

1. •

   optimistic-updates (Primary)

   • •Add section on 3-step echo detection
   • •Document $pendingPortMutations store
   • •Add anti-pattern: forgetting to track mutations
2. •

   frontend-architecture (Reference)

   • •Add echo-detection.ts to Key Files
   • •Mention echo detection in ports-v2 section
3. •

   effector-patterns (Optional)

   • •If the pattern is reusable beyond ports

Scenario: Fixed a bug in array port rendering

Changes made:

• •Fixed race condition in ArrayPort.tsx
• •Added null check

Skills to update: NONE

• •This is a bug fix, not a pattern change
• •Unless: the bug revealed an anti-pattern worth documenting

Scenario: Refactored store structure

Changes made:

• •Renamed ports/ → ports-v2/
• •Migration mode: disabled → dual-write → read-only → full
• •All new code should use ports-v2

Skills to update:

1. •

   frontend-architecture

   • •Update folder structure
   • •Document migration modes
   • •Add deprecation notice for old ports/
2. •

   effector-patterns

   • •Document migration pattern if reusable
3. •

   port-system

   • •Update all references to use ports-v2
   • •Add migration guide section

Commit Message Convention

When updating skills, use clear commit messages:

docs(skills): update effector-patterns with new sample() usage

- Added pattern for combining multiple sources
- Documented anti-pattern for nested samples
- Updated Key Files with new store locations

Skill Health Metrics

Periodically review skills for staleness:

Related Skills

• •skill-authoring - For creating new skills
• •See package-specific skills for what to update in each area