Digital Lock On

Appearance

Decision Management Quick Start ​

TL;DR - Essential Workflows ​

Creating a New Decision ​

bash
make create
# Enter title: "API Authentication Strategy"  
# Enter ADR number: 008
# → Creates: pending/adr-008-api-authentication-strategy.md

Completing a Decision ​

When your research is done and decision is made:

  1. Update the pending file: Set status to "Completed", add final rationale
  2. Move to root: mv pending/adr-008-api-auth.md adr-008-api-auth.md
  3. Dashboard auto-updates: Shows new completed decision

Weekly Review ​

Just check the auto-updated dashboard at decisions/index.md - it shows:

  • All pending decisions with deadlines
  • Recent completed decisions
  • Status metrics and urgency alerts

File Organisation ​

decisions/
├── index.md                           # 📊 Dashboard (auto-generated)
├── pending/                           # 🔄 Pending decisions
│   └── adr-001-audit-trail-strategy.md
├── adr-006-handover-flow-design.md   # ✅ Completed decisions
├── adr-007-heartbeat-frequency.md    # (sequential numbering)
├── templates/                         # 📝 Templates  
│   ├── pending-decision-enhanced.md
│   └── adr-template.md
└── scripts/                          # 🤖 Automation
    ├── simple-decision-check.py
    └── update-dashboard.py

Status Progression ​

Pending → In Research → Under Review → Decided → ADR Created
   ↓                                      ↑
🔄 Active tracking              ✅ Archived decision

Best Practices ​

✅ Do ​

  • Set realistic deadlines when creating decisions
  • Update status as you make progress
  • Link to blocking requirements in the decision
  • Use the enhanced template for complex decisions
  • Check deadlines regularly

❌ Don't ​

  • Create decisions without clear deadline or impact
  • Let decisions go stale without updates
  • Forget to create ADRs after deciding
  • Skip the dashboard updates

Advanced Features ​

1. RACI Matrix ​

Use the enhanced template to track:

  • Responsible: Who does the work
  • Accountable: Who signs off
  • Consulted: Who provides input
  • Informed: Who needs to know

2. Impact Assessment ​

Track what gets blocked if the decision is delayed:

markdown
### Blocked Items
- [REQ-AUTH-001: User Authentication](link) - *Blocked because: needs auth strategy*

3. Research Tracking ​

Keep a log of research done and outstanding:

markdown
### Completed Research
- [x] Investigated OAuth vs JWT - *Result: JWT better for our use case*

### Outstanding Research  
- [ ] Performance benchmarks - *Assigned to: Tech Lead*

Integration with Requirements ​

When a requirement needs a decision, reference it:

markdown
## Notes
- Authentication method will be determined in [Decision: Auth Strategy](./2024-01-15-auth-strategy.md)

Automation Features ​

  • Dashboard auto-updates with metrics and status
  • Deadline monitoring with CLI tools
  • GitHub Actions integration (optional)
  • Overdue decision alerts

Troubleshooting ​

"No decisions found" ​

Check you're running commands from the right directory:

bash
cd digital-lock-on-docs/decisions

Dashboard not updating ​

Run manually:

bash
python scripts/update-dashboard.py

Script permissions ​

Make scripts executable:

bash
chmod +x scripts/*.py

Templates Comparison ​

FeatureStandardEnhanced
Basic structure✅✅
Status tracking✅✅
RACI matrix❌✅
Research tracking❌✅
Impact assessment❌✅
Action management❌✅

Recommendation: Use Enhanced template for important decisions, Standard for simple ones.

Need help? Check the full documentation or create an issue.

Internal use only