2.9 KiB
Dev Design Review
Overall Assessment
The current Dev-Design.md is 75-80% ready for delegation. Strong architecture and phased approach, but missing key operational sections.
Chapter-by-Chapter Feedback
1. North Star
Strengths: Clear vision. Gaps: No measurable success criteria for MVP. Recommendation: Add success metrics (e.g., Bob spends <15 min/week on research).
2. System Architecture
Strengths: Good diagram and memory budget. Gaps: No data flow description, error propagation, or external dependency diagram. Recommendation: Add numbered daily run flow and failure modes section.
3. Data Layer
Strengths: Strong SQLite rationale and retention policy. Gaps: No backup strategy or migration process. Recommendation: Add SQLite backup/restore and schema migration approach.
4. Adapter Layer
Strengths: Clear HTTP-only decision. Gaps: No formal adapter interface contract. Recommendation: Define minimal Adapter Interface (methods, exceptions).
5. Theme Tagging
Strengths: Good phased approach. Gaps: No theme governance process. Recommendation: Add subsection on how themes are proposed and maintained.
6. Falsification Engine
Strengths: Exponential decay is a smart improvement. Gaps: No calibration/tuning process. Recommendation: Add note on how decay parameters are validated.
7. Output Layer
Strengths: Good consumer separation. Gaps: MCP tools are too high-level; no auth model. Recommendation: Define minimum MCP tools and basic API auth.
8. Observability
Strengths: Decent start. Gaps: No log retention, alerting thresholds, or SLIs. Recommendation: Add log retention policy and basic alerting matrix.
9. Scheduling
Strengths: Good comparison. Gaps: No explicit recommendation for Phase 1 vs future. Recommendation: State clear recommendation (cron for Phase 1).
10. Inference
Strengths: Clear host-level decision. Gaps: No model upgrade/rollback process. Recommendation: Add model upgrade guidance.
11. Security
Strengths: Basic coverage. Gaps: Container hardening and dependency scanning. Recommendation: Add MVP security baseline subsection.
12. Implementation Phases
Strengths: Strong. Gaps: No Definition of Done per phase. Recommendation: Add DoD checklist for each phase.
13. Backport to PRD
Strengths: Useful. Recommendation: Consider moving actual requirement text to PRD to avoid duplication.
14. Design Decisions
Strengths: Good. Recommendation: Add "Revisit in Phase X" column for key decisions.
Missing Sections to Add
- Testing Strategy (unit, integration, E2E)
- Deployment & CI/CD
- Operational Runbooks
- Risk Register & Assumptions
- Dependencies & Tooling
Priority for Next Revision
Focus on adding Testing Strategy, Runbooks, and DoD per phase first. This will make the document truly delegation-ready.