pal-e-docs

Review: docs: update docs/ for consolidation and codify sprint philosophy

review-1571-2026-06-22 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type -- Feature
  • [x] Lineage -- present
  • [x] Repo -- ldraney/paldocs
  • [x] User Story -- present
  • [x] Context -- thorough, explains both stale docs and sprint philosophy
  • [x] File Targets -- present (but inaccurate, see below)
  • [x] Feature Flag -- none, docs-only, appropriate
  • [x] Acceptance Criteria -- 5 criteria, all clear
  • [x] Test Expectations -- 2 items, appropriate for docs
  • [x] Constraints -- present
  • [x] Checklist -- present
  • [x] Related -- present

Traceability

  • [x] story:sprint-orchestration label -- present on board item
  • [x] story note verified -- story-paldocs-sprint-orchestration found in project-paldocs user-stories section
  • [ ] arch:docs label -- present on board item
  • [ ] arch note MISSING -- [SCOPE] No arch-docs note found in pal-e-docs. Create architecture note arch-docs for the docs component.
  • [x] Forgejo issue -- ldraney/paldocs#67, open

File Targets

  • [x] README.md -- verified: exists at /home/ldraney/paldocs/README.md. Line 79 has stale claim "No Rails-managed migrations". Line 20 references pal-e-docs FastAPI as coexisting. Architecture section needs update.
  • [ ] docs/shared-database.md -- ISSUE: File does NOT exist. The actual file is docs/data-model.md which contains the stale shared-database conventions (line 3: "Tables are managed externally", line 134: "table DDL is managed by the FastAPI pal-e-docs service").
  • [ ] docs/architecture.md -- ISSUE: File does NOT exist. The actual files are docs/infrastructure.md (deployment/CI architecture) and docs/auth-visibility-architecture.md (auth/visibility design). Infrastructure.md line 61 has stale reference to "external shared database managed by the pal-e-docs FastAPI service".
  • [x] docs/sprint-philosophy.md -- verified: does NOT exist yet (expected, ticket says NEW).

Repo Placement

OK. Issue filed on ldraney/paldocs, all file targets are in the paldocs repo. No cross-repo changes needed -- docs-only change.

Dependencies

  • Upstream (completed): paldocs#49 (schema ownership transfer) -- merged as PR #60. This is what created the stale docs.
  • Downstream: paldocs#50 (sprint schema) is in next_up -- the sprint philosophy doc from this ticket should inform #50's design. No hard blocker, but logical ordering is correct.
  • No blockers from in_progress items.

Acceptance Criteria

5 acceptance criteria. All are verifiable by grep/read. However:
  • AC2 says "docs/shared-database.md removed or replaced with docs/database.md" but the file is actually docs/data-model.md. The AC should reference the correct filename.
  • AC3 says "docs/architecture.md reflects Rails as sole owner" but docs/architecture.md does not exist. The stale references are in docs/infrastructure.md and docs/auth-visibility-architecture.md.
  • AC5 "No stale references to Alembic or pal-e-api schema ownership" is good -- grep confirmed stale references in 4 files (data-model.md, infrastructure.md, auth-visibility-architecture.md, README.md).

Blast Radius

Stale references found in 4 files total:
  • README.md -- line 79 (no Rails migrations), line 12 (shared database conventions link text), line 20 (pal-e-docs FastAPI coexists)
  • docs/data-model.md -- lines 3, 134-137 (schema managed externally, no DDL)
  • docs/infrastructure.md -- lines 56, 61 (shared database, pal-e-docs FastAPI manages)
  • docs/auth-visibility-architecture.md -- lines 7, 55, 58, 61, 67, 126-128, 196, 206-207 (extensive references to pal-e-docs as schema owner, Alembic migrations)
The auth-visibility doc has the most stale references (12+ lines) and may need significant rewriting to reflect Rails ownership of schema changes.

Decomposition Assessment

4 file targets (README + 3 docs files), 5 acceptance criteria. All within a single repo. Estimated agent work: 3-5 minutes for a docs-only change. No decomposition needed.

Recommendation

  • [BODY] Fix file path: docs/shared-database.md does not exist. The correct file is docs/data-model.md. Update File Targets section to reference docs/data-model.md instead.
  • [BODY] Fix file path: docs/architecture.md does not exist. The actual files with stale references are docs/infrastructure.md and docs/auth-visibility-architecture.md. Update File Targets to reference both.
  • [BODY] Update AC2: reference docs/data-model.md instead of docs/shared-database.md.
  • [BODY] Update AC3: reference docs/infrastructure.md and docs/auth-visibility-architecture.md instead of docs/architecture.md.
  • [BODY] Add docs/auth-visibility-architecture.md to File Targets -- it has 12+ stale references to pal-e-docs as schema owner / Alembic migrations.
  • [SCOPE] Create architecture note arch-docs in pal-e-docs for the docs component.