pal-e-docs

Review: Review note audit: naming, types, lifecycle

review-634-2026-03-28 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Bug
  • [x] Lineage — discovered during westside schedule scoping
  • [x] Repo — forgejo_admin/pal-e-api
  • [x] What Broke — 4 specific problems listed
  • [x] Repro Steps — 4 clear steps with observable outcome
  • [x] Expected Behavior — 3 concrete expectations
  • [x] Environment — pal-e-docs API, hook path, skill note
  • [x] Acceptance Criteria — 5 criteria
  • [x] Related — 4 references
All required Bug template sections are present and filled.

Traceability

  • [x] story:pm-scope — PM scoping pipeline
  • [x] arch:review-pipeline — review pipeline component
  • [x] Forgejo issue — forgejo_admin/pal-e-api#246, open
Traceability triangle is complete.

File Targets

  • [x] ~/.claude/hooks/check-board-advance.sh — verified exists. Queries review-{item_id}-* pattern (lines 52-56). Searches by slug prefix, not note_type.
  • [x] skill-review-ticket (pal-e-docs note) — verified exists. Step 12 specifies review-{board_item_id}-YYYY-MM-DD slug pattern.
  • [x] feedback_active_note_types (MEMORY.md line 83) — verified exists. Lists sop/convention/doc/project-page/board. Review is absent.
  • [x] convention-todo-lifecycle — referenced as related only, not a direct target.
All file targets verified. Targets are specific enough for agent execution.

Repo Placement

Issue filed on forgejo_admin/pal-e-api. Most work is data operations against the pal-e-docs API — correct repo. However, AC4 requires editing ~/.claude/projects/.../MEMORY.md which lives in claude-custom. This is a single-line edit and does not warrant a separate ticket, but should be noted in the issue body.

Dependencies

No blocking dependencies found on board-pal-e-agency. Item #591 ("Enhance skill-review-ticket") is related but independent backlog work. Items #581 and #638 (scope-review hooks) are already done. This ticket is independent.

Acceptance Criteria

All 5 criteria are testable by an agent:
  • AC1 (fix note_type): Query list_notes(tags="review"), filter note_type != "review", update each. Current count: 44 need fixing (42 doc + 2 null). Verifiable post-fix.
  • AC2 (orphan identification): Cross-reference 301 review note slugs against board items. Notes referencing items in done or missing items are orphans. Automatable but API-heavy.
  • AC3 (convention note): get_note(slug="convention-review-note-lifecycle") — confirmed does not exist yet. Net-new creation.
  • AC4 (active types): Check MEMORY.md for review in active types. Single line edit in claude-custom.
  • AC5 (skill verification): Verify skill-review-ticket step 12. Analysis task, inherently subjective but scoped.
Note: AC test commands are implied (MCP queries) rather than explicitly stated. Acceptable for data audit work.

Blast Radius

Low. The check-board-advance hook searches by slug prefix, NOT by note_type. Fixing note_type from doc/null to review is a pure data quality fix with no downstream behavioral change. No other hooks or skills filter by note_type=review. Rollback is straightforward (revert note_type values).

Decomposition Assessment

5 ACs touching primarily one system (pal-e-docs API) plus one line in MEMORY.md. The audit (AC1+AC2) requires iterating 300+ notes via API, which may exceed 5 minutes wall-clock but is logically cohesive. Splitting would create coordination overhead exceeding the work itself. No independent subtasks that benefit from parallelization — all ACs feed the same convention note (AC3). No decomposition needed.

Recommendation

  • [BODY] Fix inaccurate claim in What Broke #2: "most notes were created as doc or null." Actual data: 257/301 (85%) already have correct note_type=review. Only 44 need fixing (42 doc + 2 null). Update to reflect accurate numbers.
  • [BODY] Fix overstated slug naming claim in What Broke #1: "agents frequently use Forgejo issue numbers instead." The data shows IDs range 55-653, which IS the board item ID range. The repro example (review-232 for item #629) may be a real case but is not systemic. Clarify that slug naming is mostly correct; the primary issue is the 44 wrong-typed notes.
  • [BODY] Add note under Repo section: AC4 touches claude-custom MEMORY.md (cross-repo, single line edit).
  • [BODY] Note: template-review itself has stale guidance — its Naming Convention section says Note type: doc (until review is added to NoteType enum) but review IS already in the enum. Add a sub-task or note to fix template-review as part of this work.