pal-e-docs

Review: Deliverability validation: mail-tester.com + end-to-end password reset

review-1740-2026-07-04 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Re-review of board item #1740. Previous review (review-1740-2026-07-03) returned NEEDS_REFINEMENT for missing arch note and wrong type. Both issues are now fixed. However, the issue body was not reformatted to match the Spike template when the type was changed from Feature to Spike.

Template Completeness

Evaluated against template-issue-spike. Issue declares ### Type: Spike but uses Feature template structure.
  • [x] Type -- Spike (fixed from previous review)
  • [x] Lineage -- "Final gate -- depends on all other stalwart-email tickets"
  • [x] Repo -- ldraney/pal-e-services
  • [ ] Question -- MISSING. Has "User Story" + "Context" instead. Spike template requires a specific question this spike answers.
  • [ ] Deliverables -- MISSING. Has "Acceptance Criteria" + "Checklist" instead. Spike template requires explicit deliverables (docs file + follow-up tickets).
  • [ ] Time-box -- MISSING. Spike template requires maximum investigation time to prevent rabbit holes.
  • [x] Related -- present
Extra sections from Feature template (not part of Spike template):
  • User Story (spikes frame as Question, not User Story)
  • File Targets (spikes implicitly target docs/{topic}.md)
  • Feature Flag (not a spike section)
  • Acceptance Criteria (spikes have Deliverables)
  • Test Expectations (spikes explicitly have no test expectations per template)
  • Constraints (not a standard spike section)
  • Checklist (not a standard spike section)

Traceability

  • [x] story:password-reset label -- "As a user who forgot my password, I want to receive a reset email from my app's domain so I can regain access"
  • [x] story note verified -- found in project-stalwart-email user-stories section
  • [x] arch:stalwart label -- present on board item
  • [x] arch note verified -- arch-stalwart note exists in pal-e-docs (created 2026-07-04)
  • [x] Forgejo issue -- ldraney/pal-e-services#168, open

File Targets

No code file targets -- appropriate for a validation spike. Expected spike output: docs/deliverability-validation.md (not yet specified in issue body since Deliverables section is missing).

Repo Placement

OK. Issue filed on ldraney/pal-e-services. Validation work runs against services deployed from this repo. No cross-repo mismatch.

Dependencies

Documented as "Final gate -- depends on all other stalwart-email tickets." All 8 sibling tickets confirmed in backlog:
  • #1732 (pal-e-platform#497) -- edge-vps port 25 unblock, backlog
  • #1733 (pal-e-platform#498) -- stalwart install, backlog
  • #1734 (pal-e-platform#499) -- edge-vps PTR/rDNS, backlog
  • #1735 (pal-e-platform#500) -- edge-vps custom-domain, backlog
  • #1736 (pal-e-services#164) -- stalwart config, backlog
  • #1737 (pal-e-services#165) -- DNS landscaping-assistant.app, backlog
  • #1738 (pal-e-services#166) -- DNS westsidekingsandqueens.com, backlog
  • #1739 (pal-e-services#167) -- Keycloak SMTP config, backlog
This ticket MUST NOT move to todo until all blockers complete. Dependencies correctly documented.

Acceptance Criteria

7 items present but in Feature template format. For a Spike, these should be reframed: the "acceptance criteria" are really the sub-questions/test cases the spike investigates. The actual deliverables are (1) a docs file recording results and (2) follow-up tickets if fixes are needed. Content is substantively correct but structurally misplaced.

Blast Radius

Minimal. No code changes. Validation-only spike. If deliverability issues are found, they route back to existing config tickets on the board. No downstream consumers affected.

Decomposition Assessment

  • As a properly-formatted spike: 2 deliverables (docs file + follow-up tickets) -- under 5 threshold
  • 0 code file targets
  • 1 repo
  • Single validation session
  • Estimated agent time: ~5 minutes (external service calls, not complexity)
No decomposition needed. The 7 current "AC" items are sequential checks in one validation session -- they become sub-questions in the spike's Question section after reformatting.

Recommendation

  • [BODY] Reformat issue body to use Spike template structure. Specifically:
Traceability is now complete (arch-stalwart created, story verified). Only the body structure remains to be fixed.