rename 'docs' directory to 'doc'
This commit is contained in:
196
doc/design/P1.5-STEP4-CLUSTERS.md
Normal file
196
doc/design/P1.5-STEP4-CLUSTERS.md
Normal file
@@ -0,0 +1,196 @@
|
||||
# P1.5 Step 4: Duplicate Consolidation Clusters
|
||||
|
||||
**Date:** 2025-12-22
|
||||
**Status:** 🎯 Ready for Review & Decision
|
||||
**Baseline:** `v1.0.11-p0-p1.4-complete`
|
||||
|
||||
---
|
||||
|
||||
## Objective
|
||||
|
||||
Review and consolidate duplicate/superseded documentation with explicit "keep / merge / archive / redirect" decisions per cluster.
|
||||
|
||||
**Principle:** No information loss — archive or redirect, never delete.
|
||||
|
||||
---
|
||||
|
||||
## Cluster 1: Testing Quick References
|
||||
|
||||
### Files to Review
|
||||
|
||||
- `doc/testing/QUICK_REFERENCE.md` — Current canonical
|
||||
- `doc/testing/QUICK_REFERENCE_V2.md` — Potential duplicate
|
||||
|
||||
### Decision Process
|
||||
|
||||
1. **Compare content:**
|
||||
- If V2 has unique content → Merge into `QUICK_REFERENCE.md`, then archive V2
|
||||
- If V2 is superseded → Archive V2 with pointer in `QUICK_REFERENCE.md`
|
||||
|
||||
2. **Action:**
|
||||
- [ ] Review both files side-by-side
|
||||
- [ ] Decide: merge or archive
|
||||
- [ ] If merge: Update `QUICK_REFERENCE.md` with V2 content, archive V2
|
||||
- [ ] If archive: Move V2 to `doc/_archive/2025-12-16-consolidation/`, add pointer in `QUICK_REFERENCE.md`
|
||||
- [ ] Update `doc/00-INDEX.md` (remove V2 from active list if archived)
|
||||
|
||||
### Authoritative Doc
|
||||
|
||||
- `doc/testing/QUICK_REFERENCE.md` (keep as canonical)
|
||||
|
||||
### Expected Outcome
|
||||
|
||||
- One authoritative quick reference
|
||||
- V2 either merged or archived with pointer
|
||||
|
||||
---
|
||||
|
||||
## Cluster 2: Integration Refactor Notes
|
||||
|
||||
### Files to Review
|
||||
|
||||
- `doc/integration/REFACTOR_NOTES.md` — Current canonical
|
||||
- `doc/integration/REFACTOR_NOTES_QUICK_START.md` — Check if duplicate
|
||||
- `doc/integration/REFACTOR_ANALYSIS.md` — Check if duplicate
|
||||
|
||||
### Decision Process
|
||||
|
||||
1. **Compare content:**
|
||||
- If `REFACTOR_NOTES_QUICK_START.md` duplicates `REFACTOR_NOTES.md` → Archive with pointer
|
||||
- If `REFACTOR_ANALYSIS.md` duplicates `REFACTOR_NOTES.md` → Archive with pointer
|
||||
- If either has unique content → Keep all, add cross-references
|
||||
|
||||
2. **Action:**
|
||||
- [ ] Review all three files for overlap
|
||||
- [ ] Identify unique vs duplicate content
|
||||
- [ ] If duplicates: Archive with pointer in `REFACTOR_NOTES.md`
|
||||
- [ ] If unique: Keep all, add cross-references between files
|
||||
- [ ] Update `doc/00-INDEX.md` (remove archived files from active list)
|
||||
|
||||
### Authoritative Doc
|
||||
|
||||
- `doc/integration/REFACTOR_NOTES.md` (keep as canonical)
|
||||
|
||||
### Expected Outcome
|
||||
|
||||
- One authoritative refactor notes doc (or multiple with clear cross-references)
|
||||
- Duplicates archived with pointers
|
||||
|
||||
---
|
||||
|
||||
## Cluster 3: iOS Implementation Checklists
|
||||
|
||||
### Files to Review
|
||||
|
||||
- `doc/platform/ios/IMPLEMENTATION_CHECKLIST.md` — Current canonical
|
||||
- `doc/platform/ios/IOS_IMPLEMENTATION_CHECKLIST.md` — Check if duplicate
|
||||
- `doc/platform/ios/IMPLEMENTATION_CHECKLIST_LEGACY.md` — Already marked legacy
|
||||
|
||||
### Decision Process
|
||||
|
||||
1. **Compare content:**
|
||||
- If `IOS_IMPLEMENTATION_CHECKLIST.md` duplicates `IMPLEMENTATION_CHECKLIST.md` → Archive with pointer
|
||||
- If `IOS_IMPLEMENTATION_CHECKLIST.md` has unique content → Merge into `IMPLEMENTATION_CHECKLIST.md`, then archive
|
||||
- `IMPLEMENTATION_CHECKLIST_LEGACY.md` → Move to `doc/_archive/2025-legacy-doc/` (already marked legacy)
|
||||
|
||||
2. **Action:**
|
||||
- [ ] Review `IOS_IMPLEMENTATION_CHECKLIST.md` vs `IMPLEMENTATION_CHECKLIST.md`
|
||||
- [ ] Decide: merge or archive
|
||||
- [ ] Move `IMPLEMENTATION_CHECKLIST_LEGACY.md` to `doc/_archive/2025-legacy-doc/`
|
||||
- [ ] Update `doc/00-INDEX.md` (remove archived files from active list)
|
||||
|
||||
### Authoritative Doc
|
||||
|
||||
- `doc/platform/ios/IMPLEMENTATION_CHECKLIST.md` (keep as canonical)
|
||||
|
||||
### Expected Outcome
|
||||
|
||||
- One authoritative iOS implementation checklist
|
||||
- Legacy and duplicate files archived with pointers
|
||||
|
||||
---
|
||||
|
||||
## Cluster 4: Deployment Documentation
|
||||
|
||||
### Files to Review
|
||||
|
||||
- `doc/deployment/deployment-guide.md` — Check if exists
|
||||
- `doc/deployment/DEPLOYMENT_CHECKLIST.md` — Keep (complementary)
|
||||
- `doc/progress/DEPLOYMENT_SUMMARY.md` — Keep (complementary)
|
||||
|
||||
### Decision Process
|
||||
|
||||
1. **Check existence:**
|
||||
- If both `deployment/deployment-guide.md` and `DEPLOYMENT_GUIDE.md` exist → Compare content
|
||||
- If one exists → Keep as canonical
|
||||
- If neither exists → Skip this cluster
|
||||
|
||||
2. **If both exist:**
|
||||
- If duplicates → Keep one (prefer `DEPLOYMENT_GUIDE.md` for consistency), archive other
|
||||
- If complementary → Keep both, add cross-references
|
||||
|
||||
3. **Action:**
|
||||
- [ ] Check which deployment guide files exist
|
||||
- [ ] If both exist: Compare content, decide merge or keep both
|
||||
- [ ] If merge: Archive duplicate with pointer
|
||||
- [ ] Ensure all deployment docs are cross-referenced
|
||||
- [ ] Update `doc/00-INDEX.md` (remove archived files from active list)
|
||||
|
||||
### Authoritative Doc
|
||||
|
||||
- `doc/deployment/deployment-guide.md` (primary)
|
||||
- `doc/deployment/DEPLOYMENT_CHECKLIST.md` (complementary)
|
||||
- `doc/DEPLOYMENT_SUMMARY.md` (complementary)
|
||||
|
||||
### Expected Outcome
|
||||
|
||||
- One authoritative deployment guide (or multiple with clear cross-references)
|
||||
- Duplicates archived with pointers
|
||||
|
||||
---
|
||||
|
||||
## Implementation Checklist
|
||||
|
||||
### Per Cluster
|
||||
|
||||
- [ ] **Cluster 1:** Testing quick references consolidated
|
||||
- [ ] **Cluster 2:** Integration refactor notes consolidated
|
||||
- [ ] **Cluster 3:** iOS implementation checklists consolidated
|
||||
- [ ] **Cluster 4:** Deployment docs consolidated
|
||||
|
||||
### After All Clusters
|
||||
|
||||
- [ ] All archived files moved to appropriate archive directories
|
||||
- [ ] All pointers added to authoritative docs
|
||||
- [ ] `doc/00-INDEX.md` updated (archived files removed from active list)
|
||||
- [ ] `doc/progress/01-CHANGELOG-WORK.md` updated with consolidation summary
|
||||
|
||||
---
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] No duplicate content in active documentation
|
||||
- [ ] All unique content preserved (merged or kept separate with cross-references)
|
||||
- [ ] All archived files have clear pointers from authoritative docs
|
||||
- [ ] Index reflects only active documentation
|
||||
- [ ] No information loss (everything preserved or redirected)
|
||||
|
||||
---
|
||||
|
||||
## Risk Mitigation
|
||||
|
||||
**Risk:** Losing unique content during merge
|
||||
**Mitigation:** Review side-by-side before any merge, preserve original in archive if uncertain
|
||||
|
||||
**Risk:** Creating new sprawl with cross-references
|
||||
**Mitigation:** Keep cross-references minimal (1-2 lines), prefer single authoritative doc when possible
|
||||
|
||||
**Risk:** Breaking internal links
|
||||
**Mitigation:** Use redirects/pointers, don't delete files
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2025-12-22
|
||||
**Status:** Ready for Review & Decision
|
||||
**Next Action:** Review each cluster and make explicit decisions
|
||||
|
||||
Reference in New Issue
Block a user