chanora/docs/offline-knowledge/doc-quality-analysis.md

Documentation Quality Analysis

Summary

• Total docs analyzed: 64
• Duplicated content instances: 8
• Useless content items: 1 (malformed markdown only)
• 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

Useless Content

Empty Sections

File	Line	Header	Issue
docs/architecture/sysdes.md	1-21	Entire file	Path record file — 21 lines pointing to docs/sysdes.md with no unique content
docs/requirements/sysrs.md	1-22	Entire file	Path record file — 22 lines pointing to docs/sysrs.md with no unique content
docs/requirements/srs.md	1-22	Entire file	Path record file — 22 lines pointing to docs/srs.md with no unique content
docs/ui-ux/material3-guideline.md	1-8	Entire file	Path record file — 8 lines pointing to docs/material3-guideline.md
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	4-6 identical commit message examples
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