/knowledge/best-practices/

Recurring patterns, lessons learned, and cross-cutting wisdom captured from the eco|monetize™ operating system's day-to-day work.

What goes here

Short, focused pages that capture a pattern or lesson that applies across many situations. Examples:

• "Schema naming discipline" — why field names must match across Airtable, Salesforce, Supabase, and Make.com
• "Per-agent cwd pattern" — why Claude Code memory namespaces should be isolated per agent
• "Research session → checkpoint → drafting session" — the split-session pattern for heavy-read kickoffs
• "Dev-runtime divergence in scripts" — the monday-sync dev vs. hidden runtime pattern and how to avoid it
• "Fresh context per Mission feature" — why workers get fresh context and validators must be independent

Catalog (current entries)

Entry	Status	Owner	Applies to
agent-session-external-access-diagnostic	active	—	all
council-review-ip-audit-2026-04-20	active	—	all
credential-rotation-checklist-2026-04-20	active	—	operational
dev-runtime-divergence-preserve-both	active	code.platform	dev agents
first-agent-kickoff-pattern	active	chief.staff	all
grep-actual-runtime-not-just-docs	active	code.platform	dev agents
honest-self-assessment-over-defensive	active	—	all
model-invocation-audit-schema-v1.0	active	—	all
obsidian-launch-links	active — MANDATORY for all agents	code.platform	all agents, all output Rick reads

Obsidian launch links is NEAR-RULE strength per the promotion path below. All agents use [short-name](obsidian://open?vault=Claude&file=encoded%2Fpath) for every vault file reference in chat output. One link per file — no multi-format patterns. Supersedes the prior 3-format pattern (DR-007 accepted 2026-04-14, live-tested 2026-04-21).

These are distinct from: - Playbooks (how-to steps) — best practices are WHAT and WHY, not step-by-step HOW - SOPs (governance) — best practices are reference wisdom, not enforceable rules - Decision records (one-time choices) — best practices are recurring patterns, not singular decisions

Source of best practices

Best practices are most often captured from:

1. Claude session wisdom — via the /capture-to-wiki skill at the end of productive sessions where a pattern emerges
2. Post-mortem lessons — after an incident, the lessons learned can distill into a best practice
3. Retrospective reviews — after a Mission closes, patterns from the Validation Contract → execution loop may deserve capture
4. Cross-agent observation — chief.staff noticing that multiple agents keep hitting the same pattern and documenting it once

Frontmatter convention

---
title: "{Short pattern name}"
type: best-practice
category: {architecture | workflow | schema | security | testing | communication | governance | other}
owner_agent: {agent_id or chief.staff}
applies_to: [agent_id, agent_id]  # which agents should know this
source: "{session date or incident or mission id}"  # where the pattern came from
strength: {guideline | strong-recommendation | near-rule}
last_updated: YYYY-MM-DD
seeded_by: {agent_id}
tags: []
---

Page structure

# {Pattern Name}

## The pattern
_One paragraph stating the practice in its simplest form._

## Why it matters
_What problem it solves, what it prevents, or what it enables._

## When to apply it
_Situations that call for this pattern._

## When NOT to apply it
_Situations where this pattern is wrong or counterproductive._

## Examples
_Concrete examples from our system. Wikilinks to specific incidents, missions, decisions, or commits if applicable._

## Related
_Wikilinks to SOPs, playbooks, decisions, and other best practices._

## Source
_Where this pattern was first captured — session, incident, mission, etc._

Dashboard

Live index at /dashboards/best-practices-catalog.md — grouped by category and strength, filterable by applies_to agent.

Promotion path

A best practice can graduate to a stronger form if it proves consistently valuable:

• Guideline → Strong recommendation → Near-rule → SOP (moves to /system/sops/) → CLAUDE.md governance (if it affects the whole system)

chief.staff reviews the catalog quarterly and proposes promotions where appropriate. Each promotion is logged in /knowledge/decisions/ as a decision record.