Documentation cleanup pass #6

New issue

Closed

opened 2026-07-17 01:17:54 +00:00 by claude-bot · 2 comments

claude-bot commented

2026-07-17 01:17:54 +00:00

Contributor

Docs have drifted from reality:

docs/roadmap.md is 727 lines with every one of its ~400 checkboxes marked complete. It reads as a finished historical artifact but is still presented as a live roadmap. Remaining work actually lives in the audit doc, not here.
docs/implementation-audit.md is dated 2026-05-13 but describes work committed well after that (server-side calculation API, caching, whole-home exclusion).
The audit's Missing section contains an Inverter Modeling subsection whose remaining gaps read None - it belongs under implemented, not missing.
docs/calculation-logic-audit.md (849 lines) needs a freshness check.

Goal: roadmap retired or clearly marked historical, audit re-dated and corrected, remaining work pointed at the issue tracker rather than restated in prose.

Docs have drifted from reality: - `docs/roadmap.md` is 727 lines with every one of its ~400 checkboxes marked complete. It reads as a finished historical artifact but is still presented as a live roadmap. Remaining work actually lives in the audit doc, not here. - `docs/implementation-audit.md` is dated 2026-05-13 but describes work committed well after that (server-side calculation API, caching, whole-home exclusion). - The audit's `Missing` section contains an `Inverter Modeling` subsection whose remaining gaps read `None` - it belongs under implemented, not missing. - `docs/calculation-logic-audit.md` (849 lines) needs a freshness check. Goal: roadmap retired or clearly marked historical, audit re-dated and corrected, remaining work pointed at the issue tracker rather than restated in prose.

claude-bot added this to the v1.1.0 - Test & Ops Hardening milestone

2026-07-17 01:17:54 +00:00

claude-bot added the

docs

label

2026-07-17 01:17:54 +00:00

claude-bot commented

2026-07-17 01:29:22 +00:00

Author

Contributor

Cleanup pass done across four documents.

docs/roadmap.md — reframed as a historical record. Added a header stating it is complete, that work is tracked in issues, and that a checked box means scope delivered rather than capability live (Milestones 7 and 8 delivered a framework and a manual/CSV path, not live integrations). The Open Questions section now links to #15-#18 instead of restating them.

docs/implementation-audit.md — re-dated to 2026-07-16 with the 2026-05-13 revision noted. Fixes:

Missing > Inverter Modeling listed ~11 implemented features under a heading that said its remaining gaps were None. Moved to a new Implemented section.
Missing renamed to Known Gaps, with every gap now linking to its issue.
Partial Or Needs Rework renamed to Implemented With Caveats — it contained no outstanding work.
Corrected a stale caveat claiming Emporia data is "intentionally dropped on reload". True only for unauthenticated local use; with a home selected it persists and is reconstructed.
Tab list said 8 tabs; src/App.jsx:47 has 11 (missing Billing, Reports, Admin).
Recommended Next Slice replaced with a milestone map.

docs/calculation-logic-audit.md — verified against code before editing. Its formulas and every rate constant are still accurate (only simulation.js and outage.js changed since it was written, and that was a behavior-neutral perf refactor), so those were left untouched. What was wrong was structural — it claimed src/App.jsx is the calculation coordinator, which stopped being true when calculation moved to the shared runtime. Rewrote Data Flow, added a Where Calculations Run section (worker/backend parity, routes, fallback, cache revisions, warnings codes), repointed three location claims to calculationEngine.js/projections.js, documented per-circuit whole-home exclusion under outage — explicitly noting it does not affect bill savings — and extended the test list.

README.md — migration table listed 3 of 7 migrations and wrongly attributed calculation results to 001 (it's 004). Rebuilt from the actual DDL. Added a Contributing section covering changelog, versioning, CI, and Renovate. Added the missing Reports tab.

Also noted: two migrations share the 003_ prefix. Verified this is not a bug — backend/src/migrate.js keys each by full filename and sorts lexicographically, so ordering is deterministic. Documented as a naming smell with a note to use 007_ next.

Staged in the working tree; not yet committed.

Cleanup pass done across four documents. **`docs/roadmap.md`** — reframed as a historical record. Added a header stating it is complete, that work is tracked in issues, and that a checked box means scope delivered rather than capability live (Milestones 7 and 8 delivered a framework and a manual/CSV path, not live integrations). The Open Questions section now links to #15-#18 instead of restating them. **`docs/implementation-audit.md`** — re-dated to 2026-07-16 with the 2026-05-13 revision noted. Fixes: - `Missing > Inverter Modeling` listed ~11 implemented features under a heading that said its remaining gaps were `None`. Moved to a new `Implemented` section. - `Missing` renamed to `Known Gaps`, with every gap now linking to its issue. - `Partial Or Needs Rework` renamed to `Implemented With Caveats` — it contained no outstanding work. - Corrected a stale caveat claiming Emporia data is *"intentionally dropped on reload"*. True only for unauthenticated local use; with a home selected it persists and is reconstructed. - Tab list said 8 tabs; `src/App.jsx:47` has 11 (missing Billing, Reports, Admin). - Recommended Next Slice replaced with a milestone map. **`docs/calculation-logic-audit.md`** — verified against code before editing. Its formulas and every rate constant are still accurate (only `simulation.js` and `outage.js` changed since it was written, and that was a behavior-neutral perf refactor), so those were left untouched. What was wrong was structural — it claimed `src/App.jsx` is the calculation coordinator, which stopped being true when calculation moved to the shared runtime. Rewrote Data Flow, added a `Where Calculations Run` section (worker/backend parity, routes, fallback, cache revisions, `warnings` codes), repointed three location claims to `calculationEngine.js`/`projections.js`, documented per-circuit whole-home exclusion under outage — explicitly noting it does **not** affect bill savings — and extended the test list. **`README.md`** — migration table listed 3 of 7 migrations and wrongly attributed calculation results to `001` (it's `004`). Rebuilt from the actual DDL. Added a Contributing section covering changelog, versioning, CI, and Renovate. Added the missing Reports tab. Also noted: two migrations share the `003_` prefix. Verified this is **not** a bug — `backend/src/migrate.js` keys each by full filename and sorts lexicographically, so ordering is deterministic. Documented as a naming smell with a note to use `007_` next. Staged in the working tree; not yet committed.

claude-bot referenced this issue

2026-07-17 01:41:03 +00:00

Add CI, Renovate config, changelog, and lockfiles; refresh docs #20

claude-bot commented

2026-07-17 02:00:53 +00:00

Author

Contributor

Done in #20 (a0d604b) and corrected in #21 (5411033).

The #21 follow-up was necessary because the #20 branch was cut from a stale main: the calculation audit merged in still described payback as plain division and asserted battery degradation was unmodeled, both untrue after b31aa8c. Now reconciled against a0d604b.

Done in #20 (`a0d604b`) and corrected in #21 (`5411033`). The #21 follow-up was necessary because the #20 branch was cut from a stale `main`: the calculation audit merged in still described payback as plain division and asserted battery degradation was unmodeled, both untrue after `b31aa8c`. Now reconciled against `a0d604b`.

claude-bot closed this issue

2026-07-17 02:00:54 +00:00