Edison Jwa
bba6273af7
- Move ASPICE docs to chanoraapp/docs submodule at docs/ - Move development docs to dev-docs/ (superpowers, offline-knowledge, impl-mapping) - Add AGENTS.md with project conventions for AI agents - Add impl-mapping.md (SAD component → source file mapping) - Archive completed plans to dev-docs/superpowers/plans/_archived/ - Remove AGENTS.md from .gitignore (now tracked)
124 lines
7.5 KiB
Markdown
124 lines
7.5 KiB
Markdown
# Documentation Quality Analysis
|
|
|
|
## Summary
|
|
- Total docs analyzed: 64
|
|
- Duplicated content instances: 8
|
|
- Path record files (DV navigation aids): 4
|
|
- Genuine issues (malformed markdown): 1
|
|
- Broken references: 1 (suggested file names only; SDD-109/SAD-043 are valid historical refs)
|
|
|
|
## Duplicated Content
|
|
|
|
### Instance 1: Lifecycle Documentation Chain
|
|
- **Files**: `README.md:280`, `CONTRIBUTING.md:10`, `docs/sysdes.md:90`, `docs/sysrs.md:108`, `docs/governance/traceability-matrix.md:16`, `docs/references/aspice-swe2-swe3-integration-note.md:12`
|
|
- **Content**: `SysRS -> SysDes -> SRS -> SAD -> SDD` lifecycle chain repeated across 6+ files
|
|
- **Recommendation**: Define once in `README.md` and reference from other docs
|
|
|
|
### Instance 2: Git Commit Convention Examples
|
|
- **Files**: `README.md:380`, `CONTRIBUTING.md:38`, `docs/governance/git-commit-message-convention.md:15`
|
|
- **Content**: Same commit examples (`feat(voice): add push-to-talk state handling`, `fix(protocol): recover channel tree after reconnect snapshot`, etc.) duplicated across 3 files
|
|
- **Recommendation**: Keep examples only in `docs/governance/git-commit-message-convention.md` and reference from README/CONTRIBUTING
|
|
|
|
### Instance 3: Security/Privacy/Legal Document List
|
|
- **Files**: `README.md:349-355`, `SECURITY.md:33-38`
|
|
- **Content**: Same list of 6 security documents (threat-model, secure-storage, diagnostic-redaction, dependency, privacy-policy, trademark) repeated verbatim
|
|
- **Recommendation**: Keep list in `SECURITY.md` and reference from README
|
|
|
|
### Instance 4: Architecture Component Table
|
|
- **Files**: `README.md:73-92`, `docs/architecture/sad.md:56-67`
|
|
- **Content**: Similar architecture overview showing Flutter UI, Rust Core, Protocol Layer structure
|
|
- **Recommendation**: Keep detailed version in SAD; use abbreviated version in README
|
|
|
|
### Instance 5: Platform Policy Table
|
|
- **Files**: `README.md:47-54`, `docs/release/platform-release-policy.md:12-19`
|
|
- **Content**: Platform requirements table with overlapping information
|
|
- **Recommendation**: Consolidate in `platform-release-policy.md` and reference from README
|
|
|
|
### Instance 6: Security Gate Requirements
|
|
- **Files**: `docs/security/security-privacy-legal-guideline.md:13-21`, `docs/security/threat-model.md:22-30`
|
|
- **Content**: Similar threat/mitigation tables with overlapping secure-storage and diagnostics concerns
|
|
- **Recommendation**: Threat model should reference the guideline for gate requirements
|
|
|
|
### Instance 7: DV Conclusion Pattern
|
|
- **Files**: Nearly every `docs/` file ends with a "## DV Conclusion" section
|
|
- **Content**: Repetitive pattern: "[Area] is documented for DV. [Limitation] remains."
|
|
- **Recommendation**: This is intentional for ASPICE compliance. No change needed, but consider a template.
|
|
|
|
### Instance 8: Android Runtime Gate Documentation
|
|
- **Files**: `docs/verification/swe5-software-integration-verification-plan.md:57-68`, `docs/governance/maintainability-review-2026-06-08.md:61-88`
|
|
- **Content**: Same Android ADB/emulator verification steps and `adb devices -l` requirements
|
|
- **Recommendation**: Define once in a shared reference and import
|
|
|
|
## Path Record Files (DV Navigation Aids)
|
|
|
|
These files are intentional ASPICE DV entry-point records with reviewer navigation tables. They are NOT useless — they serve a specific compliance purpose. Listed here for awareness only.
|
|
|
|
### DV Navigation Aids
|
|
|
|
| File | Line | Header | Issue |
|
|
|------|------|--------|-------|
|
|
| `docs/architecture/sysdes.md` | 1-21 | Entire file | Path record — points to `docs/sysdes.md` for DV reviewer navigation |
|
|
| `docs/requirements/sysrs.md` | 1-22 | Entire file | Path record — points to `docs/sysrs.md` for DV reviewer navigation |
|
|
| `docs/requirements/srs.md` | 1-22 | Entire file | Path record — points to `docs/srs.md` for DV reviewer navigation |
|
|
| `docs/ui-ux/material3-guideline.md` | 1-8 | Entire file | Path record — points to `docs/material3-guideline.md` for DV reviewer navigation |
|
|
|
|
### Genuine Issues
|
|
|
|
| File | Line | Header | Issue |
|
|
|------|------|--------|-------|
|
|
| `docs/sysdes.md` | 13 | `**Repo path:** ... ---` | Malformed markdown (missing blank line before `---`) |
|
|
|
|
### TODO/Placeholder Markers
|
|
|
|
No actual TODO/TBD/placeholder markers found in the documentation files. The codebase is clean of such markers.
|
|
|
|
### Broken References
|
|
|
|
| File | Line | Reference | Issue |
|
|
|------|------|-----------|-------|
|
|
| `docs/sysrs.md` | 126-130 | `docs/chanora_SysDes.md`, `docs/chanora_SRS.md`, etc. | These suggested file names do not exist. Actual files use different names (`docs/sysdes.md`, `docs/srs.md`, etc.) |
|
|
| `docs/implementation-status-2026-05-28.md` | 103 | `SDD-109` | References a specific SDD item ID that is not itemized in the current SDD baseline |
|
|
| `docs/implementation-status-2026-05-28.md` | 105 | `SAD-043` | References a specific SAD item ID that is not itemized in the current SAD baseline |
|
|
|
|
### Outdated Content
|
|
|
|
| File | Line | Content | Issue |
|
|
|------|------|---------|-------|
|
|
| `docs/sysdes.md` | 6 | Version `0.9.8` | Superseded by later governance docs dated 2026-05-29 |
|
|
| `docs/sysrs.md` | 5 | Version `0.9.11` | May need alignment with SysDes version |
|
|
| `docs/material3-guideline.md` | 4-5 | Version `0.9.2` | Change history stops at 2026-05-14; no updates for 2026-05-29 baseline |
|
|
| `tools/windows-smoke.md` | 6 | `product/scaffold-v0` branch | Default base branch changed to `main` per CHANGELOG |
|
|
| `docs/implementation-status-2026-05-28.md` | 140 | Agent spec docs reference | States docs are "deleted from the working tree but still in git HEAD" — stale cleanup note |
|
|
|
|
### Stale Content
|
|
|
|
| File | Line | Content | Issue |
|
|
|------|------|---------|-------|
|
|
| `docs/implementation-status-2026-05-28.md` | 1 | Date: 2026-05-28 | Pre-dates DV baseline (2026-05-29); may not reflect final baseline state |
|
|
| `docs/governance/git-commit-message-convention.md` | 18 | `release(android): prepare internal alpha build metadata` | Example uses `release` type which is not in the Conventional Commits standard types |
|
|
|
|
## Duplicated Code Blocks
|
|
|
|
| Code Hash | Files | Description |
|
|
|-----------|-------|-------------|
|
|
| Lifecycle chain | `README.md:280`, `CONTRIBUTING.md:10`, `docs/sysdes.md:90`, `docs/sysrs.md:108`, `docs/governance/traceability-matrix.md:16`, `docs/references/aspice-swe2-swe3-integration-note.md:12` | `SysRS -> SysDes -> SRS -> SAD -> SDD -> Verification` |
|
|
| Commit examples | `README.md:379-386`, `CONTRIBUTING.md:37-42`, `docs/governance/git-commit-message-convention.md:14-19` | Overlapping commit message examples (different subsets in each file) |
|
|
| Security doc list | `README.md:349-355`, `SECURITY.md:33-38` | 6 identical file paths |
|
|
| Architecture ASCII art | `README.md:73-92`, `docs/architecture/sad.md:56-67` | Similar but not identical architecture diagrams |
|
|
| Platform table | `README.md:47-54`, `docs/release/platform-release-policy.md:12-19` | Overlapping platform requirement tables |
|
|
|
|
## Recommendations
|
|
|
|
### High Priority
|
|
1. **Consolidate lifecycle chain**: Define once in README, reference elsewhere
|
|
2. **Fix suggested file names**: `docs/sysrs.md` lines 126-130 reference non-existent file names
|
|
|
|
### Medium Priority
|
|
4. **Consolidate commit examples**: Keep in `git-commit-message-convention.md` only
|
|
5. **Consolidate security doc list**: Keep in `SECURITY.md` only
|
|
6. **Update outdated branch reference**: `tools/windows-smoke.md` references `product/scaffold-v0` but default is now `main`
|
|
|
|
### Low Priority
|
|
7. **Align document versions**: SysDes (0.9.8), SysRS (0.9.11), Material3 (0.9.2) have different versions
|
|
8. **Clean up implementation status**: Remove stale agent-spec references and update date
|