dynamicalsystem.com
homelab infrastructure services
Document BRANCH.md structure in workflow.md
Add section explaining BRANCH.md tracking with minimal template based on
ACT-1 experience. Documents which sections to keep (Timeline, Testing,
Issues, Notes) and which to omit (Commits table, PR Information, Status
Updates) as they were found to be unused or redundant.
+68
+68
docs/ooda/2025-10-multi-service-architecture/workflow.md
+68
docs/ooda/2025-10-multi-service-architecture/workflow.md
···
9
9
2. A git branch (ACT phase implementation)
10
10
3. A merge to main (completion)
11
11
12
+
## Branch Tracking with BRANCH.md
13
+
14
+
Each ACT phase has its own `BRANCH.md` file for detailed tracking. This provides granular development history separate from the high-level README.md.
15
+
16
+
### BRANCH.md Structure
17
+
18
+
**Minimal template** (used in practice):
19
+
20
+
```markdown
21
+
# Branch Status: <Task Name>
22
+
23
+
**Branch**: `feature/branch-name`
24
+
**Status**: [...] Not Started | [~] In Progress | [✓] Complete
25
+
**Started**: YYYY-MM-DD
26
+
**Completed**: YYYY-MM-DD
27
+
28
+
## Quick Links
29
+
30
+
- **Plan**: [plan.md](./plan.md)
31
+
- **OBSERVE/ORIENT**: [../../observe/doc.md](../../observe/doc.md)
32
+
- **Merge Commit**: abc123f
33
+
34
+
## Timeline
35
+
36
+
| Event | Date | Notes |
37
+
|-------|------|-------|
38
+
| Branch created | YYYY-MM-DD | feature/branch-name |
39
+
| First commit | YYYY-MM-DD | Description |
40
+
| Testing | YYYY-MM-DD | Test results summary |
41
+
| Outcome verified | YYYY-MM-DD | Validation results |
42
+
| Merged to main | YYYY-MM-DD | Direct merge or PR# |
43
+
44
+
## Testing
45
+
46
+
- [ ] Test case 1
47
+
- [ ] Test case 2
48
+
- [ ] Outcome verification
49
+
50
+
## Issues Encountered
51
+
52
+
1. **Issue title**: Description
53
+
- Resolution: How it was fixed
54
+
55
+
## Notes
56
+
57
+
Any significant observations or decisions during implementation.
58
+
```
59
+
60
+
**Sections we keep**:
61
+
- **Quick Links** - navigation to related docs
62
+
- **Timeline** - key events with dates
63
+
- **Testing** - what was verified
64
+
- **Issues Encountered** - bugs and resolutions
65
+
- **Notes** - context and decisions
66
+
67
+
**Sections we removed** (found to be unused):
68
+
- ~~Commits table~~ - redundant with git log
69
+
- ~~PR Information~~ - only needed if using PRs
70
+
- ~~Status Updates~~ - redundant with status at top
71
+
72
+
### When to Update BRANCH.md
73
+
74
+
1. **On branch creation** - set status to "In Progress", add start date
75
+
2. **During development** - add timeline events, testing results, issues as they occur
76
+
3. **On completion** - set status to "Complete", add completion date and merge commit
77
+
78
+
**Don't batch updates** - update BRANCH.md as events happen for better audit trail.
79
+
12
80
## Workflow Steps
13
81
14
82
### 1. Starting a Branch