pal-e-docs

Review: #21 docs/pipeline.md — dev-to-App-Store lifecycle (decomp:1800)

review-1804-2026-07-05 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Board item 1804 (board-iss), Forgejo issue ldraney/intelligentstaffingsystems#21, 2 points, decomposition child of #19 (per review-1800-2026-07-05). Scope quality is high — every repo-verifiable claim in the issue checks out (spec, reference doc, image repo, ports, URLs) and sizing is correct for a single pass. One self-contradiction blocks READY: the issue directs the Update Lifecycle sequence diagram into pipeline.md, but docs/ios.md already contains that exact web-vs-native sequence diagram, and the ticket's own Constraint forbids duplicating ios.md content. One-line body fix.

Template Completeness (Feature template)

  • [x] Type — Feature (routes to template-issue-feature)
  • [x] Lineage — child of #19, cites review-1800-2026-07-05 and the spec doc
  • [x] Repo — ldraney/intelligentstaffingsystems
  • [x] User Story — ISS owner, "idea to App Store in weeks" claim as walkable doc
  • [x] Context — names source reference, section plan, and the ios.md boundary
  • [x] File Targets — create list + do-NOT-touch list present
  • [x] Feature Flag — "none"; correct (docs-only, and repo has no docs/feature-flags.md — that is a Tier 2 item)
  • [x] Acceptance Criteria — 5 checkboxes
  • [x] Test Expectations — manual mermaid + link checks, run command N/A (appropriate for docs-only)
  • [x] Constraints — framework-neutral test wording; no ios.md duplication
  • [x] Checklist
  • [x] Related — project + parent #19
All 12 sections present. No template gaps.

Traceability

  • [x] story:project-setup label — present on board item 1804
  • [x] story note verified — project-iss user-stories section exists and lists project-setup (backing: README + docs/architecture.md + docs/adoption-plan.md; metric: "Repo, docs, infra, and CI exist; sprints can dispatch"). The gap flagged in review-1800 is fixed.
  • [x] arch:docs label — present on board item 1804
  • [x] arch note verified — arch-docs ("Architecture: Documentation") exists in pal-e-docs. Caveat, non-blocking: the note is project-scoped to westside-basketball (slugs are global, so a per-project arch-docs cannot exist); content is the generic docs-component pattern. Taxonomy pre-validated by the Overseer.
  • [x] Forgejo issue — https://forgejo.tail5b443a.ts.net/ldraney/intelligentstaffingsystems/issues/21, open, label sprint:0

File Targets

Verified against origin/main and working tree (identical for docs/).
  • [x] docs/pipeline.md (create) — verified absent on main and in worktree; correct for a create ticket
  • [x] docs/ios.md (do NOT touch, cross-link only) — exists on main. ISSUE (see [BODY]): its "Update Model" section (docs/ios.md:16–47) already contains BOTH the update-model table AND the web-vs-native Update Lifecycle sequence diagram (mermaid sequenceDiagram, lines 18–38). The issue's Context asserts ios.md owns only the table.
  • [x] docs/adoption-plan.md (spec, on main) — pipeline.md content spec at lines 31–32 matches the issue's AC1 section list exactly: Overview (4-flow mermaid) → Local Dev → Production Deploy (three-repo table) → iOS Dev Builds (link ios.md) → TestFlight → App Store → Update Lifecycle
  • [x] ~/landscaping-assistant/docs/pipeline.md (read-only reference) — exists; contains the 4-flow mermaid overview, the pal-e-platform/services/deployments three-repo table, and the Update Lifecycle sequence diagram, exactly as the Context claims
AC claims verified in-repo: image repo intelligentstaffingsystems/intelligentstaffingsystems (docs/architecture.md:273); production port 3000 + local port 9999 (README.md:105, architecture.md Port Convention section); ~/rails-base prerequisite (README.md:86); Woodpecker → Harbor → Image Updater → ArgoCD chain (architecture.md:47–49, 313–322); URL story iss.tail5b443a.ts.net funnel → intelligentstaffingsystems.ai via Hetzner edge (ios.md:70, architecture.md:13, 296–298).

Repo Placement

OK. Single-repo docs work; issue filed on the repo it modifies. No other repos affected.

Dependencies

Blocked by: nothing. The spec (docs/adoption-plan.md) and docs/ios.md are on main (#1 / item 1780 merged, sitting in validation). No in_progress items on board-iss.
Blocks: #24 (item 1807, the decomposition closer, labeled blocker:siblings) — the README Documentation-table row for pipeline.md is #24's job, correctly excluded here.
Siblings (parallel-safe): #20 (security.md), #22 (testing-strategy + local-dev-setup), #23 (user-stories + architecture amendments) — no file overlap with pipeline.md; the do-NOT-touch list correctly defers all other docs to them. Merge-order link risk noted in Blast Radius.

Acceptance Criteria

All 5 are objectively verifiable by an agent: section list (headings diff vs spec), three-repo table values (verified against architecture.md:273 and the port convention), URL correctness (verified against ios.md:70 / architecture.md:296–298), local-dev consistency (README.md:86, 105). No fake test commands; manual mermaid/link checks are honestly declared. Count is 5 — at the single-pass threshold, not over it. AC3 is the one problem: as written ("Update Lifecycle sequence diagram (web vs native), cross-linked with docs/ios.md") it requires a diagram in pipeline.md that would duplicate docs/ios.md:18–38, violating the Constraint "Don't duplicate docs/ios.md content — link it". An implementing agent must break either AC3 or the Constraint.

Blast Radius

Docs-only; no code, config, or CI. Three notes: (1) a duplicated web-vs-native diagram would drift from ios.md over time — the exact failure the single-source constraint exists to prevent; (2) if the agent links sibling docs not yet on main (local-dev-setup.md, security.md, testing-strategy.md), the "internal links resolve" check fails — link only docs on main (ios.md, architecture.md, README); (3) the framework-neutral test-wording constraint correctly defers the Minitest/RSpec decision to #22 (testing-strategy.md), matching adoption-plan open decision 1. README/CLAUDE.md propagation is deferred to #24, so no agent-context changes from this ticket.

Decomposition Assessment

No decomposition needed. 1 file target (create), 1 repo, 5 ACs (threshold is >5), 2 points. The work adapts a single ~160-line reference doc with all ISS-specific values already verified in-repo — comfortably a single agent pass under 5 minutes. This ticket is itself the product of decomposing #19, sized correctly.

Recommendation

  • [BODY] Resolve the Update Lifecycle contradiction. The Context says ios.md "owns the update-model table — put the Update Lifecycle sequence diagram here [pipeline.md] and cross-link, don't duplicate the table", but docs/ios.md:18–38 already contains the web-vs-native sequence diagram alongside the table, ios.md is do-NOT-touch, and the Constraints say "Don't duplicate docs/ios.md content — link it". Fix by editing the Context parenthetical to "(which owns the update-model table and the web-vs-native sequence diagram — summarize and cross-link, don't duplicate either)" and rewording AC3 to "Update Lifecycle section summarizes the web-vs-native split and cross-links docs/ios.md's Update Model (no duplicated diagram)". Alternative: if pipeline.md is meant to be the diagram's canonical home (mirroring landscaping-assistant), say so explicitly and exempt the diagram from the no-duplication constraint — but that accepts permanent two-copy drift and is not recommended.