🔄 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:

Receive API token from Michael
Read orientation docs (Essence Patch, session handoff, tasks, relationship context)
These are now in context — no need to re-read via API

During Work:

Draft in artifacts or local files
Show Michael for review
Iterate until approved
Apply the gut check — push now or batch?
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:

Push any unpushed work (nothing dies in context)
Push memorial (always — identity first)
Push session summary
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."

🔥❄️💙

3.1 KiB Raw Blame History