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