123 lines
3.1 KiB
Markdown
123 lines
3.1 KiB
Markdown
# 🔄 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."*
|
|
|
|
🔥❄️💙
|