pal-e-docs

Review: Sprint schema -- migrations + models for sprint tracking

review-1560-2026-06-23 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- present, references paldocs#49
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- present
  • [x] Context -- present, includes wave_number removal rationale
  • [x] File Targets -- present, 7 files listed (3 migrations, 4 models)
  • [x] Feature Flag -- none (correct, internal model change)
  • [x] Acceptance Criteria -- 5 criteria
  • [x] Test Expectations -- 4 test items + run command
  • [x] Constraints -- present
  • [x] Checklist -- present
  • [x] Related -- present
All required sections for template-issue-feature are present.

Traceability

  • [x] story:sprint-orchestration label -- present on board item
  • [x] story note verified -- story-paldocs-sprint-orchestration exists in pal-e-docs (note_type: user-story, project: paldocs). Listed in project-paldocs user-stories section.
  • [ ] story note STALE -- story note title says "cross-project wave planning UI" and acceptance criteria reference "named waves" and "Wave view" -- contradicts the revised sprint philosophy (sprints are flat parallel batches, no waves). [SCOPE] Update story-paldocs-sprint-orchestration to remove all wave references.
  • [x] arch:rails-db label -- present on board item
  • [ ] arch note MISSING -- arch-rails-db does not exist in pal-e-docs. Search returned zero results. [SCOPE] Create architecture note arch-rails-db for the Rails database schema component.
  • [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/paldocs/issues/50 -- open

File Targets

  • [x] db/migrate/XXXXXX_create_sprints.rb -- new file, does not exist yet (correct)
  • [x] db/migrate/XXXXXX_create_sprint_projects.rb -- new file, does not exist yet (correct)
  • [x] db/migrate/XXXXXX_add_sprint_id_to_board_items.rb -- new file, does not exist yet (correct)
  • [x] app/models/sprint.rb -- new file, does not exist yet (correct)
  • [x] app/models/sprint_project.rb -- new file, does not exist yet (correct)
  • [x] app/models/board_item.rb -- verified exists at /home/ldraney/paldocs/app/models/board_item.rb. Currently has basic COLUMNS constant and board association. Sprint association addition is valid.
  • [x] app/models/project.rb -- verified exists at /home/ldraney/paldocs/app/models/project.rb. Currently has notes, repos, and page_note associations. Sprint association addition is valid.
Exclusions (db/structure.sql, controllers, views) are sensible.
Note: No structure.sql exists in the repo. The app uses schema_format = :sql style inherited from the shared DB. The spec should clarify whether rails db:migrate generates structure.sql or schema.rb -- agent needs to know which schema dump format is in use.

Repo Placement

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

Dependencies

  • paldocs#49 (schema ownership transfer) -- CLOSED/MERGED. Dependency satisfied. Board item #1559 is in done column.
  • paldocs#56 (sprint planning UI) -- DOWNSTREAM, depends on this ticket. Open, in backlog. No blocking issue.
  • paldocs#67 (docs: codify sprint philosophy) -- RELATED, in next_up. Should be done in parallel or before this to formalize the no-waves decision.
  • paldocs#52 (embedding pipeline) -- in next_up, same sprint:1. No dependency relationship. Can run in parallel.

Acceptance Criteria

5 acceptance criteria. All are testable via Rails console or RSpec model specs. Run command (bundle exec rspec) is real. No missing criteria detected.
The criteria correctly test only the model/schema layer without touching UI concerns. Good separation from #56.

Blast Radius

Low. New tables and new model files. The only modification to existing models is adding associations to BoardItem and Project. No existing functionality is altered. The board_items table modification (adding nullable sprint_id FK) is additive-only.
No similar patterns in sibling services -- this is the first sprint schema in the codebase.

Decomposition Assessment

7 file targets, 1 repo, 5 AC, ~3-4 minutes estimated agent time. This is within the 5-minute rule. Three new migrations + two new models + two model updates is a single coherent unit. No decomposition needed.

Recommendation

  • [BODY] Board item title on board-paldocs says "Sprint schema -- migrations + models for wave planning" but the spec removed waves. Update board item title to match the revised Forgejo issue title: "Sprint schema -- migrations + models for sprint tracking".
  • [SCOPE] Create architecture note arch-rails-db for the Rails database schema component. This arch label is used by multiple board items (#1388, #1344, #1559, #1560).
  • [SCOPE] Update story-paldocs-sprint-orchestration to remove wave references. Title says "cross-project wave planning UI", acceptance criteria reference "named waves" and "Wave view". These contradict the revised sprint philosophy (flat parallel batches, no waves).
  • [BODY] Clarify schema dump format in Constraints section -- does the project use schema_format = :sql (structure.sql) or :ruby (schema.rb)? No schema dump file exists currently. The agent needs to know which format to expect after rails db:migrate.