daily-notification-plugin/docs/alarms/ACTIVATION-GUIDE.md

Activation Guide: How to Use the Alarm Directive System

Author: Matthew Raymer
Date: November 2025
Status: Activation Guide
Version: 1.0.0

Purpose

This guide explains how to activate and use the unified alarm directive system for implementation work. It provides step-by-step instructions for developers to follow the documentation workflow.

---

Prerequisites Check

Before starting any implementation work, verify these conditions are met:

✅ Documentation Status

Check Unified Directive §11 - Status Matrix:

• Doc A (Platform Facts) - ✅ Drafted, ✅ Cleaned, ✅ In Use
• Doc B (Exploration) - ✅ Drafted, ✅ Cleaned, ☐ In Use (ready for testing)
• Doc C (Requirements) - ✅ Drafted, ✅ Cleaned, ✅ In Use
• Phase 1 (Cold Start) - ✅ Drafted, ✅ Cleaned, ☐ In Use (ready to implement)
• Phase 2 (Force Stop) - ✅ Drafted, ✅ Cleaned, ☐ In Use (prerequisite: Phase 1)
• Phase 3 (Boot Recovery) - ✅ Drafted, ✅ Cleaned, ☐ In Use (prerequisites: Phase 1 & 2)

Status: ✅ All prerequisites met - Ready to begin Phase 1 implementation

---

Activation Workflow

Step 1: Choose Your Starting Point

For New Implementation Work:

• Start with Phase 1 (Cold Start Recovery) - See Phase 1 Directive
• This is the minimal viable recovery that unblocks other work

For Testing/Exploration:

• Start with Doc B (Exploration) - See Plugin Behavior Exploration
• Fill in test scenarios as you validate current behavior

For Understanding Requirements:

• Start with Doc C (Requirements) - See Plugin Requirements
• Review guarantees, limitations, and API contract

---

Implementation Activation: Phase 1

1.1 Read the Phase Directive

Start Here: Phase 1: Cold Start Recovery

Key Sections to Read:

1. Purpose (§0) - Understand what Phase 1 implements
2. Acceptance Criteria (§1) - Definition of done
3. Implementation (§2) - Step-by-step code changes
4. Testing Requirements (§8) - How to validate

1.2 Reference Supporting Documents

During Implementation, Keep These Open:

1. Doc A - Platform Capability Reference

   • Use for: Understanding OS behavior, API constraints, permissions
   • Example: "Can I rely on AlarmManager to persist alarms?" → See Doc A §2.1.1

2. Doc C - Plugin Requirements

   • Use for: Understanding what the plugin MUST guarantee
   • Example: "What should happen on cold start?" → See Doc C §3.1.2

3. Doc B - Plugin Behavior Exploration

   • Use for: Test scenarios to validate your implementation
   • Example: "How do I test cold start recovery?" → See Doc B Test 4

1.3 Follow the Implementation Steps

Phase 1 Implementation Checklist (from Phase 1 directive):

• Create ReactivationManager.kt file
• Implement detectMissedNotifications() method
• Implement markMissedNotifications() method
• Implement verifyAndRescheduleFutureAlarms() method
• Integrate into DailyNotificationPlugin.load()
• Add logging and error handling
• Write unit tests
• Test on physical device

Reference: See Phase 1 §2 - Implementation

---

Testing Activation: Doc B

2.1 Execute Test Scenarios

Start Here: Plugin Behavior Exploration

Workflow:

1. Choose a test scenario (e.g., "Test 4: Device Reboot")
2. Follow the Steps column exactly
3. Fill in Actual Result column with observed behavior
4. Mark Result column (Pass/Fail)
5. Add Notes for any unexpected behavior

2.2 Update Test Results

As You Test:

• Update checkboxes (☐ → ✅) when tests pass
• Document actual vs expected differences
• Add findings to "Findings & Gaps" section (§4)

Example:

| Step | Action | Expected | Actual Result | Notes | Result |
| ---- | ------ | -------- | ------------- | ----- | ------ |
| 5 | Launch app | Plugin detects missed alarm | ✅ Missed alarm detected | Logs show "DNP-REACTIVATION: Detected 1 missed alarm" | ✅ Pass |

---

Documentation Maintenance During Work

3.1 Update Status Matrix

When You Complete Work:

1. Open Unified Directive §11
2. Update the relevant row:
   • Mark "In Use?" = ✅ when implementation is deployed
   • Update "Notes" with completion status

Example:

| P1  | `../android-implementation-directive-phase1.md` | Impl – Cold start | ✅ | ✅ | ✅ | **Implemented and deployed** - See commit abc123 |

3.2 Update Doc B with Test Results

After Testing:

