pal-e-docs

Review: #23 Amend user-stories + architecture (decomp:1800)

review-1806-2026-07-05 Review

review ready
Project

Verdict: READY

Board item 1806 (board-iss), Forgejo issue ldraney/intelligentstaffingsystems#23, 2 points. Decomposition child of #19 (parent item 1800, tracking-only per review-1800-2026-07-05). Scope is tight and fully executable: two amend-in-place file targets verified on main, spec section in docs/adoption-plan.md matches the issue Context nearly verbatim, all planned additions confirmed absent from the current docs, and the Delivery Phases constraint is backed by sprint labels verified on the Forgejo issues themselves.

Template Completeness (Feature template)

  • [x] Type — Feature (routes to template-issue-feature)
  • [x] Lineage — child of #19, names review-1800-2026-07-05 and the spec doc + section
  • [x] Repo — ldraney/intelligentstaffingsystems
  • [x] User Story
  • [x] Context — full per-doc content spec inlined (matrix actions, phases, open questions, KDD list)
  • [x] File Targets — modify list + do-not-touch list ("All other docs — sibling tickets own them")
  • [x] Feature Flag — "none"; correct (docs-only; repo has no docs/feature-flags.md yet)
  • [x] Acceptance Criteria — 5 checkboxes
  • [x] Test Expectations — manual render + link check, run command N/A (appropriate for docs-only; same pattern accepted in review-1800)
  • [x] Constraints — amend-in-place; Delivery Phases must match sprint labels, not invent a plan
  • [x] Checklist
  • [x] Related — project slug + parent
All 12 sections present. No template gaps.

Traceability

  • [x] story:project-setup label — present on board item 1806
  • [x] story note verified — project-iss user-stories section exists (gap from review-1800 has been fixed); row project-setup present, backed by "README + docs/architecture.md + docs/adoption-plan.md"
  • [x] arch:docs label — present on board item 1806; taxonomy-valid
  • [x] arch note found — search_notes("arch-docs") returns note arch-docs ("Architecture: Documentation"). Caveat: that note is scoped to project westside-basketball, not ISS. Advisory only — see Recommendation; this is the same board-wide platform gap review-1800 already flagged, not a defect of this ticket's scope.
  • [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/ldraney/intelligentstaffingsystems/issues/23, open, label sprint:0 (full label set lives on the board item, same pattern as #19)

File Targets

Verified against origin/main.
  • [x] docs/user-stories.md (modify) — exists on main. Current structure: Roles / Client Journey / Epics 1–6 / Role-Tab Access Matrix. All six planned additions are genuinely new: grep for "permission matrix|delivery phase|open question|related ticket|persona|default tab" hits only "personalized" in US-2.2 (false positive). The Role-Tab Access Matrix (4 tabs x 3 roles, lead/client/admin) exists at the doc's tail — AC4's consistency anchor is real, and the ≥12-action permission matrix is a genuine extension of it, matching the plan's "~15 actions" estimate.
  • [x] docs/architecture.md (modify) — exists on main; no "Key Design Decisions" or "Rails Structure" headings anywhere. The issue supplies 6 KDDs (mirroring the plan's list), so the ≥5 AC is achievable. "Rails Structure" stub correctly defers content to scaffold ticket #3.
  • [x] Spec alignment — docs/adoption-plan.md "Amendments to existing docs" section exists on main and matches the issue Context item-for-item (matrix actions, Delivery Phases mirroring the sprint map, the same 4 Open Questions, Related Tickets #3–#18, default tab per role, personas; the same 6 KDDs and Rails Structure stub).
  • [x] Do-not-touch list — correct: siblings own docs/security.md (#20), docs/pipeline.md (#21), testing-strategy + local-dev-setup (#22), README + plan status (#24). No overlap with this ticket's targets.

Repo Placement

OK. Single-repo docs work; the issue is filed on the repo it modifies. Neither README.md nor CLAUDE.md is touched (those belong to closer #24), so no symlink propagation concerns here.

Dependencies

Blocked by: nothing. Item 1780 (#1), which created both target docs, is merged to main (files verified present) and sits in validation. No items in in_progress touch these files.
Blocks: sibling #24 (item 1807, "Docs closer: README + plan status") carries blocker:siblings — it waits on this ticket and #20–#22. Documented board-side via that label.
Parallel-safe: siblings #20/#21/#22 target disjoint files; all five children share parent #19 (tracking-only, labeled decomposed).
Inputs verified: Delivery Phases constraint requires sprint labels on the Forgejo issues — spot-checked Forgejo-side: #3=sprint:1, #10=sprint:3, #18=sprint:6, #19/#24=sprint:0; board mirrors sprint:1–6 across #3–#18 and sprint:0 on the docs children. AC4 requires issues #6–#16 as input — all exist on board-iss (items 1786–1796).

Acceptance Criteria

All 5 criteria objectively verifiable by an agent: (1) section presence + matrix size ≥12x3, Open Questions ≥4 — countable; (2) numbered KDDs ≥5 + Rails Structure stub — countable; (3) "no existing content removed" — verifiable by diff against main; (4) permission matrix consistency with the Role-Tab Access Matrix (verified to exist) and issues #6–#16 (verified to exist) — enumerable; (5) mermaid renders + links resolve — manual, honestly declared as such in Test Expectations. No fake test commands. AC count is exactly at the 5-AC threshold, not over it.

Blast Radius

Docs-only; no code or config. Two couplings worth noting: (1) sibling #20's docs/security.md Controller Role Map derives from the same role semantics as this ticket's Role Permission Matrix — both must source issues #6–#16 as ground truth to stay consistent if worked in parallel; (2) the Delivery Phases section becomes a second place sprint assignments are written down — the constraint correctly forces it to mirror the labels rather than fork a new plan. README's Documentation table already links both target docs, so no README edit is needed (and #24 owns README anyway).

Decomposition Assessment

No decomposition needed. 2 file targets in 1 repo (rule: >3 across >2 repos — not tripped); 5 ACs (rule: >5 — not tripped); estimated agent work fits a single pass — all content is pre-specified in adoption-plan.md and the issue Context, inputs are the two docs plus board/issue labels, no research or authoring-from-scratch. This ticket is one of the two amendment halves review-1800's decomposition explicitly recommended.

Recommendation

No action needed on this ticket — READY to move to todo.
Advisory, non-blocking (board-wide platform gap, already surfaced in review-1800, owned by pal-e-docs not this ticket):
  • [SCOPE] The arch-docs note in pal-e-docs is scoped to westside-basketball. Either generalize it into a cross-project docs-component note or create an ISS-scoped architecture note (e.g., arch-iss-docs) so board-iss's arch:docs label has project-local backing.