pal-e-docs

Review: Scaffold Rails 8 app + data model

review-1329-2026-06-05 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- Standalone
  • [x] Repo -- ldraney/lil-beasties
  • [x] User Story -- present
  • [x] Context -- present, thorough
  • [x] File Targets -- 12 files listed
  • [x] Acceptance Criteria -- 11 criteria
  • [x] Test Expectations -- 4 test items + run command
  • [x] Constraints -- present
  • [x] Checklist -- present
  • [x] Related -- present

Traceability

  • [x] story:collect label -- Collect Monsters
  • [x] story entry on project-lil-beasties user-stories table -- "collect" row exists, links to story-lil-beasties-collect
  • [ ] story note MISSING -- story-lil-beasties-collect note does not exist in pal-e-docs. [SCOPE] Create story note story-lil-beasties-collect.
  • [x] arch:rails-monolith label -- Rails monolith component
  • [ ] arch note MISSING -- no arch-rails-monolith note found in pal-e-docs. [SCOPE] Create architecture note arch-rails-monolith.
  • [x] Forgejo issue -- https://forgejo.tail5b443a.ts.net/ldraney/lil-beasties/issues/1, open

File Targets

  • [x] All 12 file targets are new files to create -- repo currently contains only README.md. Greenfield scaffold, no existing-file verification needed.
  • [ ] Dockerfile -- ISSUE: rails-base/docs/starting-a-new-project.md says "No Dockerfile needed for dev" and uses docker compose with a pre-built ruby-rails-build image from Harbor. If the ticket intends a production Dockerfile, this needs clarification. [BODY] Clarify whether Dockerfile is for production only, or remove if dev uses docker-compose with base image.

Repo Placement

OK -- Forgejo issue filed on ldraney/lil-beasties, ticket targets same repo. Single-repo scope.

Dependencies

  • No blocking dependencies -- this is the first ticket on the board (standalone, foundational).
  • Board item #1330 (Integrate Phaser 4 + first island scene) depends on this ticket -- it needs the Rails app and islands#show view to mount Phaser onto.
  • Board item #1332 (Keycloak auth integration) depends on this ticket -- the issue references "auth wiring comes in #4, stub for now."
  • Dependencies are implicitly documented in the constraints section ("Root route must redirect to login if unauthenticated (auth wiring comes in #4, stub for now)") but not explicitly listed as blocked-by/blocks relationships.

Acceptance Criteria

  • Criteria are concrete and verifiable by an agent.
  • "App boots and passes rails test" is a real, runnable command.
  • However: AC says "Multi-database configured: primary + solid_cache + solid_queue + solid_cable" but the rails-base multi-database doc shows this as a production-only concern. Dev uses a single database. The AC should clarify this is production config only.

Blast Radius

  • Greenfield project -- no existing consumers affected.
  • Constraint conflict: ticket says "Use SQLite for dev, PostgreSQL for prod" but rails-base pattern uses PostgreSQL for both dev and prod via docker-compose. The docker-compose.yml in rails-base runs a PostgreSQL container for dev. Using SQLite for dev would diverge from the platform standard and could cause dev/prod parity issues. [BODY] Resolve database conflict: align with rails-base pattern (PostgreSQL for dev via docker-compose) or document why SQLite is preferred for this project.

Decomposition Assessment

  • 12 file targets in 1 repo
  • 11 acceptance criteria
  • 4 test expectations
  • Estimated agent work: well beyond 5 minutes -- generating a full Rails app, creating 5 models with migrations, seeds, routes, controller, view, Dockerfile, and database config is substantial.
  • However: this is a rails new scaffold + model generation. Most file targets are generated by rails commands (rails new, rails generate model), not hand-written. The agent workflow is sequential: generate app, generate models, configure routes, write seeds. This can be done in a single focused pass if the agent runs rails generators inside docker compose.
  • Recommendation: borderline. The high file/AC count is inflated because rails new generates most of them. A skilled agent running generators can complete this in one pass. No decomposition needed IF the scope conflicts below are resolved first.

Recommendations

  • [SCOPE] Create story note story-lil-beasties-collect in pal-e-docs -- the project user-stories table links to it but it does not exist.
  • [SCOPE] Create architecture note arch-rails-monolith in pal-e-docs -- the board item has the label but no backing note.
  • [BODY] Resolve database conflict in Constraints section: ticket says "Use SQLite for dev" but rails-base platform pattern uses PostgreSQL for dev via docker-compose. Pick one and update the ticket.
  • [BODY] Clarify Dockerfile file target: rails-base says "No Dockerfile needed for dev" and uses a pre-built Harbor image. If this is a production Dockerfile, label it as such. If not needed, remove from file targets.
  • [BODY] Clarify multi-database AC: specify this is production config; dev uses single database per rails-base/docs/multi-database.md.