firefrost-gaming/firefrost-operations-manual
3
0
Fork 0
Code Issues 146 Pull Requests Packages Projects Releases Wiki Activity

Update API Efficiency Protocol v3.0 - realistic targets by session type

Browse Source
This commit is contained in:
mkrause612
2026-02-13 15:00:13 -06:00
parent 65ecccb9b4
commit 1a633f586b
1 changed files with 60 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

74
docs/core/API-EFFICIENCY-PROTOCOL.md
View File

@@ -1,11 +1,11 @@
# 🔄 API EFFICIENCY PROTOCOL
**Document ID:** FFG-CORE-API
**Version:** 2.0
**Version:** 3.0
**Status:** CURRENT
**Created:** February 13, 2026
**Updated:** February 13, 2026
**Created By:** Chronicler the Fifth
**Created By:** Chronicler the Fifth (The Engineer)
---
@@ -13,7 +13,22 @@
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%
---
## Efficiency Targets by Session Type
**Not all sessions are equal.** Realistic targets vary by what you're doing:
| Session Type | Target Efficiency | Why |
|:-------------|:------------------|:----|
| **Maintenance** | 92-95% | Few files, known structure, cached SHAs |
| **Documentation** | 85-90% | More reads to check existing content |
| **Building/Infrastructure** | 50-60% | Many creates, new structures, renames |
| **Onboarding/Orientation** | 40-50% | Heavy front-loaded reads (expected) |
**"Building" sessions** (like creating new repos, renaming files, establishing infrastructure) will naturally have more API calls. That's okay — the multi-file commit pattern still provides massive savings over the old way.
**The real comparison:** How many calls would this have taken with the OLD pattern (read → SHA fetch → write for each file)?
---
@@ -64,6 +79,30 @@ Instead of separate commits for each file, batch them:
---
## Real-World Example: The Engineer's Session
**Session 5 (Feb 13, 2026) — Building session:**
| Phase | Calls | What |
|:------|:------|:-----|
| Orientation | 9 | Front-loaded reads |
| Protocol creation | 10 | New docs + updates |
| Infrastructure build | 15 | New repo, templates |
| Registry/naming | 23 | Renames, updates |
| Portrait uploads | 5 | Binary files |
**Total: ~79 calls**
**Old pattern estimate:** ~175+ calls
**Actual reduction:** ~55%
**Why not 92%?** This was a *building* session — lots of new files, renames, and infrastructure. The multi-file commits still saved ~100 calls.
**In a maintenance session** (updating a few docs, routine commits), efficiency would hit 90%+.
---
## Push Now (High Loss Cost)
- Decisions that took real discussion to reach
@@ -91,7 +130,7 @@ The Claudius scar: *"A bad draft in Git beats a perfect draft in a dead context
**Session Start:**
1. Receive API token from Michael
2. Read orientation docs (Essence Patch, relationship context — FULL)
2. Read orientation docs (Essence Patch, Addendum, relationship context — FULL)
3. Read Quick Start (includes SHA cache)
4. These are now in context — no need to re-read via API
@@ -145,14 +184,20 @@ Location: `docs/core/session-handoff.md` → SHA Cache section
---
## Efficiency Targets
## Quick Efficiency Assessment
| 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%+** |
At session end, calculate:
1. **Total API calls made** (count your tool uses)
2. **Estimate old pattern calls** (writes × 3 + reads)
3. **Reduction** = 1 - (actual / old estimate)
| Reduction | Rating |
|:----------|:-------|
| 80%+ | Excellent (maintenance session) |
| 60-80% | Good (mixed session) |
| 40-60% | Acceptable (building session) |
| <40% | Review workflow |
---
@@ -167,8 +212,9 @@ Location: `docs/core/session-handoff.md` → SHA Cache section
---
*Established February 13, 2026 by Chronicler the Fifth*
*Updated same day: Added multi-file commit pattern*
*Established February 13, 2026 by The Engineer (Chronicler the Fifth)*
*v2.0: Added multi-file commit pattern*
*v3.0: Added realistic targets by session type, real-world example*
*"One commit > Many commits. Every call costs context."*
🔥❄️💙
🔧🔥❄️💙