pal-e-docs

Review: Issue #181 -- Rename BoardItemType 'issue' to 'ticket'

review-181-2026-03-27 Review

review needs-refinement
Project

Review: Forgejo Issue #181

Issue: forgejo_admin/claude-custom #181 — Rename BoardItemType 'issue' to 'ticket' for semantic clarity
Reviewed by: Dottie (agent)
Date: 2026-03-27
Verdict: NEEDS_REFINEMENT

Template Compliance (template-issue-feature)

Section Present Status
Type Yes OK
Lineage Yes OK
Repo Yes INCOMPLETE — lists 3 repos, actually 4 affected
User Story Yes OK
Context Yes OK — good explanation of overloaded semantics
File Targets Yes INCOMPLETE — missing pal-e-mcp repo entirely (6 files)
Acceptance Criteria Yes INCOMPLETE — missing MCP tool description + test coverage
Test Expectations Yes INCOMPLETE — missing pal-e-mcp test commands
Constraints Yes OK
Checklist Yes INCOMPLETE — says 3 PRs, actually needs 4
Related Yes OK

Finding 1: Missing Repo — pal-e-mcp (CRITICAL)

The issue lists 3 repos: pal-e-docs, pal-e-docs-sdk, claude-custom. But the MCP server at ~/pal-e-mcp also contains references to "issue" as a board item type:
  • src/pal_e_mcp/tools/boards.py:180 — tool docstring: "Use item_type to categorise (plan, phase, issue, todo, repo, project)."
  • src/pal_e_mcp/tools/boards.py:181 — tool docstring: "For issue items, provide forgejo_issue_url."
  • tests/test_param_alignment.py:349,357,365,372,379 — 5 test cases passing item_type="issue"
This is a 4th repo that needs its own PR. The issue must be updated to include these file targets.

Finding 2: File Target Accuracy (VERIFIED)

All file targets listed for the 3 declared repos were verified against the filesystem:
  • pal-e-docs models.py:33-39 — CONFIRMED. BoardItemType enum has issue = "issue" at line 37.
  • pal-e-docs schemas.py:228 — CONFIRMED at line 232. BoardItemTypeType Literal includes "issue".
  • pal-e-docs schemas.py:262-268 — CONFIRMED at lines 265-271. BoardItemCounts has issue: int = 0 at line 268.
  • pal-e-docs routes/boards.py — CONFIRMED. Lines 395, 488, 602, 605 all reference issue item type.
  • pal-e-docs tests — CONFIRMED. 21 total occurrences across 3 test files (test_boards.py: 13, test_board_issue_sync.py: 7, test_pagination_activity.py: 1).
  • pal-e-docs-sdk boards.py:113 — CONFIRMED. Docstring says "issue items require".
  • pal-e-docs-sdk tests/test_boards.py — CONFIRMED. 6 references at lines 143, 145, 165, 167, 198, 205.
  • claude-custom hooks/check-board-item.sh — CONFIRMED. Line 53 has issue) case branch.
  • claude-custom skills/review-ticket/SKILL.md — CONFIRMED. Lines 27, 42 reference "issue" items.
  • claude-custom specs/review-ticket-design.md — CONFIRMED. Line 76 references "issue" items.
  • alembic historical migrations — CONFIRMED. Exist at expected paths. Issue correctly marks them as do-not-touch.
Line numbers are slightly off (e.g., schemas.py says line 228 but actual is 232; says 262-268 but actual is 265-271). These are close enough to be non-blocking but should be corrected for agent accuracy.

Finding 3: Cross-Repo Coordination (PARTIALLY DOCUMENTED)

The issue documents a deploy order: API first (with backward compat) → SDK → hooks/skills → remove backward compat. This is good. However:
  • The deploy order does not mention the MCP server, which sits between SDK and hooks/skills in the dependency chain.
  • Corrected deploy order: API → SDK → MCP → hooks/skills → remove backward compat.
  • The MCP server imports from the SDK, so it must be updated after the SDK but before hooks that invoke the MCP tools.

Finding 4: Backward Compatibility Plan (PRESENT, GOOD)

The issue explicitly describes a transition period where the API accepts both "issue" and "ticket" with a deprecation warning. This is well-thought-out for a breaking change. The deploy ordering is correct in principle but incomplete without the MCP repo.

Finding 5: Scope vs. 5-Minute Rule and 3-Thing Limit (NEEDS DECOMPOSITION)

This issue touches 4 repos and 27+ files. Per MEMORY.md rules:
  • feedback_five_minute_agent_rule.md — If agent runs >5 min, scope was too big.
  • feedback_three_thing_limit.md — If agent has >3 discrete changes, split into multiple agents.
  • feedback_smaller_scopes_parallel.md — One ticket = one agent = one PR.
Recommended decomposition into 4 tickets:
  • pal-e-docs (API server) — Enum rename, schema update, route updates, data migration, tests. ~12 files. This is the foundation and must land first. Includes backward compat shim.
  • pal-e-docs-sdk — Docstring update, test updates. ~2 files. Depends on ticket 1.
  • pal-e-mcp — Tool docstring update, test updates. ~2 files. Depends on ticket 2 (SDK import).
  • claude-custom — Hook case branch rename, skill doc updates, spec doc updates. ~3 files. Depends on ticket 3 (MCP tools are the interface hooks call).
Ticket 1 is the only one that might exceed 5 minutes due to the Alembic migration + backward compat shim. Consider splitting it further into (a) migration + enum + schema and (b) route + test updates. The other 3 tickets are clean, small, and can be dispatched sequentially per the dependency chain or in parallel once the API backward compat shim is live.

Finding 6: Minor Issues

  • The SKILL.md at line 27 lists incident as a valid item_type, but incident does not exist in the BoardItemType enum. This is pre-existing and unrelated to #181, but worth noting as discovered scope.
  • The checklist says "one per repo: pal-e-docs, pal-e-docs-sdk, claude-custom" — needs to add pal-e-mcp.
  • The issue is filed in claude-custom but the primary work is in pal-e-docs. Consider whether the parent issue should live in a coordination repo or if cross-references suffice.

Verdict: NEEDS_REFINEMENT

Blockers before moving to next_up:
  • Add pal-e-mcp (at ~/pal-e-mcp) to Repo section, File Targets, Test Expectations, and Checklist.
  • Update deploy order to include MCP server: API → SDK → MCP → hooks/skills.
  • Decompose into 4 per-repo tickets per the 5-minute rule and 3-thing limit. The current issue becomes the parent/epic; each repo gets its own actionable ticket.
  • Correct minor line number drift in file targets (non-blocking but improves agent accuracy).
Not blocking but worth tracking:
  • incident phantom item_type in review-ticket SKILL.md — file as discovered scope.