pal-e-docs

Review: Svelte promotion prep: @svelte-notes annotations

review-416-2026-03-25 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — references parent note westside-playground-overhaul
  • [x] Repo — present (forgejo_admin/westside-playground)
  • [x] User Story — present and well-formed
  • [x] Context — present, explains the gap between existing @route/@auth annotations and missing @state/@svelte-notes
  • [x] File Targets — present with detailed example for tryouts.html
  • [x] Acceptance Criteria — present (6 items)
  • [x] Test Expectations — present (grep-based verification + explicit "no automated tests")
  • [x] Constraints — present (annotations only, no HTML/CSS/JS changes)
  • [x] Checklist — present
  • [x] Related — present (3 references)
All required sections for a Feature issue are present.

Traceability

  • [x] story:WS-S26 label — matches westside-playground-overhaul parent note's story column
  • [ ] story label mismatch — ISSUE: Forgejo issue body says story:agent-promote in the User Story section, but the board item label is story:WS-S26. The parent note uses WS-S26. The issue body should be corrected to story:WS-S26 for consistency.
  • [x] arch:landing-site label — correct, playground pages are the landing site component
  • [x] Forgejo issue — forgejo_admin/westside-app#96, open

File Targets

  • [x] tryouts.html — verified: exists in westside-playground, has existing @route/@auth/@nav/@api doc comment block at top
  • [x] index.html — verified: exists, has existing doc comment block
  • [x] schedule.html — verified: exists, has existing doc comment block
  • [x] about.html — verified: exists in playground
  • [x] team.html — verified: exists in playground
  • [ ] gear.html — ISSUE: does NOT exist yet. Depends on issue #94 (Gear page) which is still open. This ticket cannot annotate a file that doesn't exist.
  • [ ] "ALL playground HTML pages" — the ticket says to annotate all pages, but 3 dependency issues (#93 Teams, #94 Gear, #95 Schedule update) are still open. Pages created by those issues may not exist yet or may change.
26 HTML files currently exist in the playground repo. The ticket's scope of "ALL pages" is valid for existing pages but premature for pages that depend on open issues.

Repo Placement

MISMATCH. The Forgejo issue is filed on forgejo_admin/westside-app (issue #96) but the issue body says ### Repo: forgejo_admin/westside-playground. The work targets playground HTML files, not the SvelteKit app. This is the same repo mismatch flagged in reviews of sibling tickets (#408, #409, #410). The issue should be filed on forgejo_admin/westside-playground, or the board item's forgejo_issue_url should be updated. An agent following the Forgejo URL will land in the wrong repo.

Dependencies

Board item labels: depends:ws-91+ws-92+ws-93+ws-94+ws-95
  • [x] #91 (About page) — closed
  • [x] #92 (Tryouts page) — closed
  • [ ] #93 (Teams page) — open, board item #408 in todo
  • [ ] #94 (Gear page) — open, board item #409 in todo
  • [ ] #95 (Schedule update) — open, board item #410 in todo
3 of 5 dependencies are still open and in todo. This ticket cannot move to next_up until #93, #94, and #95 are done, because the annotation work targets pages that those issues create or modify. The dependency labels are correctly documented.

Acceptance Criteria

Criteria are testable and mechanically verifiable:
  • [x] "Every page has @state" — verifiable via grep
  • [x] "Every page has @api expanded" — verifiable via grep
  • [x] "Every page with JS has @svelte-notes" — verifiable via grep + manual check for JS presence
  • [x] "Toggle pages document shared program state" — verifiable by checking specific pages
  • [x] "Authenticated pages document role-specific data" — verifiable
  • [x] "Nav/footer noted as +layout.svelte" — verifiable via grep
The translation pattern table in the Context section is excellent — it gives agents a concrete mapping from HTML patterns to Svelte 5 equivalents. Acceptance criteria are clear and an agent could verify each one after implementation.

Blast Radius

Low blast radius. This is a documentation-only change (HTML comments). No functional code, CSS, or JS is modified. The annotations will be consumed by future Svelte promotion work but have no runtime effect. No sibling services are affected.
One consideration: the translation patterns table references +page.server.ts load functions and basketball-api endpoints. If those API contracts change before Svelte promotion, the annotations could become stale. This is acceptable risk for documentation.

Recommendation

Three issues must be resolved before this ticket is READY:
  • Repo placement mismatch — Either refile the issue on forgejo_admin/westside-playground or update the Repo section in the issue body to say forgejo_admin/westside-app with a note that the work targets the playground repo. Consistent with the pattern flagged in review-408-2026-03-25.
  • Story label mismatch — Change story:agent-promote in the Forgejo issue body to story:WS-S26 to match the board item label and parent note.
  • Dependencies not met — Issues #93, #94, #95 are still open. This ticket correctly has depends:ws-91+ws-92+ws-93+ws-94+ws-95 labels and must stay in todo until all dependencies close. No action needed here beyond awareness — the labels correctly gate this work.