chore: directive activation guide
This commit is contained in:
Matthew Raymer
319
docs/alarms/ACTIVATION-GUIDE.md
Normal file
319
docs/alarms/ACTIVATION-GUIDE.md
Normal file
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user