pal-e-docs

Review: Communications tab (admin): incoming management

review-1827-2026-07-25 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage
  • [x] Repo
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Feature Flag -- "None" (core admin view, appropriate)
  • [x] Acceptance Criteria (8 items)
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
  • [x] Dependencies (bonus section, well-documented)
All required template sections are present and filled in.

Traceability

  • [x] story:communications label -- present on board item
  • [ ] story note MISSING -- [SCOPE] The key communications does not appear in the project-iss user-stories section. The table lists messaging (Epic 4: DM threads) but not communications (the admin inbox/contact tab). Create a communications user story entry on project-iss user-stories section, or reconcile with the existing messaging key.
  • [x] arch:rails label -- present on board item
  • [x] arch note verified -- arch-rails note exists in pal-e-docs (ISS Rails Architecture)
  • [x] Forgejo issue -- #57, state: open, valid URL

File Targets

  • [x] app/controllers/communications_controller.rb -- verified: exists, admin branch already renders :admin_index at line 15-16. Controller needs data loading added.
  • [x] app/views/communications/admin_index.html.erb -- verified: exists as placeholder. Line 27 references "Coming soon -- see ticket #57." Ready to replace.
  • [x] app/views/communications/_inbox_card.html.erb -- does not exist yet (new partial to create). Expected per ticket scope.
  • [x] app/assets/stylesheets/communications.css -- verified: exists (3.3k), will receive inbox styling additions.
All existing file targets verified. New partial creation is expected.

Repo Placement

OK -- issue filed on ldraney/intelligentstaffingsystems, all file targets are in the same repo. No cross-repo work needed.

Dependencies

  • #54 (Appointment scheduling) -- board item #1824, column: validation (merged, awaiting validation). Ticket correctly handles this as a soft dependency: "scope the inbox to DM cards only; appointment display is additive."
  • #55 (Live DM / block lead role from DM) -- board item #1825, column: validation. Provides message data for inbox cards. The Message model exists with belongs_to :lead and scopes (chronological, reverse_chronological, for_lead).
  • #52 (Communications tab lead/client) -- board item #1822, column: done. Prerequisite is satisfied.
  • #56 (CRM tab) -- board item #1826, column: todo. No blocking dependency; CRM is a parallel admin view.
Dependencies are well-documented and the soft dependency on #54 is handled gracefully.

Acceptance Criteria

8 acceptance criteria, all verifiable via endpoint tests:
  • AC 1-3: Admin inbox view rendering with card content -- directly testable with assert_select
  • AC 4: Filter (All / DMs / Appointments) -- testable; appointments filter gracefully degrades
  • AC 5-7: Quick actions (DM thread, appointment details, CRM) -- testable as link presence
  • AC 8: Lead/client still sees contact buttons -- already partially tested (existing test at line 49 checks for 3 contact cards)
Test expectations align with ISS testing strategy (endpoint-first, Minitest, Keycloak stubs). Run command is correct: rails test test/controllers/communications_controller_test.rb. Existing test file already has admin and role-specific tests to extend.

Blast Radius

Low risk. The admin branch pattern (admin? helper, render :admin_index) is already established in the communications controller. The Message model (belongs_to :lead, scopes) and Appointment model (belongs_to :lead, upcoming/recent scopes) have the necessary associations and query methods. The Lead model has has_many :messages and has_many :appointments. No changes to existing models or other controllers are needed.

Decomposition Assessment

  • 4 file targets, 1 repo -- does NOT exceed the >3 files across >2 repos threshold
  • 8 acceptance criteria -- exceeds the >5 AC threshold
  • Estimated agent work: 5-8 minutes (replace placeholder view, create partial, add controller data loading, add CSS)
The AC count exceeds the formal threshold. However, the work is cohesive (one view with supporting parts in a single repo) and per standing directive, inclusive tickets are preferred over decomposition. No decomposition recommended.

Recommendation

  • [SCOPE] Create user story entry for communications on project-iss user-stories section. The key is used on multiple board items (#52 done, #54 validation, #57 todo) but has no backing entry in the project page. Suggested row: Key=communications, Backing="Epic 4 (US-4.3)", Role="Admin", Success metric="Admin sees unified inbox of DMs and appointments; leads/clients see contact cards"