Summary
The biometric-vault package has accumulated ~700+ comment lines that reference internal review iteration (Round-N FX: prefixes), narrate pre-fix vs. post-fix history, or expand single-sentence intent into multi-paragraph essays. This is noise — git history captures the fix narrative; comments should describe the current code's intent and constraints.
Scope
Files with the highest comment debt:
| File |
Round-N / pre-fix references |
src/lib/enbox/__tests__/biometric-vault.test.ts |
70 |
src/lib/enbox/agent-store.ts |
67 |
src/lib/enbox/biometric-vault.ts |
61 |
src/lib/enbox/__tests__/agent-store.reset-blockers.test.ts |
57 |
android/.../NativeBiometricVaultModule.kt |
27 |
src/features/session/session-store.test.ts |
26 |
src/features/session/session-store.ts |
21 |
ios/.../RCTNativeBiometricVault.mm |
16 |
| (long tail across remaining package files) |
~200 |
Problems with the Current Style
- Review-cycle prefixes (
// Round-15 F3:, // Round-9 F4:): meaningless to anyone not present for the original review.
- Pre-fix narration (
Pre-fix the helper logged a warning and returned 'true'...): explains code that no longer exists.
- Multi-paragraph essays where one sentence would do: many comments restate the surrounding code instead of explaining intent.
- Fictional spec tags (
VAL-VAULT-028): there is no validation document the codebase ships; these tags don't resolve.
self-review tags: internal AI-cycle nomenclature.
Acceptance Criteria
- Zero
Round-N FX: / Round-N self-review: prefixes in the package.
- No
Pre-fix ... / pre-fix ... historical narration.
VAL-VAULT-XXX tags either resolve to a real, checked-in spec or are removed.
- File / function header comments describe the what and why (intent, invariants, non-obvious constraints) — not the change history.
- Multi-paragraph block comments collapsed to 1–3 lines unless they capture a non-obvious invariant or trade-off.
- Crash-resilience / fail-CLOSED rationale stays — but framed as current constraints, not as patch notes.
- Test files: prefer descriptive
describe / it titles over inline narration; keep at most one short intent comment per test.
Out of Scope
- Refactoring code structure (separate issues).
- Renaming public APIs.
Notes
- Commit messages and PR descriptions remain valid places for review-round nomenclature; they live in git history where it belongs.
Summary
The
biometric-vaultpackage has accumulated ~700+ comment lines that reference internal review iteration (Round-N FX:prefixes), narrate pre-fix vs. post-fix history, or expand single-sentence intent into multi-paragraph essays. This is noise — git history captures the fix narrative; comments should describe the current code's intent and constraints.Scope
Files with the highest comment debt:
Round-N/pre-fixreferencessrc/lib/enbox/__tests__/biometric-vault.test.tssrc/lib/enbox/agent-store.tssrc/lib/enbox/biometric-vault.tssrc/lib/enbox/__tests__/agent-store.reset-blockers.test.tsandroid/.../NativeBiometricVaultModule.ktsrc/features/session/session-store.test.tssrc/features/session/session-store.tsios/.../RCTNativeBiometricVault.mmProblems with the Current Style
// Round-15 F3:,// Round-9 F4:): meaningless to anyone not present for the original review.Pre-fix the helper logged a warning and returned 'true'...): explains code that no longer exists.VAL-VAULT-028): there is no validation document the codebase ships; these tags don't resolve.self-reviewtags: internal AI-cycle nomenclature.Acceptance Criteria
Round-N FX:/Round-N self-review:prefixes in the package.Pre-fix .../pre-fix ...historical narration.VAL-VAULT-XXXtags either resolve to a real, checked-in spec or are removed.describe/ittitles over inline narration; keep at most one short intent comment per test.Out of Scope
Notes