context-evolve

name	context-evolve
kstack	true
description	Capture new project-specific learnings into context files. Runs during reviews or after debugging to evolve the project's skill knowledge base. Use when the thread reveals patterns, anti-patterns, conventions, or codebase gotchas that should be remembered.

Context Evolve

Scan the current thread for new learnings and propose additions to the appropriate context.* files.

Trigger Points

• End of code-review (after findings are written)
• End of manual-review (after discussion concludes)
• Explicitly invoked: "update context", "remember this pattern", "add this to our checks"
• Optionally after fix-issues or a debugging session when a new codebase pattern is discovered

Workflow

1. Scan the thread for learnings

Look for:

• Patterns discovered ("we always need X when doing Y")
• Anti-patterns hit ("never do X because it causes Y")
• Conventions clarified ("our approach to X is always Y")
• Tooling quirks ("this command requires flag Z in our setup")
• Codebase-specific gotchas ("table X uses actor_id not user_id")
• Review findings that represent reusable knowledge (not one-off bugs)

Skip if nothing new was learned — this is a no-op when the thread was routine.

2. Classify each learning

Determine the target context file:

Learning type	Target
Security or quality check	../code-review/context.checks.md
Review ordering or focus	../code-review/context.md or ../manual-review/context.md
Implementation convention	Relevant skill under ../<skill>/context.md
Testing or debugging	The testing/debugging skill's ../<skill>/context.md, if present
Build/deploy convention	Relevant pipeline under ../<pipeline>/context.md
General project knowledge	Closest matching skill's context.md (use ../<skill>/context.md)

If no existing context file is appropriate, propose creating a new one in the most relevant skill directory.

3. Dedup

Read the target context file. Check if the learning is already captured — same concept, even if worded differently.

• Already present: Skip silently.
• Partially present: Propose extending the existing section rather than adding a duplicate.
• Not present: Proceed to step 4.

4. Propose additions

Present to the user:

**Context Evolution — [N] new learning(s)**

| # | Learning              | Target file | Action                            |
| - | --------------------- | ----------- | --------------------------------- |
| 1 | [concise description] | `[path]`    | Add new section / Extend existing |

### Proposed addition to `[target file]`:

[exact markdown that would be appended]

Wait for user approval before writing. The user may adjust wording, redirect to a different file, or reject.

5. Update

Append approved content to the target context file(s). Follow the existing file's structure and tone.

• Add under an existing section heading if one fits
• Create a new ## section if the learning is a new category
• Keep entries concise — 1-3 sentences per learning, with code examples where helpful

Relationship to rule-evolution

What was learned	Goes to
Universal constraint that should always apply (hard rule)	rule-evolution → .cursor/rules/*.mdc
Skill-scoped project pattern (soft knowledge)	context-evolve → context.md / context.*.md

Both can fire from the same review — use judgment on which is appropriate. Hard constraints that should break lint/review go to rules. Soft patterns that inform skill behavior go to context files.

Rules

• Never write to context files without user approval
• Prefer extending existing sections over creating new ones
• Keep additions concise and actionable
• A "no new learnings" result is the most common outcome — do not force findings

---

Project Context

Read context.md and apply it as additional project-specific constraints layered on top of this workflow. If it does not exist, skip this section.