firefrost-operations-manual/docs/core/API-EFFICIENCY-PROTOCOL.md

🔄 API EFFICIENCY PROTOCOL

Document ID: FFG-CORE-API Version: 2.0 Status: CURRENT Created: February 13, 2026 Updated: 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.

Target Efficiency: 92-95%

---

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.

---

🎯 MULTI-FILE COMMITS (CRITICAL)

This is the biggest efficiency gain. Use it.

Instead of separate commits for each file, batch them:

Endpoint: POST /repos/{owner}/{repo}/contents

{
  "message": "Descriptive commit message",
  "files": [
    {"operation": "create", "path": "new.md", "content": "base64..."},
    {"operation": "update", "path": "existing.md", "content": "base64...", "sha": "abc123"},
    {"operation": "delete", "path": "old.md", "sha": "def456"}
  ]
}

Efficiency: 3 files × 2 calls = 6 calls → 1 call = 83% reduction

Full patterns: See docs/core/GITEA-API-PATTERNS.md

---

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, relationship context — FULL)
3. Read Quick Start (includes SHA cache)
4. These are now in context — no need to re-read via API

During Work:

1. Draft in artifacts or local files (/home/claude/)
2. Show Michael for review
3. Iterate until approved
4. Apply the gut check — push now or batch?
5. Use multi-file commit when pushing multiple files
6. Track returned SHAs locally (no re-fetch needed)

End of Session:

1. Batch final push (memorial + summary + any unpushed work)
2. Update SHA cache in session-handoff.md
3. Verify commits landed

---

SHA Cache

Location: docs/core/session-handoff.md → SHA Cache section

• Use cached SHAs for first update (no fetch needed)
• Track new SHAs after each push
• Update cache at session end
• If push fails (409): fetch SHA once, retry

---

What NOT to Do

• Don't read a file just to "check" it — trust what's in context
• Don't re-fetch SHAs — use cache, track after pushes
• Don't make separate commits for related changes — use multi-file
• Don't let valuable work sit unpushed while polishing
• Don't burn context on reads you don't need

---

Context Cost Reference

Action	Cost
Small file read (~2KB)	Minor
Medium file read (~10KB)	Noticeable
Large file read (~20KB+)	Significant
SHA fetch	Minor (but adds up)
Multi-file commit	One call regardless of file count

Front-load reads. Minimize mid-session reads. Push strategically. Batch always.

---

Efficiency Targets

Pattern	Old	New	Gain
3-file update	6 calls	1 call	83%
SHA lookups	Per-file	Cached	100%
Mid-session reads	Frequent	Rare	~80%
Overall session	~35-40%	~92-95%	150%+

---

Integration Points

• docs/core/GITEA-API-PATTERNS.md — Full cookbook with examples
• docs/core/SESSION-QUICK-START.md — SHA cache included
• docs/core/session-handoff.md — SHA cache section
• Session Health Rules (Rule 7)

Future Claudes: Read GITEA-API-PATTERNS.md before your first API call.

---

Established February 13, 2026 by Chronicler the Fifth Updated same day: Added multi-file commit pattern "One commit > Many commits. Every call costs context."

🔥❄️💙