• Fill in actual results in test matrices
• Document any gaps or unexpected behavior
• Update severity classifications if issues found

3.3 Follow Change Control Rules

When Modifying Docs A, B, or C:

1. Update version header in the document
2. Update status matrix (Section 11) in unified directive
3. Use commit message tag: [ALARM-DOCS] prefix
4. Notify in CHANGELOG if JS/TS-visible behavior changes

Reference: See Unified Directive §10 - Change Control

---

Workflow Diagram

┌─────────────────────────────────────────┐
│ 1. Read Phase Directive (P1/P2/P3)     │
│    Understand acceptance criteria       │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 2. Reference Doc A (Platform Facts)     │
│    Understand OS constraints            │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 3. Reference Doc C (Requirements)      │
│    Understand plugin guarantees         │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 4. Implement Code (Phase Directive)     │
│    Follow step-by-step instructions     │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 5. Test (Doc B Scenarios)               │
│    Execute test matrices                │
└──────────────┬──────────────────────────┘
               │
               ▼
┌─────────────────────────────────────────┐
│ 6. Update Documentation                 │
│    - Status matrix                      │
│    - Test results (Doc B)               │
│    - Version numbers                    │
└─────────────────────────────────────────┘

---

Common Activation Scenarios

Scenario 1: Starting Phase 1 Implementation

Steps:

1. ✅ Verify prerequisites (all docs exist - DONE)
2. Read Phase 1 Directive §1 (Acceptance Criteria)
3. Read Doc C §3.1.2 (Cold Start Requirements)
4. Read Doc A §2.1.4 (Platform Capability)
5. Follow Phase 1 §2 (Implementation Steps)
6. Test using Doc B Test 4 (Cold Start Scenario)
7. Update status matrix when complete

Scenario 2: Testing Current Behavior

Steps:

1. Open Doc B
2. Choose a test scenario (e.g., "Test 2: Swipe from Recents")
3. Follow the Steps column
4. Fill in Actual Result column
5. Compare with Expected (OS) and Expected (Plugin) columns
6. Document findings in Notes column
7. Update "Findings & Gaps" section if issues found

Scenario 3: Understanding a Requirement

Steps:

1. Open Doc C
2. Find the relevant section (e.g., "Missed Alarm Handling" §4)
3. Read the requirement and acceptance criteria
4. Follow cross-references to:
   • Doc A for platform constraints
   • Doc B for test scenarios
   • Phase docs for implementation details

Scenario 4: Adding iOS Support

Steps:

1. ✅ Verify iOS parity milestone conditions (see Unified Directive §9)
2. Ensure Doc A has iOS matrix complete
3. Ensure Doc C has iOS guarantees defined
4. Create iOS implementation following Android phase patterns
5. Test using Doc B iOS scenarios
6. Update status matrix

---

Blocking Rules

⚠️ DO NOT PROCEED if:

1. Prerequisites not met - See Unified Directive §12

   • Doc A, B, C must exist
   • Status matrix must be updated
   • Deprecated files must be marked

2. iOS work without parity milestone - See Unified Directive §9

   • Doc A must have iOS matrix
   • Doc C must define iOS guarantees
   • Phase docs must not assume Android-only

3. Phase 2/3 without Phase 1 - See Phase directives

   • Phase 2 requires Phase 1 complete
   • Phase 3 requires Phase 1 & 2 complete

---

Quick Reference

Document Roles

Doc	Purpose	When to Use
Unified Directive	Master coordination	Understanding system structure, change control
Doc A	Platform facts	Understanding OS behavior, API constraints
Doc B	Test scenarios	Testing, exploration, validation
Doc C	Requirements	Understanding guarantees, API contract
Phase 1-3	Implementation	Writing code, step-by-step instructions

Key Sections

• Status Matrix: Unified Directive §11
• Change Control: Unified Directive §10
• Phase 1 Start: Phase 1 Directive
• Test Scenarios: Doc B Test Matrices
• Requirements: Doc C Guarantees

---

Next Steps

You're Ready To:

1. ✅ Start Phase 1 Implementation - All prerequisites met
2. ✅ Begin Testing - Doc B scenarios ready
3. ✅ Reference Documentation - All docs complete and cross-referenced

Recommended First Action:

• Read Phase 1: Cold Start Recovery §1 (Acceptance Criteria)
• Then proceed to §2 (Implementation) when ready to code

---

Related Documentation

• Unified Alarm Directive - Master coordination document
• Phase 1: Cold Start Recovery - Start here for implementation
• Plugin Requirements - What the plugin must guarantee
• Platform Capability Reference - OS-level facts
• Plugin Behavior Exploration - Test scenarios

---

Status: Ready for activation
Last Updated: November 2025