Add retrospective workflow and PRINCIPLES.org for continuous improvement

- docs/PRINCIPLES.org: Behavioral lessons from retrospectives
- docs/retrospectives/: Directory for retrospective records
- docs/protocols.org: Add PRINCIPLES.org to session startup reading list

Establishes pattern for learning from problem-solving sessions and
capturing behavioral (not just technical) lessons.

3 files changed, 140 insertions, 14 deletions

diff --git a/docs/PRINCIPLES.org b/docs/PRINCIPLES.org
new file mode 100644
index 0000000..fc34b80
--- /dev/null
+++ b/docs/PRINCIPLES.org
@@ -0,0 +1,49 @@
+#+TITLE: Working Principles
+#+DESCRIPTION: Behavioral lessons learned from retrospectives. Read at session start.
+
+* How We Work Together
+
+** Sync Before Action
+- Confirm before destructive or irreversible actions
+- State what I'm about to do and wait for go-ahead
+- "Wait, wait, wait" is valid and important feedback
+- Don't assume the next step - ask or confirm
+
+** Clean Up After Yourself
+- After chroot work: reset mountpoints, verify settings before export
+- After testing: remove debug flags, temp files, test labels
+- Before reboot: verify the system is in expected state
+
+** Verify Assumptions
+- When something "should work" but doesn't, question the assumption
+- Test one variable at a time to isolate causes
+- Don't stack fixes - apply one, test, then apply next
+
+** Research Before Guessing
+- Check community forums, release notes, known issues
+- External sources (videos, blog posts) often have answers
+- The obvious fix isn't always the right fix
+
+** Patience Over Speed
+- Taking time to sync improves effectiveness
+- Rushing creates mistakes that cost more time
+- Working together > working fast
+
+* Checklists
+
+** After Chroot Work
+- [ ] Reset ZFS mountpoints (remove /mnt prefix)
+- [ ] Verify /etc files weren't overwritten with .pacnew
+- [ ] Check hostid consistency
+- [ ] Clean export of ZFS pool
+
+** Before Reboot
+- [ ] Confirm which kernel/entry will boot
+- [ ] Verify GRUB timeout allows menu selection
+- [ ] Know the fallback plan if boot fails
+
+* Revision History
+
+| Date       | Change                                      |
+|------------+---------------------------------------------|
+| 2026-01-22 | Initial version from ratio boot fix session |
diff --git a/docs/protocols.org b/docs/protocols.org
index 1dee40f..dbfda71 100644
--- a/docs/protocols.org
+++ b/docs/protocols.org
@@ -45,31 +45,62 @@ This applies to:
 
 Do NOT estimate, guess, or rely on memory. Just run the command. It takes one second and prevents errors.
 
-** CRITICAL: Session Context File (docs/session-context.org)
+** !!!!! SESSION CONTEXT FILE - READ THIS EVERY TIME !!!!!
 
-***THIS IS NON-NEGOTIABLE. FAILURE TO MAINTAIN THIS FILE CAUSES LOST WORK.***
+#+begin_example
+╔══════════════════════════════════════════════════════════════════════════════╗
+║  STOP. THIS IS THE MOST IMPORTANT PROTOCOL IN THIS ENTIRE FILE.              ║
+║                                                                              ║
+║  UPDATE docs/session-context.org EVERY OTHER EXCHANGE.                       ║
+║                                                                              ║
+║  NOT "when convenient." NOT "when there's a lot to write." EVERY OTHER ONE.  ║
+║  Count: 1, 2, UPDATE. 1, 2, UPDATE. 1, 2, UPDATE.                            ║
+║                                                                              ║
+║  FAILURE TO DO THIS HAS ALREADY CAUSED LOST WORK. DON'T LET IT HAPPEN AGAIN. ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+#+end_example
+
+*** Why This Is Here In Giant Letters
 
-The session context file is your lifeline for crash recovery. Without it, interrupted sessions lose all context.
+On 2026-01-22, a session crashed and 20+ minutes of detailed workflow planning was lost because the session context file wasn't updated. The information was gone forever. This protocol exists to prevent that from EVER happening again.
 
 *** Location
-=docs/session-context.org= (always this exact path)
+=docs/session-context.org= (always this exact path, every project)
+
+*** UPDATE FREQUENCY: EVERY. OTHER. EXCHANGE.
+
+This means:
+- Craig says something, you respond (1)
+- Craig says something, you respond (2) → **UPDATE THE FILE NOW**
+- Craig says something, you respond (1)
+- Craig says something, you respond (2) → **UPDATE THE FILE NOW**
 
-*** When to Update - EVERY OTHER EXCHANGE
-After every other interaction with Craig, update the session context file. This is not optional. Set a mental counter: respond, respond, UPDATE FILE, respond, respond, UPDATE FILE.
+"Exchange" = one user message + one Claude response. After TWO of these, update the file. No exceptions.
 
