56 lines
1.9 KiB
Markdown
56 lines
1.9 KiB
Markdown
# 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.
|