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?"

Change Type	Likely Affected Skills
New Effector pattern	effector-patterns
Frontend architecture	frontend-architecture
New port type	port-system, types-architecture
DBOS workflow change	dbos-patterns, executor-architecture
Subscription change	subscription-sync
New node pattern	node-creation, types-architecture

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:

  ### 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

Skill Type	Update Frequency
Foundation (chaingraph-concepts)	Rarely - core concepts stable
Package (*-architecture)	Monthly - as architecture evolves
Technology (*-patterns)	When patterns discovered/deprecated
Feature (port-system, etc.)	When feature area changes significantly
Meta (skill-*)	When skill conventions change

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:

Metric	Healthy	Needs Review
Last updated	< 3 months	> 6 months
Key Files exist	All exist	Files missing
Patterns work	Code compiles	Outdated syntax
Anti-patterns relevant	Still problematic	Fixed in codebase

Related Skills

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