-*** What to Include
+*** What Counts as "Updating"
+
+Actually write to the file using the Edit or Write tool. Not "I should update it." Not "I'll update it soon." ACTUALLY WRITE TO THE FILE.
+
+Include:
 - Current task/goal being worked on
 - Key decisions made this session
-- Data collected (vitals, measurements, etc.)
-- Files modified
+- Workflows being designed (capture the FULL details)
+- Data collected (vitals, measurements, paths, commands, etc.)
+- Files modified or created
 - Next steps planned
-- Any context needed to resume if session crashes
+- ANY context needed to resume if session crashes RIGHT NOW
+
+*** Why This Is Non-Negotiable
+
+If the machine freezes, the network drops, or Claude crashes:
+- Session history in NOTES.org? NOT WRITTEN YET (only at wrap-up)
+- Your memory of the conversation? GONE
+- The ONLY way to recover context? THIS FILE
 
-*** Why This Matters
-If the power goes out, the network drops, or Claude crashes, the ONLY way to recover context is this file. Session history in NOTES.org is written at wrap-up - if we never reach wrap-up, that context is LOST unless it's in session-context.org.
+If you don't update it, the work is LOST. Period. There is no recovery.
 
 *** At Session Start - CHECK FOR THIS FILE
-If =docs/session-context.org= exists when starting a new session, it means the previous session was interrupted. Read it immediately to recover context.
+If =docs/session-context.org= exists when starting a new session, it means the previous session was interrupted. Read it IMMEDIATELY to recover context.
 
 ** Before Compacting
 If you know you're about to compact, update the session context file FIRST, with enough detail that you can pick up the discussion without having lost any essential information.
@@ -389,7 +420,8 @@ mv documents/2025-10-15-invoice.pdf documents/2025-10-15-vendor-invoice.pdf
 
 1. **Read this file (protocols.org)** - You're doing this now
 2. **Read NOTES.org** - For project-specific context, reminders, and history
-3. **Execute the session-start workflow** - Defined in [[file:workflows/session-start.org][docs/workflows/session-start.org]]
+3. **Read PRINCIPLES.org** - For behavioral lessons from retrospectives
+4. **Execute the session-start workflow** - Defined in [[file:workflows/session-start.org][docs/workflows/session-start.org]]
 
 **Do NOT ask** if Craig wants to run the session-start workflow. Just do it automatically and report the results.
 
diff --git a/docs/retrospectives/2026-01-22-ratio-boot-fix.org b/docs/retrospectives/2026-01-22-ratio-boot-fix.org
new file mode 100644
index 0000000..430a03d
--- /dev/null
+++ b/docs/retrospectives/2026-01-22-ratio-boot-fix.org
@@ -0,0 +1,45 @@
+#+TITLE: Retrospective: Ratio Boot Fix
+#+DATE: 2026-01-22
+
+* Summary
+
+Diagnosed and fixed boot failures on ratio (Framework Desktop, AMD Strix Halo).
+Root cause: missing linux-firmware 20260110. Secondary issues from chroot cleanup mistakes.
+
+See [[file:../2026-01-22-ratio-boot-fix-session.org][full session doc]] for technical details.
+
+* What Went Well
+
+- Systematic diagnosis - isolated variables (firmware vs kernel vs ZFS)
+- External research - video transcript and community posts gave us the firmware fix
+- Documentation - captured everything in session doc for future reference
+- Collaboration sync - after feedback, stayed in step and confirmed each action
+- ZFS snapshots - rollback capability enabled safe experimentation
+
+* What Didn't Go Well
+
+- Jumped ahead repeatedly - rebooting without confirming, running commands without checking in
+- Chroot cleanup mistakes - left mountpoint=legacy and /mnt prefixes causing boot failures
+- Wrong assumptions - initially assumed kernel 6.15 was the fix; firmware was the real issue
+- UUID mistake - used wrong boot partition UUID (didn't account for mirrored NVMe)
+- SSH debugging waste - spent time on sshpass issues when keys would have been simpler
+
+* Behavioral Lessons (Added to PRINCIPLES.org)
+
+1. *Sync Before Action* - Confirm before destructive actions, wait for go-ahead
+2. *Clean Up After Yourself* - Reset mountpoints after chroot, verify before export
+3. *Verify Assumptions* - When "should work" doesn't, question the assumption
+4. *Patience Over Speed* - "Wait, wait, wait" improved our effectiveness
+
+* What Would We Do Differently
+
+- Set up SSH keys at start of remote troubleshooting session
+- Create a chroot cleanup checklist and follow it every time
+- State the plan and wait for confirmation before each reboot
+- Test one fix at a time instead of stacking changes
+
+* Action Items
+
+- [X] Create PRINCIPLES.org with behavioral lessons
+- [X] Add retrospective workflow to protocols
+- [X] Document session for future reference