feat/energia-est-tune
needs attention745394e · incrementalPR #330reviewed 2026-07-21 23:31 UTC3H · 1M · 2L- Purpose
- Energía module — per-org toggleable bill intelligence layer; this branch calibrates estimated_reading detector severity based on ROI analysis (Mexico has no back-billing cap; most estimated readings are not recoverable money).
- Goal
- Demote generic estimated_reading finding from recoverable to informational, scaling to warning only on material over-estimation (>20% above contract median).
- Sub-goals
- SG-1: detectEstimatedReadings severity model revised (info default, warning on over-estimate >20%)
- SG-2: Detector version bumped estimated_reading@1 → @2
- SG-3: 68 decision tests updated to new severity model
- SG-4 (this commit): Clean up deleted spec file references in comments
- What
- 3 comment lines in finding.decisions.ts, finding.shells.ts, and finding.decisions.test.ts replaced specific spec file path references with vague prose after deleting docs/specs/energia-module-pr1-pr2.md.
- Why
- The spec file was removed (likely merged into the PR description or considered transient scaffolding); comments were updated to avoid dead paths — but the replacements are themselves untraceable.
- Areas
- domains/utility/src/finding/__tests__/finding.decisions.test.ts+28−14domains/utility/src/finding/finding.decisions.ts+21−12domains/utility/src/finding/finding.shells.ts+1−1
- Blast
- 3 files, +50/−27 total on branch; doc-only commit; no logic changes.
Findings · 6
conventions3
Spec ref → untraceable prose (test file)
domains/utility/src/finding/__tests__/finding.decisions.test.ts:8
`docs/specs/energia-module-pr1-pr2.md § Verification` was replaced with 'the energía PR2 verification spec'. The spec file was deleted in this same commit. The project requires comments to reference stable, findable anchors (file paths or ADR numbers). A reader now has no path to follow to understand the verification basis for the test fixtures. Prefer pointing to the SQL sources already cited above (`scripts/corpus-study/sql/NOTES-bill-facts.md`), the PR itself (`PR #330` or GitHub URL), or an ADR.
Spec ref → untraceable prose (decisions file)
domains/utility/src/finding/finding.decisions.ts:15
`docs/specs/energia-module-pr1-pr2.md § PR2` replaced with 'the energía PR2 spec'. The spec no longer exists in the repo. The SQL sources (`scripts/corpus-study/sql/30-estimated-readings.sql`, `36-fp-recompute.sql`) are already cited on the preceding line and would serve as a stable anchor.
Spec ref → untraceable prose (shells file)
domains/utility/src/finding/finding.shells.ts:5
`docs/specs/energia-module-pr1-pr2.md § PR2` replaced with 'the PR2 spec'. The shell comment explains a non-obvious transaction boundary decision; that rationale needs a traceable anchor. A reader cannot currently verify the design choice — prefer an ADR ref or PR link.
improvement3
Comment anchors downgraded to unresolvable prose
domains/utility/src/finding/finding.decisions.ts:15
Vague 'the energía PR2 spec' resolves to nothing — worse than the dead path it replaces (at least the path could be searched in git history). Better alternatives: `PR #330`, a GitHub URL to the PR description, or an ADR. Same applies to the shells and test files.
Surviving dead-path reference missed in schema file
packages/database/src/schema/utility-contract-findings.ts:23
Line 23 still says `See docs/specs/energia-module-pr1-pr2.md § PR2 for the full spec.` — the same dead path that was cleaned up in the three other files. This one was not updated, leaving the codebase inconsistent.
Inconsistent PR2 reference wording across files
domains/utility/src/finding/finding.shells.ts:5
`finding.shells.ts` uses 'the PR2 spec' (no module qualifier); the other two files use 'the energía PR2 spec'. Minor inconsistency makes grep-based cross-referencing harder. Unify to one form once a stable anchor is chosen.