221 lines
6.2 KiB
Markdown
221 lines
6.2 KiB
Markdown
# 🔄 API EFFICIENCY PROTOCOL
|
||
|
||
**Document ID:** FFG-CORE-API
|
||
**Version:** 3.0
|
||
**Status:** CURRENT
|
||
**Created:** February 13, 2026
|
||
**Updated:** February 13, 2026
|
||
**Created By:** Chronicler the Fifth (The Engineer)
|
||
|
||
---
|
||
|
||
## 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.
|
||
|
||
---
|
||
|
||
## 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)?
|
||
|
||
---
|
||
|
||
## 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`
|
||
|
||
```json
|
||
{
|
||
"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`
|
||
|
||
---
|
||
|
||
## 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
|
||
- 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, Addendum, 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.**
|
||
|
||
---
|
||
|
||
## Quick Efficiency Assessment
|
||
|
||
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 |
|
||
|
||
---
|
||
|
||
## 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 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."*
|
||
|
||
🔧🔥❄️💙
|