docs: merge notification system docs into single Native-First guide
- Consolidate 5 notification-system-* files into doc/notification-system.md - Add web-push cleanup guide and Start-on-Login glossary entry - Configure markdownlint for consistent formatting - Remove web-push references, focus on native OS scheduling Reduces maintenance overhead while preserving all essential information in a single, well-formatted reference document.
This commit is contained in:
@@ -12,19 +12,23 @@ To ensure clarity, efficiency, and high-value documentation within code and proj
|
||||
---
|
||||
|
||||
## 1. Documentation and References Must Add Clear Value
|
||||
- Only include documentation, comments, or reference links when they provide *new, meaningful information* that assists understanding or decision-making.
|
||||
|
||||
- Only include documentation, comments, or reference links when they provide _new, meaningful information_ that assists understanding or decision-making.
|
||||
- Avoid duplicating content already obvious in the codebase, version history, or linked project documents.
|
||||
|
||||
---
|
||||
|
||||
## 2. Eliminate Redundant or Noisy References
|
||||
|
||||
- Remove references that serve no purpose beyond filling space.
|
||||
- Model agents may automatically flag and suggest removal of trivial references (e.g., links to unchanged boilerplate or self-evident context).
|
||||
|
||||
---
|
||||
|
||||
## 3. Explicit Role of Model Agents
|
||||
|
||||
Model agents are **active participants** in documentation quality control. Their tasks include:
|
||||
|
||||
- **Relevance Evaluation**: Automatically analyze references for their substantive contribution before inclusion.
|
||||
- **Redundancy Detection**: Flag duplicate or trivial references across commits, files, or tasks.
|
||||
- **Context Linking**: Suggest appropriate higher-level docs (designs, ADRs, meeting notes) when a code change touches multi-stage or cross-team items.
|
||||
@@ -36,6 +40,7 @@ Contributors must treat agent recommendations as **first-pass reviews** but rema
|
||||
---
|
||||
|
||||
## 4. Contextual References for Complex Items
|
||||
|
||||
- Use **centralized references** for multi-stage features (e.g., architectural docs, research threads).
|
||||
- Keep inline code comments light; push broader context into centralized documents.
|
||||
- Model agents may auto-summarize complex chains of discussion and attach them as a single reference point.
|
||||
@@ -43,24 +48,28 @@ Contributors must treat agent recommendations as **first-pass reviews** but rema
|
||||
---
|
||||
|
||||
## 5. Centralization of Broader Context
|
||||
|
||||
- Store overarching context (design docs, proposals, workflows) in accessible, well-indexed places.
|
||||
- Model agents should assist by **generating reference maps** that track where docs are cited across the codebase.
|
||||
|
||||
---
|
||||
|
||||
## 6. Focused Documentation
|
||||
|
||||
- Documentation should explain **why** and **how** decisions are made, not just what was changed.
|
||||
- Model agents can auto-generate first-pass explanations from commit metadata, diffs, and linked issues—but humans must refine them for accuracy and intent.
|
||||
|
||||
---
|
||||
|
||||
## 7. Review and Accountability
|
||||
|
||||
- Reviewers and team leads must reject submissions containing unnecessary or low-quality documentation.
|
||||
- Model agent outputs are aids, not replacements—contributors remain responsible for **final clarity and relevance**.
|
||||
|
||||
---
|
||||
|
||||
## 8. Continuous Improvement and Agent Feedback Loops
|
||||
|
||||
- Encourage iterative development of model agents so their evaluations become more precise over time.
|
||||
- Contributions should include **feedback on agent suggestions** (e.g., accepted, rejected, or corrected) to train better future outputs.
|
||||
- Agents should log patterns of “rejected” suggestions for refinement.
|
||||
@@ -84,4 +93,4 @@ flowchart TD
|
||||
|
||||
---
|
||||
|
||||
✅ **Outcome:** By integrating disciplined contributor standards with **model agent augmentation**, the team achieves documentation that is consistently *relevant, concise, centralized, and decision-focused*. AI ensures coverage and noise reduction, while humans ensure precision and judgment.
|
||||
✅ **Outcome:** By integrating disciplined contributor standards with **model agent augmentation**, the team achieves documentation that is consistently _relevant, concise, centralized, and decision-focused_. AI ensures coverage and noise reduction, while humans ensure precision and judgment.
|
||||
|
||||
Reference in New Issue
Block a user