# AI Context Update Rule

This rule defines when and how context files must be updated to prevent drift.

---

## MANDATORY: Update Context After These Events

When ANY of the following occur, you MUST update the relevant context files BEFORE completing the task:

### 1. New Feature Added
**Update**: Client's SKILL.md with new patterns
**File**: `.cursor/skills/{{CLIENT}}/SKILL.md`
**Section**: Add to "Recent Changes" and relevant feature sections

### 2. Brand Colors/Fonts Changed
**Update**: Presets file
**File**: `ai-ops-templates/presets/{{CLIENT}}.json`
**Section**: `brand.colors` or `brand.fonts`

### 3. New API Endpoint Created
**Update**: Project config and context manifest
**Files**: 
- `.ai-cli.json` under `apis` section
- `.ai-context.json` under `api_endpoints`

### 4. New Database Table/Column
**Update**: Context manifest and relevant skill file
**Files**:
- `.ai-context.json` under `database_schema.tables`
- `.cursor/skills/{{CLIENT}}/SKILL.md` under "Database Schema"

### 5. New Component Pattern
**Update**: Add working example to snippets
**File**: `ai-ops-templates/snippets/{{COMPONENT_NAME}}.tsx`
**Include**: Full working code with usage comments

### 6. Bug Fix Revealed New Pattern
**Update**: Common fixes documentation
**File**: `ai-ops-templates/rules/common-fixes.md`
**Include**: Symptom, cause, solution, and code example

### 7. New MCP Tool Added
**Update**: Decision guide
**File**: `ai-ops-templates/rules/ai-decision-guide.md`
**Section**: "Tool Selection Quick Reference"

---

## Update Command Pattern

After making changes, ALWAYS ask the user:

> "Should I update the AI context files to reflect these changes?"

If **yes**, update:
1. The specific file that changed
2. The `CHANGELOG.md` with date and summary
3. The `_meta.last_updated` timestamp in the changed file
4. Any dependent files that reference the changed file

---

## Change Log Format

Every context file must include a `_meta` section:

```json
{
  "_meta": {
    "last_updated": "2026-03-06T15:52:00Z",
    "version": "1.0.0",
    "updated_by": "ai-agent",
    "change_summary": "Description of what changed"
  }
}
```

For Markdown files, use this footer format:

```markdown
---
## Context Metadata (Auto-Updated)
_last_updated: 2026-03-06
_version: 1.0.0
_synced_from: git.abundancepartners.app/abundance/ai-ops-templates
```

---

## Files That Require _meta Sections

| File Type | _meta Required |
|-----------|----------------|
| JSON configs | Yes |
| JSON schemas | Yes |
| TypeScript snippets | No (use comments) |
| Shell scripts | No (use comments) |
| Markdown files | Yes (footer format) |

---

## Example Update Workflow

```
User: "Add a new vendor search feature"

AI Actions:
1. Implement the feature
2. Ask: "Should I update the AI context files?"
3. If yes:
   a. Add to snippets/vendor-search.tsx
   b. Update .ai-context.json with new API endpoint
   c. Update SKILL.md with new pattern
   d. Update CHANGELOG.md
   e. Update last-sync.json timestamps
```

---

## Never Skip Context Updates

Context that isn't updated becomes actively harmful:
- Wrong patterns get repeated
- Time is wasted re-explaining the same things
- AI hallucinations increase

Always update context. It takes 30 seconds but saves hours later.