---
name: lfo-lessons-write
description: Invoke at orchestrator session close (won/lost/withdrawn/post-submit). Scans session log for fired gap-watch rules + Rocky-flagged misses + override patterns + contradictions Rocky resolved. Appends per-session entries to `_Internal/lessons-learned/{date}-{slug}.md` (append-only) AND a sibling action-rule distillation to `C:\Users\mclou\lfcs-lessons-learned\lesson-{date}-{slug}.md` for cross-agent portability. Updates `standards/gaps-pattern-library.md` if a new pattern is sufficiently general (Rocky-confirmed before merge).
model: claude-sonnet-4-6
phase: 7
invoked_by: orchestrator at session close (won/lost/withdrawn/post-submit)
preconditions:
  - orchestrator session log complete
  - any methodology proposals already in proposals-pending.md
inputs:
  - session_id
  - session log full text
  - any Rocky-flagged misses during session (free-text)
outputs:
  - new entry in `_Internal/lessons-learned/{date}-{slug}.md`
  - optional update to `standards/gaps-pattern-library.md` (Rocky-confirmed before merge)
  - one-liner appended to `_Brain/_Log.md`
side_effects:
  - closes session log with footer
  - never deletes/edits prior lessons (append-only)
authored_by: claude-code-orchestrator
created: 2026-05-08
---

# lfo-lessons-write

Capture lessons from a closing orchestrator session. Same shape as `_Internal/2630-gaps-log.md` per-entry format.

## Procedure

1. **Re-scan session log.** Find:
   - Every gap-watch rule that fired (under `## Gap-watch fires`)
   - Every Rocky-flagged miss (free-text Rocky said "we should have caught X")
   - Every override that revealed a methodology pattern (cross-reference proposals-pending.md)
   - Every contradiction Rocky resolved (Q-2 vs drawing-spec, Q-1 vs scope-email, etc.)

2. **For each lesson, draft entry. Format:**
   ```markdown
   ## {YYYY-MM-DD} — {short title}

   **Missed:** {what the orchestrator OR worker missed and how it manifested in output}

   **Flagged:** {who flagged + when + what they said}

   **Root cause hypothesis:** {why the miss happened — methodology gap, CLAUDE.md rule gap, gap-pattern-library gap, intake-gate gap, standing-context gap, or operational discipline gap}

   **Suggested CLAUDE.md fix area:** {file + section to update}

   **Suggested methodology fix:** {proposed Rate Template / Standard Exclusion / Common Misses Pattern adjustment}

   **Status:** {captured-pending-Rocky-review | merged-into-library | rejected-after-review | superseded}

   ---
   ```

3. **Choose target file path:** `_Internal/lessons-learned/{YYYY-MM-DD}-{job_no}-{slug}.md`. Slug = short kebab-case lesson title (e.g. `2026-05-08-2630-four-gaps.md`, `2026-05-15-2631-rate-only-not-flagged.md`).

4. **Write entry.** Append-only. If file exists, append to bottom. If new file, write frontmatter:
   ```yaml
   ---
   job_no: {job}
   purpose: Lessons-learned entries from orchestrator session {session_id}
   authored_by: claude-code-orchestrator
   created: {YYYY-MM-DD}
   append_only: true
   ---
   ```

5. **Pattern library candidates.** For each lesson where the root cause is a gap-watch-rule gap (a real-world miss the existing G1–G5 didn't catch):
   - Draft new pattern G{N+1} per format at bottom of `gaps-pattern-library.md`
   - Add to `_Internal/lessons-learned/proposals-pending.md` under heading `## Gap-watch pattern proposals`
   - Surface batch to Rocky with: "These N pattern proposals are pending. Accept / reject / modify."
   - On Rocky-accept: append to `gaps-pattern-library.md` at bottom (append-only).

6. **One-liner to `_Brain/_Log.md`.** Per AI Team Protocol:
   ```
   2026-05-15 :: claude-code-orchestrator :: 2631 session closed — 3 lessons written, 2 G-rule proposals queued, 5 methodology proposals queued.
   ```

7. **Close session log.** Append footer:
   ```yaml
   ## Session footer
   ended_at: {timestamp}
   lessons_written: 3
   gap_rule_proposals_queued: 2
   methodology_proposals_queued: 5
   final_session_status: {complete|aborted-breach|aborted-other}
   ```

## Failure modes

- Session log incomplete (interrupted mid-phase): write what's there + flag in footer. Don't fabricate.
- Rocky has not flagged any miss explicitly: still scan for fired-but-uncategorised rules. If none, write a "no-lessons" entry confirming the bid ran clean (still useful as evidence the orchestrator+worker pair delivered without correction).
- A "lesson" turns out to be a false positive (gap-watch rule fired but the prompt was actually correct): document as `false-positive` + tune the predicate in `gaps-pattern-library.md` (Rocky-confirmed update).

## Output schema (per-entry)

Same as `_Internal/2630-gaps-log.md` entry shape. Maintain consistency so the lessons-learned directory + the original 2630-gaps-log read as one continuous canon.

## Reference — when to write a lesson (canonical criteria)

Shared lessons folder: `C:\Users\mclou\lfcs-lessons-learned\`. Both `lfcs-pricing` and `lfcs-orchestrator` read AND write. Cowork reads read-only.

**Trigger to write a new lesson** (any one):
- Rocky flags something an agent missed
- A pattern repeats across 2+ bids (not a one-off)
- A decision should be a default next time
- A push-back caught a real error
- A scope or rate convention changes (locked by Rocky)

**File format:** `lesson-{YYYY-MM-DD}-{short-name}.md` — kebab-case short name (e.g. `lesson-2026-05-08-labour-rate.md`).

**Content structure** (short, plain English, no fluff):
- **What happened** — concrete 1–3 sentences. Quote Rocky verbatim where possible.
- **Why it matters** — failure mode + magnitude (cost / scope / time / accuracy impact).
- **What to do next time** — explicit rule the next agent session must apply.

**Do NOT write a lesson for:** one-off typos, file-naming preferences, ambiguity that resolves itself within a session, internal agent reasoning errors that didn't affect output. Lessons are for cross-session learning, not session-internal corrections.

**Cross-link discipline:** when this skill (Phase 7) writes the per-session entry to `_Internal/lessons-learned/{date}-{job}-{slug}.md`, ALSO write a sibling shared lesson to `C:\Users\mclou\lfcs-lessons-learned\lesson-{date}-{slug}.md` if the lesson is portable across both agents (most lessons are). Vault-internal `_Internal/lessons-learned/` keeps the full session reference + proposals queue; shared folder gets the action-rule distillation Cowork can read.

After writing: append a one-liner to `_Brain/_Log.md` per AI Team Protocol.