chore: retro-review PR #108 — docs(spec): three quick wins from spec-completeness audit (81/100)#138
Closed
Artic0din wants to merge 1 commit into
Closed
Conversation
Spec audit (5-layer framework) scored the repo 81/100 — Safe tier for
agent delegation — with L2 (interface) + L5 (cultural) flagged yellow.
The three quick wins close the highest-ROI gaps without forcing a
codebase rewrite.
Win 1 — pyproject.toml (L2 + L5 fix)
Pin ruff + pyright + pytest config. Ruff ruleset matches what the
codebase already passes (E + F), with a documented future-strict
ladder (W, I, B, UP, S, BLE, RUF) and pre-counted violations per
rule so each can be adopted incrementally. Pyright basic-mode +
reportMissingImports=warning to tolerate HA libs being absent in
the sandbox while still catching real type errors.
Win 2 — docs/development.md naming + reference implementations (L5)
Append three sections:
- Naming conventions for entity_id, provider_id, statistic_id,
config-flow step IDs, service IDs, CONF_* constants. Pins the
live-UAT 2026-05-23 lowercase-statistic_id contract in writing.
- Reference implementations table — canonical file per pattern
(external-SDK price source, public-endpoint price source,
CDR-derived provider, composition wrapper, Energy-Dashboard
sensor, reauth dispatcher, external-stats push).
- Versioning policy — SemVer + HACS rules, beta tag handling,
when version bumps happen in a stack.
Win 3 — agent orientation + codex findings in TODOS.md (L1 + L4)
- CLAUDE.md gains an "Agent orientation" section pointing at the
six artefacts an agent must read before non-trivial work
(.paul/STATE.md, .paul/phases/<phase>/PLAN.md, DECISIONS.md,
TODOS.md, docs/architecture.md, docs/development.md).
- TODOS.md grows a "Codex full-repo review findings (2026-05-23)"
section enumerating the P0/P1/P2 items the codex pass surfaced
(dashboard ha_token in URL, DWT midnight rollover gap, legacy
hass.data in options flow, per-entry service capture, monotonic
sum violation, single-rate ranking gap, DWT from_dict ignores
today, background task cleanup, MagicMock test drift, pycache
secret-shaped strings). Each entry has file:line + fix + priority
so a future agent doesn't silently re-discover them.
E741 cleanup in tests/test_blueprints.py — three list comprehensions
used `l` as the loop variable; renamed to `line` so the codebase
clears bare `ruff check` against the new pyproject ruleset.
1070 passing, ruff clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Owner
Author
|
@claude review |
Owner
Author
|
Retro-review complete. Findings (if any) tracked in fix/retro-review-batch (#143) or noted in .planning/retro-review-findings.md. Closing synthetic PR + cleaning branches. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Synthetic retro-review of merged PR #108. Diff = original
b78edac..4896d87(same as original PR). Do NOT merge; close after @claude review posts.