loki/docs/implementation/README.md

Implementation Notes

This directory holds per-step implementation notes for the Loki REST API refactor. Each note captures what was actually built during one step, how it differed from the plan, any decisions made mid-implementation, and what the next step needs to know to pick up cleanly.

Why this exists

The refactor is spread across multiple phases and many steps. The implementation plans in docs/PHASE-*-IMPLEMENTATION-PLAN.md describe what should happen; these notes describe what did happen. Reading the plan plus the notes for the most recent completed step is enough context to start the next step without re-deriving anything from the conversation history or re-exploring the codebase.

Naming convention

One file per completed step:

PHASE-<phase>-STEP-<step>-NOTES.md

Examples:

• PHASE-1-STEP-1-NOTES.md
• PHASE-1-STEP-2-NOTES.md
• PHASE-2-STEP-3-NOTES.md

Contents of each note

Every note has the same sections so they're easy to scan:

1. Status — done / in progress / blocked
2. Plan reference — which phase plan + which step section this implements
3. Summary — one or two sentences on what shipped
4. What was changed — file-by-file changelist with links
5. Key decisions — non-obvious choices made during implementation, with the reasoning
6. Deviations from plan — where the plan said X but reality forced Y, with explanation
7. Verification — what was tested, what passed
8. Handoff to next step — what the next step needs to know, any preconditions, any gotchas

Lifetime

This directory is transitional. When Phase 1 Step 10 lands and the GlobalConfig type alias is removed, the Phase 1 notes become purely historical. When all six phases ship, this whole directory can be archived into docs/archive/implementation-notes/ or deleted outright — the plans and final code are what matters long-term, not the step-by-step reconstruction.