Audit and clean up review notes: type consistency, naming, and lifecycle #246
Labels
No labels
domain:backend
domain:devops
domain:frontend
status:approved
status:in-progress
status:needs-fix
status:qa
type:bug
type:devops
type:feature
No milestone
No project
No assignees
1 participant
No due date set.
Dependencies
No dependencies set.
Reference
ldraney/pal-e-api#246
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "%!s()"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Type
Bug
Lineage
Discovered during westside schedule feature scoping — review agents created notes with wrong slugs (Forgejo issue number instead of board item ID), wrong note_type (
docinstead ofreview), blocking thecheck-board-advancehook.Repo
forgejo_admin/pal-e-api(notes + skill-review-ticket)Cross-repo touch: AC4 (update
feedback_active_note_types) requires editingMEMORY.mdinclaude-custom, not this repo. Coordinate accordingly.What Broke
Review notes are inconsistent and accumulating without cleanup:
skill-review-ticketstep 12 saysreview-{board_item_id}-YYYY-MM-DDbut a small number of agents have used Forgejo issue numbers instead. Thecheck-board-advancehook queries forreview-{board_item_id}-*, so misnamed notes fail the gate silently. Note: audit shows the IDs used are generally in the board-item-ID range — this is not a systemic pattern, but the naming convention should still be reinforced.reviewbut audit shows 44 of 301 review-tagged notes have the wrong type (42doc+ 2null). The remaining 257 (85%) already havenote_type=review. Fix scope is the 44, not 301.done.reviewis not infeedback_active_note_types(sop, convention, doc, project-page, board). Either add it or decide reviews shouldn't be notes.Repro Steps
/review-ticket board-westside-basketball#629review-232-2026-03-28(using Forgejo issue #232 instead of board item #629)check-board-advancehook blocks because it looks forreview-629-*Expected Behavior
review-{board_item_id}-*slugs consistentlydoneEnvironment
~/.claude/hooks/check-board-advance.shskill-review-ticketnote in pal-e-docsAcceptance Criteria
reviewfor the 44 notes that need it (42doc+ 2nullout of 301 total)doneor no longer exists)convention-review-note-lifecycledefining creation, naming, type, and cleanup rulesreviewadded to active note types list infeedback_active_note_typesinclaude-customMEMORY.md (or decision documented to remove review notes entirely)skill-review-ticketstep 12 verified — if the naming convention is clear, note WHY agents drift (possible: agents see existing misnamed notes and copy the pattern)template-reviewcontains stale guidance ("Note type: doc (until review is added to NoteType enum)") —reviewIS already in the NoteType enum. Update the template to saynote_type: review.Related
skill-review-ticket— the skill that guides review agentscheck-board-advance.sh— hook in claude-custom that enforces the gate (code change is a separate ticket if needed)feedback_active_note_types— memory noting active types (lives inclaude-customMEMORY.md, not pal-e-api)convention-todo-lifecycle— related lifecycle conventiontemplate-review— review note template (contains stale note_type guidance)Review Note Audit -- Dottie Report
Summary
review)docinstead ofreview)doneor superseded)Review Notes Inventory
review-241-2026-03-28review-317-2026-03-24review-356-2026-03-25review-356-2026-03-25-r2review-364-2026-03-27review-364-2026-03-27-v2review-376-2026-03-25review-376-2026-03-25-r2review-398-2026-03-26review-416-2026-03-25review-416-2026-03-26review-418-2026-03-25review-418-2026-03-25-r2review-418-2026-03-27review-424-2026-03-26review-464-2026-03-27review-464-2026-03-28review-479-2026-03-27review-181-2026-03-27review-595-2026-03-28review-595-2026-03-28-r2review-597-2026-03-28review-597-2026-03-28-r2Fixes Applied
review-595-2026-03-28,review-597-2026-03-28,review-597-2026-03-28-r2changed fromdoctoreview.template-reviewnaming convention section saidnote_type: doc (until review is added to NoteType enum)-- butreviewIS a valid NoteType now. Stale guidance caused the westside-ai-assistant session to usedoc.Duplicate Reviews (Review Chains)
These are expected -- they are the review-fix-re-review loop in action:
Naming Convention Conflict Found
Three sources gave conflicting slug guidance:
skill-review-ticketstep 12:review-{board_item_id}-{YYYY-MM-DD}(authoritative)template-review:review-{issueNumber}-{YYYY-MM-DD}(stale)note-conventions:review-{repo}-{pr-number}(describes PR reviews, different artifact)Resolution:
skill-review-ticketis authoritative. All existing review notes already follow the board-item-ID pattern.template-reviewnaming convention section needs updating to match.Convention Note Created
convention-review-note-lifecycle-- covers naming, note_type, tags, status, cleanup rules, and documents the source conflict resolution.Remaining Work (for Betty Sue)
template-reviewnaming convention section to sayreview-{board_item_id}andnote_type: review(currently says{issueNumber}anddoc).doneolder than 7 days are cleanup candidates per the new convention.Scope Review: NEEDS_REFINEMENT
Review note:
review-634-2026-03-28Issue body contains inaccurate data claims that should be corrected before execution.
note_type=review. Only 44 need fixing (42 doc + 2 null).claude-customMEMORY.md, not pal-e-api.template-reviewNaming Convention section saysNote type: doc (until review is added to NoteType enum)butreviewIS already in the enum. Should be fixed as part of this work or as discovered scope.Scope refinement applied (Dottie, 2026-03-28)
Source:
review-634-2026-03-28(NEEDS_REFINEMENT verdict, board-pal-e-agency item 634)4 fixes applied to issue body:
Corrected data claims (What Broke #2, AC1): Original said "most notes were created as
docornull" and "50+ notes taggedreviewexist with mixed types." Audit shows 257/301 (85%) already havenote_type=review. Only 44 need fixing (42doc+ 2null). AC1 updated to reflect the actual fix scope.Corrected slug naming claim (What Broke #1): Original said "agents frequently use Forgejo issue numbers instead of board item IDs." Audit shows the IDs are generally in the board-item-ID range — not a systemic pattern. Softened the language and noted the convention should still be reinforced.
Documented cross-repo touch (AC4):
feedback_active_note_typeslives inclaude-customMEMORY.md, not pal-e-api. Added explicit callout in Repo section and updated AC4 + Related section to note the cross-repo dependency.Added discovered scope — template-review stale guidance (new AC6):
template-reviewsays "Note type: doc (until review is added to NoteType enum)" butreviewIS already in the NoteType enum. Added as a new checklist item in Acceptance Criteria and addedtemplate-reviewto Related section.Scope Review: NEEDS_REFINEMENT
Review note:
review-634-2026-03-29Well-scoped bug with complete template and full traceability, but exceeds single-agent execution capacity.