/learning-harvest

name: learning-harvest
description: "Manage the operational learnings lifecycle — load prior learnings to inform current work, harvest new patterns worth preserving, and keep the document tight over time. Provides a protocol for accumulating actionable patterns from practice that complement standards and defaults. Use when a workflow session completes and produced insights worth persisting, when starting a session that should benefit from prior patterns, or when the user says 'harvest learnings', 'what have we learned', 'capture this pattern', 'tighten learnings', 'compress learnings', or 'operational learnings'."

Learning Harvest

Scope Boundary

Operational learnings are NOT rules. They are what you learn while applying rules.

| Standards (refiner output, atom defaults) | Operational Learnings (this document) | |---|---| | "Domain layer must not import from infrastructure" | "When adding a new aggregate, we keep forgetting to define the repository interface first — design interface before implementation" | | "Functions should have single responsibility" | "Service classes that start small grow past 500 lines within 3 features — split by command type proactively at ~200 lines" | | "Value objects must validate in constructor" | "Date range VOs without explicit inclusive/exclusive documentation cause boundary bugs every time — document semantics alongside validation" |

**The standard is the rule. The operational learning is what we discovered while applying the rule on this project.**

If an entry reads like a rule that should always be followed, it belongs in a standards document (run the relevant refiner). If it reads like "here's what we keep learning the hard way" or "here's an approach that keeps working for us" — it belongs here.

Patterns that recur frequently may graduate to standards via a refiner. That promotion path is part of the Tighten behavior.

Config Resolution

1. Check `.lattice/config.yaml` for `paths.operational_learnings`. 2. If set and the file exists at that path → use it. 3. If set but no file exists there → tell the user which configured path is missing, then use the default `.lattice/learnings/operational-learnings.md`. 4. If not set → use the default `.lattice/learnings/operational-learnings.md`.

**Backward compatibility**: If default path not found, check these legacy paths in order:

• `.lattice/learnings.md` — flat file at root
• `.lattice/learnings/review-insights.md` — prior naming convention

If found, offer migration to canonical path and format. If user declines, read as flat input. **STOP: do not write to it.**

Document Structure

# Operational Learnings

Experiential patterns from practice. Complements standards (what should be) with experience (what we keep learning).

## Design Patterns
<!-- Decomposition, architecture choices, scope decisions that proved good or bad -->

## Implementation Craft
<!-- Coding approaches, library gotchas, design-to-reality gaps -->

## Quality Signals
<!-- Recurring quality issues that keep appearing despite rules -->

## Reliability
<!-- Bug root causes, failure modes, fragile areas, boundary condition gaps -->

## Structural Health
<!-- Architectural drift, debt accumulation, coupling issues, migration lessons -->

**Entry format**: `- YYYY-MM-DD [context] Pattern — actionable takeaway`

• `context`: type of session (e.g., "design", "implementation", "review", "bug fix", "refactoring"). Not a feature name — learnings are cross-cutting.
• Each entry ONE bullet, max 2 lines, scannable in under 10 seconds. **STOP: keep to two lines even when existing entries are longer — do not copy their length or shape.**

Load Behavior

Invoked at session start. Composing workflow passes a **focus hint** (relevant categories).

1. Resolve file path per Config Resolution. 2. If file not found — "No operational learnings yet." Continue. Non-blocking. 3. If found — surface relevant entries (3-5 most recent from matching categories) as brief context. Treat as soft guidance, not hard constraints.

**Active monitoring**: Once loaded, maintain a **silent harvest queue** throughout the session. When a decision or trade-off passes the cross-cutting test below, add it to the queue. **STOP: do not prompt immediately.**

**Cross-cutting test** — a candidate must pass BOTH before queuing: 1. It names a pattern or approach, not a feature-specific fact. 2. A developer on a completely different feature could apply it without knowing this feature's context.

**STOP: if either fails, skip entirely — do not queue.**

Before queuing, check against entries loaded at session start. If the same pattern already exists — skip.

**When to surface:** Surface the queue as a single batch when EITHER condition is true — not at every level or layer:

• Queue reaches 3 candidates, OR
• A major phase completes (all design levels done, a full implementation layer done)

**STOP: do not surface at every individual level approval or component completion** — that is over-prompting. Once surfaced, clear the queue. Anything remaining at session end goes to Harvest.

> "I noted [N] potential harvest candidates — worth a quick review?"

**Mid-session interrupt** (rare exception): surface a single pattern immediately, outside the queue, only when it would be impossible to reconstruct by session end — a live debate that resolved unexpectedly, a library gotcha caught mid-implementation. If in doubt, queue instead.

Session-end Harvest is the primary mechanism.

Harvest Behavior

Invoked at session end. Composing workflow passes a **session context** (what kind of work happened).

**Governing principle: STOP: the atom never writes autonomously.** Session-end Harvest is the primary capture event — mid-session prompting is the exception.

**Steps**:

1. **Drain the queue.** Collect all candidates from active monitoring queue plus any new ones surfaced by reviewing session decisions and outcomes. Each candidate must have passed the cross-c