pal-e-docs

Review: Rename BoardItemType 'issue' to 'ticket' for semantic clarity

review-479-2026-03-27 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone, discovered during board item creation workflows
  • [x] Repo -- Cross-repo identified
  • [x] User Story -- Well-formed As/I want/So that
  • [x] Context -- Thorough explanation of semantic confusion + breaking change awareness
  • [x] File Targets -- Detailed with line numbers (some issues noted below)
  • [x] Acceptance Criteria -- 8 criteria present
  • [x] Test Expectations -- Specific test files and run commands
  • [x] Constraints -- Historical migration protection, backward compat, deploy order
  • [x] Checklist -- Present
  • [x] Related -- Present with project and convention links

Traceability

  • [x] story:pm-scope label -- PM scoping user story
  • [x] arch:note-system label -- note system architecture component
  • [x] Forgejo issue -- forgejo_admin/claude-custom#181, open

File Targets

  • [x] pal-e-docs/src/pal_e_docs/models.py:34-40 -- verified: BoardItemType enum has issue = "issue" at line 37
  • [x] pal-e-docs/src/pal_e_docs/schemas.py:225 -- verified: BoardItemTypeType Literal includes "issue"
  • [x] pal-e-docs/src/pal_e_docs/schemas.py:258-264 -- verified: BoardItemCounts has issue: int = 0 at line 261
  • [x] pal-e-docs/src/pal_e_docs/routes/boards.py:395 -- verified: docstring references item_type=issue
  • [x] pal-e-docs/src/pal_e_docs/routes/boards.py:488 -- verified: item_type=BoardItemType.issue
  • [x] pal-e-docs/src/pal_e_docs/routes/boards.py:602-605 -- verified: validation checks body.item_type == "issue"
  • [x] pal-e-docs/tests/test_boards.py -- verified: ~11 references to "item_type": "issue"
  • [x] pal-e-docs/tests/test_board_issue_sync.py -- verified: 7 references to item_type=issue
  • [x] pal-e-docs/tests/test_pagination_activity.py:49 -- verified: 1 reference
  • [x] pal-e-docs/alembic/versions/f6a7b8c9d0e1_sprint_schema_expansion.py:30-31 -- verified: historical migration, correctly marked as do-not-modify
  • [x] pal-e-docs-sdk/src/pal_e_sdk/boards.py:112-113 -- verified: docstring says "issue items require"
  • [x] pal-e-docs-sdk/tests/test_boards.py -- verified: 4 references to item_type="issue"
  • [x] claude-custom/hooks/check-board-item.sh:52-57 -- verified: issue) case branch at line 53
  • [x] claude-custom/skills/review-ticket/SKILL.md:27 -- verified: lists (phase, issue, incident, repo)
  • [x] claude-custom/skills/review-ticket/SKILL.md:42 -- verified: "For issue items with forgejo_issue_url:"
  • [ ] claude-custom/docs/superpowers/specs/2026-03-18-review-ticket-design.md:41 -- INACCURATE: line 41 references the field name item_type, not the value "issue". No actual change needed. Remove from file targets.
  • [ ] MISSING: pal-e-mcp/src/pal_e_mcp/tools/boards.py:180-181 -- tool description says "plan, phase, issue, todo, repo, project" and "For issue items, provide forgejo_issue_url". This is the MCP tool description agents see at runtime.
  • [ ] MISSING: pal-e-mcp/tests/test_param_alignment.py -- 5 test cases pass item_type="issue" (lines 349, 357, 365, 372, 379)

Repo Placement

MISMATCH. The issue says "Cross-repo: pal-e-docs, pal-e-docs-sdk, claude-custom" but misses pal-e-mcp (the MCP server at ~/pal-e-mcp). The MCP server has the tool description that agents see at runtime -- this is where acceptance criterion #5 ("MCP create_board_item tool description shows ticket in the valid values list") actually lives. The issue must add pal-e-mcp as a fourth repo. A fourth Forgejo issue is likely NOT needed -- the MCP changes are small (1 docstring + 5 test values) and could be batched with the SDK PR. But the scope document must acknowledge this repo.

Dependencies

No blocking dependencies found on the board. Item #478 (Spike: Note type system audit) is in_progress and touches arch:note-system, but it's about NoteTypes not BoardItemTypes -- no conflict. The deploy ordering documented in the issue (API -> SDK -> hooks -> remove compat) is correct and sufficient. The pal-e-mcp deploy would slot after SDK (since MCP depends on SDK).

Acceptance Criteria

8 acceptance criteria. All are mechanically verifiable except #8 ("No remaining references to item_type='issue'") which requires a cross-repo grep -- an agent can do this. Criterion #5 ("MCP create_board_item tool description") cannot be verified against the file targets as written because the MCP repo is missing. The test commands in Test Expectations are valid: pytest tests/test_boards.py tests/test_board_issue_sync.py tests/test_board_sync.py tests/test_pagination_activity.py -v. Missing: test command for pal-e-mcp (pytest tests/test_param_alignment.py -v).

Blast Radius

pal-e-mcp is the main blast radius miss. Beyond the four repos, the board_items table in production has existing rows with item_type='issue' (confirmed: board-pal-e-agency alone has 55 issue-type items; board-westside-basketball has 109). The data migration is correctly scoped. No downstream consumers beyond the MCP server were found -- the SDK is the only programmatic client, and hooks only validate via the shell script.

Decomposition

NEEDS DECOMPOSITION. 4 repos, ~15+ file targets, 8 acceptance criteria, breaking change with data migration + backward compatibility transition period + ordered deploy sequence. This is well beyond the 5-minute rule. Recommend decomposition via template-board:
  • Ticket A: pal-e-docs API -- enum rename, schema, routes, data migration, tests (~8 file targets, the foundation)
  • Ticket B: pal-e-docs-sdk + pal-e-mcp -- SDK docstring + tests, MCP tool description + tests (~4 file targets, depends on A being deployed)
  • Ticket C: claude-custom -- hook + skill updates (~3 file targets, depends on A being deployed)
  • Ticket D: Remove backward compatibility from API (depends on B + C being deployed)

Recommendation

  • [BODY] Add pal-e-mcp to the Repo section: "Cross-repo: pal-e-docs, pal-e-docs-sdk, pal-e-mcp, claude-custom"
  • [BODY] Add pal-e-mcp file targets: pal-e-mcp/src/pal_e_mcp/tools/boards.py:180-181 (tool description) and pal-e-mcp/tests/test_param_alignment.py (5 test references)
  • [BODY] Remove inaccurate file target: docs/superpowers/specs/2026-03-18-review-ticket-design.md:41 -- no change needed there
  • [BODY] Add pal-e-mcp test command to Test Expectations: pytest tests/test_param_alignment.py -v
  • [BODY] Update Checklist to show 4 PRs (one per repo) instead of 3
  • [DECOMPOSE] 4 repos, 15+ file targets, 8 AC, ordered deploy with backward compat transition. Split into 4 tickets via template-board (API foundation, SDK+MCP, hooks/skills, backward compat removal).