pal-e-docs

Review: feat: render project page note content on project show page

review-1343-2026-06-06 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone
  • [x] Repo -- ldraney/paldocs
  • [x] User Story
  • [x] Context
  • [x] File Targets
  • [x] Acceptance Criteria
  • [x] Test Expectations
  • [x] Constraints
  • [x] Checklist
  • [x] Related
All required sections for Feature type are present.

Traceability

  • [x] story:project-pages label -- present on board item
  • [ ] story note MISSING -- [SCOPE] The user-stories section on project-paldocs says "No user-story notes created yet." Create user story entry for "project-pages" on project-paldocs user-stories section.
  • [x] arch:rails-views label -- present on board item
  • [ ] arch note MISSING -- [SCOPE] No arch-rails-views note found in pal-e-docs. Create architecture note arch-rails-views for the Rails views component.
  • [x] Forgejo issue -- ldraney/paldocs#12, state: open

File Targets

  • [x] app/controllers/projects_controller.rb -- verified: exists, show action loads @project with includes(:notes, :repos). Note: page_note is NOT eager-loaded; controller will need to add page_note to includes or use a separate query.
  • [x] app/views/projects/show.html.erb -- verified: exists, currently renders notes list and repos but no block content. Page note is not referenced anywhere in the view.
  • [x] app/views/blocks/_block.html.erb -- new partial to create (does not exist yet, correct)
  • [x] app/assets/stylesheets/blocks.css -- new stylesheet to create (does not exist yet, correct)
  • [x] app/models/block.rb -- verified: exists with belongs_to :note, correctly excluded from modification
  • [x] app/models/project.rb -- verified: belongs_to :page_note association exists, correctly excluded from modification
  • [x] app/models/note.rb -- verified: has_many :blocks association exists (not mentioned in issue but confirms feasibility)
  • [x] docs/data-model.md -- verified: exists, documents blocks table schema with block_type, content (json), anchor_id, position

Repo Placement

OK. Issue filed on ldraney/paldocs, all file targets are within paldocs. Single-repo change.

Dependencies

  • Item #1220 (done) -- "Project pages -- browse projects, view notes/repos/board link" -- the foundational feature that created the project show page. This is the predecessor and is complete.
  • Item #1344 (backlog) -- "feat: add Postgres trigger to bump projects.updated_at" -- shares story:project-pages label but is independent (DB trigger, not view layer). Not blocking.
  • Item #1342 (backlog) -- "feat: group kanban cards by phase within columns" -- shares arch:rails-views label but is a different feature. Not blocking.
  • No blocking dependencies found. Dependencies are not documented in the issue but none are needed.

Acceptance Criteria

9 acceptance criteria, all testable by an agent. Test commands are real (bin/rails test, manual URL visits). However:
  • AC for heading blocks says "h2/h3/h4 based on content.level" -- the pal-e-docs block format uses numeric levels (2, 3, 4). Agent can verify by reading list_blocks output. Testable.
  • AC for code blocks references "content.code or content.text" -- the data model uses "content" JSON field. Agent should verify actual field names from real block data. Minor ambiguity but acceptable.
  • No missing criteria detected. The 9 AC are comprehensive for the scope.

Blast Radius

  • The _block.html.erb partial is new and will only be rendered from the project show page. No downstream consumers.
  • No other views currently render blocks -- this is the first block-rendering code in the Rails app. Future features (e.g., note show pages) could reuse this partial.
  • The existing notes list and repos sections are below the new content per AC -- no risk of breaking existing layout if implemented correctly.
  • No html_safe or raw usage exists anywhere in current views -- this feature introduces the first use. The Constraints section appropriately warns about sanitization.

Decomposition Assessment

4 file targets (2 existing, 2 new) in 1 repo. 9 acceptance criteria. Estimated agent work: 3-5 minutes. The block partial has multiple sub-types (heading, paragraph, list, code, mermaid, table) but they are all in a single file with a case/when pattern. Within the 5-minute threshold. No decomposition needed.

Recommendations

  • [BODY] Add note to File Targets: "The controller's show action currently does includes(:notes, :repos) but does NOT include :page_note. The agent should add :page_note to the includes call or load blocks via a separate query to avoid N+1."
  • [SCOPE] Create user story entry for "project-pages" on project-paldocs user-stories section.
  • [SCOPE] Create architecture note arch-rails-views for the Rails views component.