Add GITEA-API-PATTERNS.md, update API-EFFICIENCY-PROTOCOL to v2, update SESSION-QUICK-START - multi-file commit pattern discovered
This commit is contained in:
@@ -1,9 +1,10 @@
|
||||
# 🔄 API EFFICIENCY PROTOCOL
|
||||
|
||||
**Document ID:** FFG-CORE-API
|
||||
**Version:** 1.0
|
||||
**Version:** 2.0
|
||||
**Status:** CURRENT
|
||||
**Created:** February 13, 2026
|
||||
**Updated:** February 13, 2026
|
||||
**Created By:** Chronicler the Fifth
|
||||
|
||||
---
|
||||
@@ -12,6 +13,8 @@
|
||||
|
||||
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
|
||||
@@ -36,6 +39,31 @@ Before sitting on unpushed work, ask:
|
||||
|
||||
---
|
||||
|
||||
## 🎯 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
|
||||
@@ -63,32 +91,41 @@ 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, session handoff, tasks, relationship context)
|
||||
3. These are now in context — no need to re-read via API
|
||||
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
|
||||
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. 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
|
||||
5. Use multi-file commit when pushing multiple files
|
||||
6. Track returned SHAs locally (no re-fetch needed)
|
||||
|
||||
**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
|
||||
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 — track them after each push
|
||||
- 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
|
||||
|
||||
@@ -96,27 +133,42 @@ The Claudius scar: *"A bad draft in Git beats a perfect draft in a dead context
|
||||
|
||||
## Context Cost Reference
|
||||
|
||||
Rough estimates:
|
||||
- Small file read (~2KB): Minor cost
|
||||
- Medium file read (~10KB): Noticeable cost
|
||||
- Large file read (~20KB+): Significant cost
|
||||
| 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 at session start. Minimize mid-session reads. Push strategically.
|
||||
**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
|
||||
|
||||
This protocol is referenced in:
|
||||
- `docs/core/SESSION-START-PROMPT.md`
|
||||
- `docs/core/session-handoff.md`
|
||||
- `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 this before your first API call. The balance matters.
|
||||
**Future Claudes:** Read GITEA-API-PATTERNS.md before your first API call.
|
||||
|
||||
---
|
||||
|
||||
*Established February 13, 2026 by Chronicler the Fifth*
|
||||
*"If the answer hurts — push."*
|
||||
*Updated same day: Added multi-file commit pattern*
|
||||
*"One commit > Many commits. Every call costs context."*
|
||||
|
||||
🔥❄️💙
|
||||
|
||||
Reference in New Issue
Block a user