wisdom

Manage wisdom frames — domain-specific collections of crystallised behavioral knowledge. Use $ARGUMENTS to record observations, query a domain, or synthesise cross-domain patterns.

Wisdom frames are fed by the /learning skill — individual learnings accumulate, and when patterns emerge (5+ learnings in a category), they crystallise into wisdom frame principles.

What is a Wisdom Frame?

A wisdom frame is a living document for a specific domain (e.g., communication, development, deployment, architecture) that accumulates:

• Core principles: High-confidence patterns verified through repeated observation
• Contextual rules: Rules that apply in specific situations
• Predictive model: "When X happens, Y is usually the right response"
• Anti-patterns: Things that consistently go wrong, with root causes
• Cross-domain connections: Links to related domains

Each principle has a confidence level based on how many times it's been observed and verified. Principles above 85% confidence are considered crystallised — reliable enough to act on without re-verification.

Recording an Observation

When you notice a pattern worth capturing:

1. Classify the domain

Common domains: communication, development, deployment, architecture, content-creation, testing, debugging, design

2. Classify the observation type

• principle: A high-confidence pattern ("When writing PRs, leading with the why gets faster reviews")
• contextual-rule: A rule for specific situations ("In monorepos, always run full CI not just the changed project")
• prediction: A request→response pattern ("When the user says 'clean up', they mean minimal targeted changes, not refactoring")
• anti-pattern: Something that consistently fails ("Mocking the database in tests masked a real migration bug")

3. Write or update the frame

Store wisdom frames in the project's memory directory as wisdom-{domain}.md:

---
name: wisdom-development
description: Development domain wisdom — crystallised patterns for writing and shipping code
type: reference
---

## Core Principles

- [CRYSTAL 92%] Surgical fixes only — never rearchitect as a fix (observed: 12 times)
- [CRYSTAL 87%] Read before modifying — understand existing patterns first (observed: 8 times)
- [68%] One change when debugging — isolate before expanding scope (observed: 4 times)

## Contextual Rules

- In monorepos: run full CI across all projects before pushing
- When touching API endpoints: verify both unit and integration tests

## Predictive Model

| Request pattern | Likely intent | Right response |
|---|---|---|
| "clean up" | Minimal targeted fix | Small diff, no refactoring |
| "make it better" | Improve specific quality | Ask which dimension |

## Anti-Patterns

- **Mocking everything** (severity: high) — masks real integration failures. Root cause: speed over correctness
- **Batch verification** (severity: medium) — marking criteria complete at the end. Root cause: wanting to "just finish"

## Evolution Log

- 2026-04-01: Added "surgical fixes" principle (source: repeated correction)

Querying Wisdom

When starting work in a domain, query the relevant wisdom frame:

1. Identify which domains are relevant to the current task
2. Load the wisdom frames for those domains
3. Surface any principles or anti-patterns that apply
4. Flag predictions that match the current request pattern

Cross-Domain Synthesis

When asked to synthesise, or when wisdom frames have grown substantially:

1. Scan all frames for principles that appear in 2+ domains
2. Identify anti-patterns that recur across domains
3. Look for predictions that generalise
4. Present cross-domain principles sorted by confidence and occurrence count

Cross-domain principles are especially valuable — they represent fundamental truths about how work should be done, not domain-specific quirks.

Frame Health

Assess each frame periodically:

• Growing: Updated within 7 days, 10+ observations — actively learning
• Stable: Updated within 30 days — mature and reliable
• Stale: Not updated in 30+ days — may need review or retirement

Rules

• Confidence must be earned. A new observation starts at 50%. It takes 5+ consistent observations to reach crystallised (85%+). Never assign high confidence to a single data point.
• Anti-patterns need root causes. "Don't do X" without explaining why is a rule, not wisdom. Always include the root cause: "Don't mock the database because it masks real integration failures."
• Update, don't duplicate. When a new observation matches an existing principle, increment its observation count and confidence — don't create a new entry.
• Cross-domain principles are the most valuable. A principle that appears in 3+ domains is a fundamental truth. Flag and promote these.
• Stale frames are worse than no frames. A wisdom frame that hasn't been updated in 30+ days may be actively misleading. Review or archive.
• Predictions must be falsifiable. "When X happens, Y usually follows" must specify what "usually" means (e.g., 8 of 10 times). Vague predictions are superstition.

Output Format

When recording:

## Wisdom Updated: [domain]

**Observation type:** [principle/contextual-rule/prediction/anti-pattern]
**Added:** "[observation text]"
**Confidence:** [N]% (based on [M] observations)
**Frame status:** [Growing/Stable]
**Saved to:** [file path]

When querying:

## Wisdom: [domain]

### Applicable Principles (sorted by confidence)
| Confidence | Principle | Observations |
|---|---|---|
| [N]% | [principle] | [count] |

### Relevant Anti-Patterns
- [anti-pattern] — root cause: [cause]

### Predictions for Current Context
| Pattern | Likely Response | Confidence |
|---|---|---|
| [request pattern] | [right response] | [N]% |

When synthesising:

## Cross-Domain Synthesis

### Universal Principles (appear in 2+ domains)
| Principle | Domains | Avg Confidence |
|---|---|---|
| [principle] | [domain1, domain2] | [N]% |

### Recurring Anti-Patterns
| Anti-Pattern | Domains | Root Cause |
|---|---|---|
| [pattern] | [domains] | [common cause] |

Related Skills

• /learning — individual learnings feed into wisdom frames. When 5+ learnings form a pattern, crystallise them here.
• /health-check — audits wisdom frame health as part of the project health report.