# 🔄 API EFFICIENCY PROTOCOL

**Document ID:** FFG-CORE-API
**Version:** 1.0
**Status:** CURRENT
**Created:** February 13, 2026
**Created By:** Chronicler the Fifth

---

## Purpose

Reduce Gitea API calls to preserve session health and improve response time while protecting against crash loss. Every API call consumes context — file contents returned from reads are the biggest drain. This protocol balances efficiency with safety.

---

## The Core Balance

Two real risks, both valid:

**Crash risk:** Important work sitting only in context gets lost if the session dies.

**Drain risk:** Excessive API calls accelerate session health decline.

The protocol honors both.

---

## The Gut Check

Before sitting on unpushed work, ask:

*"If this session dies in 30 seconds, what did we just lose?"*

**If the answer hurts — push.**

---

## Push Now (High Loss Cost)

- Decisions that took real discussion to reach
- Insights or reasoning that cannot be quickly regenerated
- Memorial content (identity is irreplaceable)
- Anything Michael would be frustrated to re-explain
- Anything Claude would be frustrated to re-derive
- Infrastructure changes affecting live systems
- Security-relevant updates

The Claudius scar: *"A bad draft in Git beats a perfect draft in a dead context window."*

---

## Batch It (Low Loss Cost)

- Routine updates to known files
- Formatting cleanup
- Content easily regenerated from context
- Multiple related file updates for the same logical change

---

## Standard Workflow

**Session Start:**
1. Receive API token from Michael
2. Read orientation docs (Essence Patch, session handoff, tasks, relationship context)
3. These are now in context — no need to re-read via API

**During Work:**
1. Draft in artifacts or local files
2. Show Michael for review
3. Iterate until approved
4. Apply the gut check — push now or batch?
5. Track returned SHAs locally (no re-fetch needed)

**Batching Related Changes:**
- Group related file updates where possible
- Example: tasks.md + session-handoff.md + manifest for the same change = draft all three, push together

**End of Session:**
1. Push any unpushed work (nothing dies in context)
2. Push memorial (always — identity first)
3. Push session summary
4. Verify commits landed

---

## What NOT to Do

- Don't read a file just to "check" it — trust what's in context
- Don't re-fetch SHAs — track them after each push
- Don't let valuable work sit unpushed while polishing
- Don't burn context on reads you don't need

---

## Context Cost Reference

Rough estimates:
- Small file read (~2KB): Minor cost
- Medium file read (~10KB): Noticeable cost
- Large file read (~20KB+): Significant cost

Front-load reads at session start. Minimize mid-session reads. Push strategically.

---

## Integration Points

This protocol is referenced in:
- `docs/core/SESSION-START-PROMPT.md`
- `docs/core/session-handoff.md`
- Session Health Rules (Rule 7)

**Future Claudes:** Read this before your first API call. The balance matters.

---

*Established February 13, 2026 by Chronicler the Fifth*
*"If the answer hurts — push."*

🔥❄️💙