pal-e-docs

Review: feat: group kanban cards by phase within columns

review-1342-2026-06-06 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related

Traceability

  • [x] story:kanban label -- present on board item
  • [ ] story note MISSING -- project-paldocs user-stories section says "No user-story notes created yet." No story:kanban note exists. [SCOPE] Create user story entry for kanban on project-paldocs user-stories section.
  • [x] arch:rails-views label -- present on board item
  • [ ] arch note MISSING -- search for "arch-rails-views" returned no results. [SCOPE] Create architecture note arch-rails-views for component rails-views.
  • [x] Forgejo issue -- ldraney/paldocs#11, state: open

File Targets

  • [x] app/controllers/boards_controller.rb -- verified: exists (367 bytes), groups items by column via flat position ordering. Correct target for adding phase grouping logic.
  • [x] app/views/boards/show.html.erb -- verified: exists, iterates columns and renders cards in flat list. Correct target for phase group headers.
  • [x] app/views/board_items/_card.html.erb -- verified: exists, already renders labels. Correct target for phase badge styling.
  • [ ] app/assets/stylesheets/kanban.css -- ISSUE: File does not exist. All kanban CSS is in app/assets/stylesheets/application.css (lines 453-676). [BODY] Fix file path: app/assets/stylesheets/kanban.css should be app/assets/stylesheets/application.css.
  • [ ] app/javascript/controllers/kanban_controller.js -- ISSUE: NOT listed as a file target but MUST be modified. The Stimulus controller (200 lines) handles drag-and-drop using flat .kanban-column-body children. Phase grouping introduces nested containers that will break: (1) _dropPosition() which queries .kanban-card:not(.is-dragging) within the body, (2) the drop handler's DOM insertion via body.children[position], (3) tap-to-move position calculation in cardClick, (4) arrow-based reordering in moveUp/moveDown. [BODY] Add app/javascript/controllers/kanban_controller.js to File Targets with note: "Update drag-and-drop logic to work across phase group boundaries."

Repo Placement

OK -- issue filed on ldraney/paldocs, repo field says ldraney/paldocs, all file targets are in this repo.

Dependencies

No blocking dependencies found on board-paldocs. Item #1221 (Interactive kanban board -- drag-and-drop) is in done and is the predecessor. No other in-progress items conflict. The constraint "Must not break existing drag-and-drop Stimulus controller" is correct but the issue underestimates the required changes to that controller.

Acceptance Criteria

5 acceptance criteria -- at the threshold. Criteria are testable via manual verification. However:
  • "Drag-and-drop still works within and across phase groups" is underspecified -- does not acknowledge that the Stimulus controller needs modification to support grouped containers.
  • "Phase groups maintain correct ordering" -- unclear what ordering means (alphabetical? position-based? creation-order?).
  • Missing AC: What happens when a card is dragged from one phase group to another within the same column? Does the phase label update?

Blast Radius

The kanban Stimulus controller is the only drag-and-drop controller in the app. No sibling services are affected. The CSS changes are in the single application.css file. The main risk is breaking existing drag-and-drop functionality if the Stimulus controller changes are not carefully scoped.

Decomposition Assessment

4 file targets listed (should be 5 with kanban_controller.js), 5 acceptance criteria, all in 1 repo. The Stimulus controller modification is non-trivial (nested container support for drag-and-drop). Estimated agent work is within 5 minutes if the file targets and AC are corrected. No decomposition needed, but the scope must be tightened first.

Recommendations

  • [BODY] Fix file path: app/assets/stylesheets/kanban.css should be app/assets/stylesheets/application.css
  • [BODY] Add app/javascript/controllers/kanban_controller.js to File Targets with note: "Update drag-and-drop position calculation and DOM insertion to work across phase group boundaries"
  • [BODY] Clarify AC: "Phase groups maintain correct ordering" -- specify ordering rule (alphabetical, position-based, etc.)
  • [BODY] Add AC: specify behavior when dragging cards between phase groups within the same column
  • [SCOPE] Create user story entry for story:kanban on project-paldocs user-stories section
  • [SCOPE] Create architecture note arch-rails-views for component rails-views