OpenWriterControle/.opencode/context/core/context-system/operations/update.md

Update Operation

Purpose: Update context when APIs, frameworks, or contracts change

Last Updated: 2026-01-06

---

When to Use

• Framework version updates (Next.js 14 → 15)
• API changes (breaking changes, deprecations)
• New features added to existing topics
• Migration guides needed

---

8-Stage Workflow

Stage 1: Identify Changes (APPROVAL REQUIRED)

Action: User describes what changed

Format:

What changed in {topic}?
  [A] API changes
  [B] Deprecations
  [C] New features
  [D] Breaking changes
  [E] Other (describe)

Select all that apply (A B C D or describe):

Follow-up: Get specific details for each selected type

Validation: MUST get user input before proceeding

---

Stage 2: Find Affected Files

Action: Search for files referencing the topic

Process:

1. Grep for topic references across all context
2. Count references per file
3. Show impact analysis

Format:

Found 5 files referencing {topic}:
  📄 concepts/routing.md (3 references, 145 lines)
  📄 examples/app-router-example.md (7 references, 78 lines)
  📄 guides/setting-up-nextjs.md (2 references, 132 lines)
  📄 errors/nextjs-errors.md (1 reference, 98 lines)
  📄 lookup/nextjs-commands.md (4 references, 54 lines)

Total impact: 17 references across 5 files

---

Stage 3: Preview Changes (APPROVAL REQUIRED)

Action: Show line-by-line diff for each file

Format:

Proposed updates:

━━━ concepts/routing.md ━━━

Line 15:
  - App router is optional (use pages/ or app/)
  + App router is now default in Next.js 15 (pages/ still supported)

Line 42:
  + ## Metadata API (New in v15)
  + Next.js 15 introduces new metadata API...

━━━ examples/app-router-example.md ━━━

Line 8:
  - // Optional: use app router
  + // Default in Next.js 15+

Preview next file? (yes/no/show-all)
Approve changes? (yes/no/edit):

Edit mode: Line-by-line approval for each change

Validation: MUST get approval before proceeding

---

Stage 4: Backup

Action: Create backup before updating

Location: .tmp/backup/update-{topic}-{timestamp}/

Purpose: Enable rollback if updates cause issues

---

Stage 5: Update Files

Action: Apply approved changes

Process:

1. Update concepts, examples, guides, lookups
2. Maintain MVI format (<200 lines)
3. Update "Last Updated" dates
4. Preserve file structure

Enforcement: @critical_rules.mvi_strict

---

Stage 6: Add Migration Notes

Action: Add migration guide to errors/

Format:

## Migration: {Old Version} → {New Version}

**Breaking Changes**:
- Change 1
- Change 2

**Migration Steps**:
1. Step 1
2. Step 2

**Reference**: [Link to changelog]

Location: {category}/errors/{topic}-errors.md

---

Stage 7: Validate

Action: Check all references and links

Checks:

• All internal references still work
• No broken links
• All files still <200 lines
• MVI format maintained

---

Stage 8: Report

Action: Show comprehensive results

Format:

✅ Updated X files
📝 Modified Y references
🔄 Added migration notes to errors/
💾 Backup: .tmp/backup/update-{topic}-{timestamp}/

Summary of changes:
  - concepts/routing.md: 2 updates (145 → 162 lines)
  - examples/app-router-example.md: 4 updates (78 → 89 lines)
  - guides/setting-up-nextjs.md: 1 update (132 → 133 lines)

All files still under 200 line limit ✓

Rollback available if needed.

---

Change Types

API Changes

• Method signatures changed
• Parameters added/removed
• Return types changed

Deprecations

• Features marked deprecated
• Replacement APIs available
• Timeline for removal

New Features

• New capabilities added
• New APIs introduced
• New patterns available

Breaking Changes

• Incompatible changes
• Migration required
• Old code won't work

---

Examples

Framework Update

/context update for Next.js 15
/context update for React 19

API Changes

/context update for Stripe API v2024
/context update for OpenAI API breaking changes

Library Update

/context update for Tailwind CSS v4

---

Success Criteria

• User described changes?
• All affected files found?
• Diff preview shown?
• User approved changes?
• Backup created?
• Migration notes added?
• All references validated?
• All files still <200 lines?

---

Related

• guides/workflows.md - Interactive diff examples
• standards/mvi.md - Maintain MVI format
• operations/error.md - Adding migration notes