Review: Review note audit: naming, types, lifecycle

Verdict: NEEDS_REFINEMENT

Template Completeness

• [x] Type — Bug
• [x] Lineage — discovered during westside schedule feature scoping
• [x] Repo — forgejo_admin/pal-e-api, cross-repo touch to claude-custom noted
• [x] What Broke — 4 specific items described
• [x] Repro Steps — 4-step sequence with concrete example (item #629 vs issue #232)
• [x] Expected Behavior — 3 bullet points
• [x] Environment — pal-e-docs API production, hook path, skill note
• [x] Acceptance Criteria — 6 AC items
• [x] Related — 5 links to relevant notes and files

Traceability

• [x] story:pm-scope — present on board item
• [x] arch:review-pipeline — present on board item
• [x] Forgejo issue — forgejo_admin/pal-e-api#246, open

File Targets

• [x] template-review (pal-e-docs note) — VERIFIED: naming convention section says review-{issueNumber}-{YYYY-MM-DD} (contradicts skill) and note_type: doc (until review is added to NoteType enum) (stale — review IS in enum at schemas.py line 15)
• [x] skill-review-ticket step 12 — VERIFIED: says review-{board_item_id}-YYYY-MM-DD with note_type: review (correct)
• [x] ~/.claude/hooks/check-board-advance.sh — VERIFIED: uses review-{item_id}-* slug pattern (lines 52-56). Matches skill, contradicts template-review
• [x] feedback_active_note_types in MEMORY.md — VERIFIED: lists "sop, convention, doc, project-page, board" — review is absent
• [x] convention-review-note-lifecycle — VERIFIED: does not exist (AC3 requires creation)
• [x] NoteType enum in src/pal_e_docs/schemas.py — VERIFIED: review present at line 15

Repo Placement

• pal-e-api — AC1 (fix note_type for 44 notes via API or migration) and AC2 (query orphaned notes)
• pal-e-docs notes (via MCP tools) — AC3 (create convention note), AC5 (verify skill note), AC6 (fix template-review)
• claude-custom — AC4 (update MEMORY.md feedback_active_note_types)

Dependencies

• [x] Board item #478 (Spike: Note type system audit) — in_progress. This spike may produce decisions that affect AC3 (convention design) and AC4 (active types list). The audit ticket should wait for or coordinate with the spike outcome.
• [x] Board item #646 (Content sweep: rename Betty Sue to Ava) — in_progress. template-review also contains "Betty Sue" reference in When to Create section. Could conflict if both tickets edit template-review simultaneously.

Acceptance Criteria

• AC1 (fix note_type for 44 notes) — Testable: query API for review-tagged notes with note_type != review. Specific and clear.
• AC2 (identify orphaned/duplicate review notes) — Partially testable: "identified" is not a verifiable end state. Does this mean listed? Deleted? Logged? Needs clarification on what "identified" means as a deliverable.
• AC3 (create convention-review-note-lifecycle) — Testable: note exists with slug. But content requirements are vague — "defining creation, naming, type, and cleanup rules" needs more specificity on what cleanup means (archive? delete? tag?).
• AC4 (update feedback_active_note_types) — Testable: grep MEMORY.md for review in the list. Clear.
• AC5 (verify skill step 12 + explain drift) — Not testable as written. "Note WHY agents drift" is analysis, not a verifiable criterion. Suggest splitting: verify step 12 is correct (testable) vs. root cause analysis (spike/doc).
• AC6 (fix template-review stale guidance) — Testable: read template-review naming convention section, confirm note_type says review and slug says board_item_id. Clear.

Blast Radius

• review note data (44 notes) — Low risk. Changing note_type from doc to review is a safe metadata update. The migration already exists but may not have caught all notes (notes created after migration ran).
• template-review — Medium risk. This template guides all future review agents. Getting the naming convention wrong here causes the same slug mismatch bug. Must be correct.
• check-board-advance.sh — Not touched by this ticket (confirmed: "code change is a separate ticket if needed"). No blast radius.
• convention-review-note-lifecycle — New note. No existing consumers to break. But cleanup rules could have downstream effects if automated.
• MEMORY.md — Low risk. Adding one word to a list.

Decomposition Assessment

• 6 AC items across 3 repos (pal-e-api, pal-e-docs notes, claude-custom)
• Mix of data operations (AC1, AC2), content creation (AC3), metadata updates (AC4, AC6), and analysis (AC5)
• Estimated agent work: well over 5 minutes for a single agent
• AC1+AC2 are data operations that can be parallelized with AC3+AC6 (content fixes)
• AC5 is analysis/investigation — different work type than the other ACs

• Data fix: AC1 (fix 44 note_types) + AC2 (identify orphans) — pal-e-api
• Template + convention: AC3 (create convention note) + AC6 (fix template-review) — pal-e-docs notes
• Memory update: AC4 (update feedback_active_note_types) — claude-custom (tiny, could be folded into #2)
• Drift analysis: AC5 (investigate why agents use wrong slug pattern) — analysis/spike

Recommendation

• [BODY] AC2: Clarify what "identified" means as a deliverable — list them in a note? Delete them? Archive them? Tag them?
• [BODY] AC5: Split into testable part (verify skill step 12 is correct) and analysis part (root cause of agent drift). The analysis could be a separate spike or folded into AC3 convention note.
• [BODY] Add dependency note: board item #478 (note type system audit spike) is in_progress and may affect decisions about review note lifecycle and active types list.
• [DECOMPOSE] 6 AC across 3 repos exceeds the three-thing limit. Recommend decomposition into 3-4 sub-tickets via template-board. See Decomposition Assessment section above.