pal-e-docs

Review: Add schema.rb drift check to dev agent workflow

review-1779-2026-07-04 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — present, references S7 QA of PR #96
  • [x] Repo — ldraney/prediction-assistant
  • [x] User Story — present
  • [x] Context — present, clear explanation of the drift problem
  • [x] File Targets — present but vague (see below)
  • [x] Feature Flag — None (correct, documentation-only change)
  • [x] Acceptance Criteria — present, 3 items
  • [x] Test Expectations — present (no code tests needed)
  • [x] Constraints — present, sensible guardrails
  • [x] Checklist — present
  • [x] Related — present, references PR #96 and PR #75

Traceability

  • [ ] story:bot-marketplace label — WRONG STORY. This is a dev agent process improvement discovered during QA. It has no relationship to the bot-marketplace user story ("User activates first bot within 2 minutes of login"). The discovery context (issue #88) was story:portfolio-builder work, and the fix is foundational process improvement. [LABEL] Change to story:platform-setup or remove (foundational work, acceptable without story).
  • [ ] story note verification — bot-marketplace exists on project-prediction-assistant user-stories section, but the label itself is wrong per above.
  • [ ] arch:rails label — present, but no backing architecture note found. search_notes("arch-rails") returned empty. [SCOPE] Create architecture note arch-rails for the Rails component.
  • [x] Forgejo issue — ldraney/prediction-assistant#99, open

File Targets

  • [ ] "CLAUDE.md or agent-workflow pal-e-docs note" — ISSUE: Vague. CLAUDE.md in prediction-assistant is a symlink to README.md (a docs index, not an instructions file). There is no project-level .claude/CLAUDE.md. No agent-workflow note exists in pal-e-docs (search returned empty). The ticket must specify which file and where. [BODY] Specify exact target: either create a .claude/CLAUDE.md in prediction-assistant with the schema check, or add a Rails enforcement section to ~/.claude/agents/dev.md (lives in claude-custom repo).
  • [ ] "Dev agent type definition (if applicable)" — ISSUE: Vague. The dev agent definition exists at ~/.claude/agents/dev.md in the claude-custom repo (not prediction-assistant). It already has domain-specific enforcement sections (Infrastructure, Python) where a "Rails Enforcement" section with the schema.rb check would fit naturally. [BODY] Clarify: ~/.claude/agents/dev.md in ldraney/claude-custom repo.

Repo Placement

Issue is filed on ldraney/prediction-assistant, but the most impactful fix location is ~/.claude/agents/dev.md which lives in the ldraney/claude-custom repo. If the fix only goes in prediction-assistant's CLAUDE.md, it is too narrow — there are 7 Rails projects with schema.rb files (prediction-assistant, westside-basketball, flightscanner, pal-enterprises, palinks, landscaping-assistant, believers-elite) that would all benefit from the check. Adding a "Rails Enforcement" section to dev.md (global) would cover all repos. [BODY] Clarify repo placement: if dev.md in claude-custom is the target, file the issue there or document that the fix is cross-repo.

Dependencies

No blockers found. This is a standalone process improvement. No board items are blocking or blocked by this ticket.

Acceptance Criteria

3 acceptance criteria, all reasonable:
  • AC1: "Dev agents diff schema.rb against the base branch before committing" — testable but lacks specificity on implementation mechanism (guideline in CLAUDE.md? section in dev.md? a hook?). The Constraints section says "guideline, not a blocking hook" which helps.
  • AC2: "If unrelated changes detected, regenerate from clean db:schema:load && db:migrate cycle" — clear recovery procedure, testable.
  • AC3: "Document the check in the dev agent workflow" — testable but vague on location (matches the file targets vagueness).

Blast Radius

7 Rails repos with schema.rb: prediction-assistant, westside-basketball, flightscanner, pal-enterprises, palinks, landscaping-assistant, believers-elite. A global fix in dev.md benefits all. A project-scoped fix in prediction-assistant only benefits one repo. No downstream consumers affected — this is documentation only.

Decomposition Assessment

1 point, 2-3 file targets (documentation only), 3 acceptance criteria. Estimated agent work well under 5 minutes. No decomposition needed.

Recommendation

  • [LABEL] Change story:bot-marketplace to story:platform-setup (or remove story label — foundational process work is acceptable without a user story).
  • [SCOPE] Create architecture note arch-rails for the Rails component in pal-e-docs.
  • [BODY] Resolve file target ambiguity: specify whether the fix goes in (a) ~/.claude/agents/dev.md as a "Rails Enforcement" section (global, covers all 7 Rails repos, lives in claude-custom repo), or (b) prediction-assistant/.claude/CLAUDE.md (project-scoped, narrow). Option (a) is recommended given 7 affected repos.
  • [BODY] If option (a), update the Repo field to ldraney/claude-custom or note that the fix is cross-repo. If option (b), create the .claude/CLAUDE.md file path since it does not currently exist.