pal-e-docs

Review: Repoint MCP + deprecate pal-e-docs

review-1563-2026-06-22 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- depends on paldocs#51, paldocs#52
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- well-formed As/I want/So that
  • [x] Context -- clear motivation
  • [x] File Targets -- present (but incomplete, see below)
  • [x] Feature Flag -- "none" with rollback rationale
  • [x] Acceptance Criteria -- 5 criteria present
  • [x] Test Expectations -- manual verification described
  • [x] Constraints -- rollback plan, human gate for archive
  • [x] Checklist -- present
  • [x] Related -- upstream deps and affected repos listed

Traceability

  • [x] story:consolidation label -- present on board item
  • [ ] story note MISSING -- project-paldocs user-stories section lists only: kanban, project-pages, auth. No "consolidation" story entry. [SCOPE] Create user story entry "story-paldocs-consolidation" on project-paldocs user-stories section.
  • [x] arch:infra label -- present on board item
  • [ ] arch note MISSING -- search for "arch-infra" returned zero results in pal-e-docs. [SCOPE] Create architecture note arch-infra for the infra component.
  • [x] Forgejo issue -- paldocs#53, state: open

File Targets

  • [x] ~/.mcp.json -- verified: file exists, contains PALDOCS_BASE_URL pointing to https://pal-e-docs.tail5b443a.ts.net
  • [x] ~/claude-custom/docs/mcp-servers.md -- verified: file exists (7.8k)
  • [x] ~/claude-custom/docs/operations.md -- verified: file exists (5.0k)
  • [ ] MISSING: 29 additional files in ~/claude-custom/ reference "pal-e-docs" -- agents (dev.md, qa.md, overseer.md), skills (8 SKILL.md files), hooks (15 scripts), settings.json, settings.local.json, plus 6 more docs files (agents.md, enforcement.md, settings.md, skills.md, hooks.md, filetree.md). Issue only lists 2 doc files as targets.
  • [ ] MISSING: ~/pal-e-mcp/ -- server.py, pyproject.toml, README.md, and all tool module docstrings reference "pal-e-docs". Issue says "do not touch" but docstrings and README will be stale after cutover.
  • [ ] MISSING: ~/pal-e-services/terraform/cnpg.tf -- has pal-e-docs DB credential secret comment
  • [x] ~/pal-e-mcp/ listed as "do not touch" for code -- correct, only env var changes
  • [x] ~/pal-e-docs/ listed as "do not touch" -- correct, archived not modified

Repo Placement

Issue filed on ldraney/paldocs but actual changes span 4 repos:
  • ~/.mcp.json -- local config, not repo-tracked (OK)
  • ~/claude-custom/ -- separate repo (ldraney/claude-custom), 29+ files affected
  • ~/pal-e-services/ -- separate repo (k8s teardown via tofu, cnpg.tf cleanup)
  • ~/pal-e-mcp/ -- separate repo (README/docstring updates for accuracy)
Multi-repo scope is acknowledged in the issue ("Affects: pal-e-mcp, claude-custom docs") but the file targets section severely understates the work in claude-custom. With 29+ files across 4 repos, this needs per-repo sub-tickets.

Dependencies

  • paldocs#51 (API endpoints, board item #1561) -- backlog, open. HARD blocker. Rails must serve the full REST surface before MCP can repoint.
  • paldocs#52 (Embedding pipeline, board item #1562) -- backlog, open. HARD blocker. Semantic search must work in Rails before cutover.
  • Both upstream dependencies are wave:2; this ticket is wave:3. Ordering is correct.
  • This ticket blocks nothing on the board currently, but it effectively gates the deprecation of the pal-e-docs project.

Acceptance Criteria

  • [x] AC1: "14 MCP tools return correct results from Rails" -- testable via manual MCP calls
  • [x] AC2: "semantic_search matches previous FastAPI behavior" -- testable
  • [x] AC3: "pal-e-docs k8s namespace has no pods" -- testable via kubectl
  • [x] AC4: "pal-e-docs Forgejo repo is archived" -- testable via Forgejo API
  • [ ] AC5: "claude-custom docs reflect Rails monolith" -- too vague. Should specify all 8 docs files, CLAUDE.md/README.md, plus 21 agent/skill/hook files that reference pal-e-docs.
  • [ ] MISSING AC: "No hooks or skills reference stale pal-e-docs URLs or names after update" -- 29 files need audit
  • [ ] MISSING AC: "pal-e-mcp README and docstrings reflect new architecture"

Blast Radius

Critical finding: The ticket lists 3 file targets but the actual blast radius is far larger:
  • claude-custom docs/: 8 files, 38 references to "pal-e-docs"
  • claude-custom hooks/: 15 hook scripts (block-docs-writes.sh alone has 23 references)
  • claude-custom agents/: 3 agent definitions (overseer.md: 11 refs, qa.md: 6, dev.md: 2)
  • claude-custom skills/: 8 skill files
  • claude-custom settings: settings.json (4 refs), settings.local.json (1 ref)
  • pal-e-mcp/: server.py, pyproject.toml, README.md, 7 tool modules with docstrings
  • pal-e-services/: terraform/cnpg.tf (DB credentials secret)
Key scoping question: many references use "pal-e-docs" as the MCP server name (e.g., mcp__pal-e-docs__get_note in settings.json). The ticket must decide: rename the MCP server from "pal-e-docs" to "paldocs" everywhere (breaking change for all tool references), or keep the legacy name with a new backend URL? This decision drives whether the blast radius is 3 files (URL swap only) or 50+ files (full rename).

Decomposition Assessment

NEEDS DECOMPOSITION -- fails the 5-minute rule on all three dimensions:
  • File count: 30+ files across 4 repos -- far exceeds the >3 files / >2 repos threshold
  • AC count: 5 stated + 2 missing = 7 -- exceeds >5 threshold
  • Estimated agent time: well beyond 5 minutes for a single pass
Suggested sub-ticket decomposition:
  • Repoint PALDOCS_BASE_URL and verify 14 MCP tools (~/.mcp.json swap + manual verification)
  • Update claude-custom docs (8 files, 38 references)
  • Update claude-custom hooks/agents/skills/settings (21 files, rename decision required)
  • Remove pal-e-docs k8s deployment (pal-e-services tofu)
  • Archive pal-e-docs Forgejo repo (human-gated)
  • Update pal-e-mcp README and docstrings

Recommendation

  • [SCOPE] Create user story note story-paldocs-consolidation and add entry to project-paldocs user-stories section.
  • [SCOPE] Create architecture note arch-infra for the infra component.
  • [BODY] Add missing file targets: the 29 files in claude-custom (hooks, agents, skills, settings) plus pal-e-mcp README/docstrings plus pal-e-services terraform.
  • [BODY] Add missing AC: "No hooks or skills reference pal-e-docs incorrectly after update" and "pal-e-mcp README reflects new architecture."
  • [BODY] Add scoping decision to Context section: rename MCP server from "pal-e-docs" to "paldocs" everywhere, or keep legacy name with new URL?
  • [DECOMPOSE] 30+ files across 4 repos, 7 AC -- route to skill-decompose-ticket. Suggested 6 sub-tickets above.