diff --git a/docs/alarms/ACTIVATION-GUIDE.md b/docs/alarms/ACTIVATION-GUIDE.md new file mode 100644 index 0000000..af97f09 --- /dev/null +++ b/docs/alarms/ACTIVATION-GUIDE.md @@ -0,0 +1,319 @@ +# 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](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix): + +- [x] **Doc A** (Platform Facts) - ✅ Drafted, ✅ Cleaned, ✅ In Use +- [x] **Doc B** (Exploration) - ✅ Drafted, ✅ Cleaned, ☐ In Use (ready for testing) +- [x] **Doc C** (Requirements) - ✅ Drafted, ✅ Cleaned, ✅ In Use +- [x] **Phase 1** (Cold Start) - ✅ Drafted, ✅ Cleaned, ☐ In Use (ready to implement) +- [x] **Phase 2** (Force Stop) - ✅ Drafted, ✅ Cleaned, ☐ In Use (prerequisite: Phase 1) +- [x] **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](../android-implementation-directive-phase1.md) +- This is the minimal viable recovery that unblocks other work + +**For Testing/Exploration**: +- Start with **Doc B** (Exploration) - See [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md) +- Fill in test scenarios as you validate current behavior + +**For Understanding Requirements**: +- Start with **Doc C** (Requirements) - See [Plugin Requirements](./03-plugin-requirements.md) +- Review guarantees, limitations, and API contract + +--- + +## Implementation Activation: Phase 1 + +### 1.1 Read the Phase Directive + +**Start Here**: [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md) + +**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](./01-platform-capability-reference.md) + - 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](./03-plugin-requirements.md) + - 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](./02-plugin-behavior-exploration.md) + - 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](../android-implementation-directive-phase1.md#2-implementation) + +--- + +## Testing Activation: Doc B + +### 2.1 Execute Test Scenarios + +**Start Here**: [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md) + +**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**: +```markdown +| 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](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix) +2. Update the relevant row: + - Mark "In Use?" = ✅ when implementation is deployed + - Update "Notes" with completion status + +**Example**: +```markdown +| 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](./000-UNIFIED-ALARM-DIRECTIVE.md#10-change-control-rules) + +--- + +## 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](../android-implementation-directive-phase1.md) §1 (Acceptance Criteria) +3. Read [Doc C §3.1.2](./03-plugin-requirements.md#312-app-cold-start) (Cold Start Requirements) +4. Read [Doc A §2.1.4](./01-platform-capability-reference.md#214-alarms-can-be-restored-after-app-restart) (Platform Capability) +5. Follow [Phase 1 §2](../android-implementation-directive-phase1.md#2-implementation) (Implementation Steps) +6. Test using [Doc B Test 4](./02-plugin-behavior-exploration.md#test-4-device-reboot) (Cold Start Scenario) +7. Update status matrix when complete + +### Scenario 2: Testing Current Behavior + +**Steps**: +1. Open [Doc B](./02-plugin-behavior-exploration.md) +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](./03-plugin-requirements.md) +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](./000-UNIFIED-ALARM-DIRECTIVE.md#9-next-steps)) +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](./000-UNIFIED-ALARM-DIRECTIVE.md#12-single-instruction-for-team) + - 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](./000-UNIFIED-ALARM-DIRECTIVE.md#9-next-steps) + - 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](./000-UNIFIED-ALARM-DIRECTIVE.md#11-status-matrix) +- **Change Control**: [Unified Directive §10](./000-UNIFIED-ALARM-DIRECTIVE.md#10-change-control-rules) +- **Phase 1 Start**: [Phase 1 Directive](../android-implementation-directive-phase1.md) +- **Test Scenarios**: [Doc B Test Matrices](./02-plugin-behavior-exploration.md#12-behavior-testing-matrix) +- **Requirements**: [Doc C Guarantees](./03-plugin-requirements.md#1-plugin-behavior-guarantees--limitations) + +--- + +## 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](../android-implementation-directive-phase1.md) §1 (Acceptance Criteria) +- Then proceed to §2 (Implementation) when ready to code + +--- + +## Related Documentation + +- [Unified Alarm Directive](./000-UNIFIED-ALARM-DIRECTIVE.md) - Master coordination document +- [Phase 1: Cold Start Recovery](../android-implementation-directive-phase1.md) - Start here for implementation +- [Plugin Requirements](./03-plugin-requirements.md) - What the plugin must guarantee +- [Platform Capability Reference](./01-platform-capability-reference.md) - OS-level facts +- [Plugin Behavior Exploration](./02-plugin-behavior-exploration.md) - Test scenarios + +--- + +**Status**: Ready for activation +**Last Updated**: November 2025 +