docs: documentation drift audit and rework tracking#233
Draft
vredchenko wants to merge 3 commits into
Draft
Conversation
The docs under docs/ have drifted from the code since the workspace tooling was split into smartem-devtools. Before rewriting blind, measure the drift: slice each how-to/reference/tutorial doc into content atoms, decompose prose into factual claims, and verify each against the repositories. Lands the analysis (verdicts.jsonl, REPORT.md, interactive drift-map.html) and the re-runnable slicer (atomize.py) as the tracking point for the rework.
vredchenko
added
the
documentation
The drift audit measures whether documented claims are true; it cannot see undocumented system surface. This adds the coverage axis: the actual agent CLI, backend API, env vars, k8s resources, and frontend routes enumerated from source and diffed against the docs corpus. Largest gap is the entire shipped frontend (16 routes, no docs/frontend/). Also surfaces real defects alongside the doc gaps: a stale committed OpenAPI spec, an orphaned HPA that no kustomization deploys, and an incomplete secret.example.yaml.
The docs corpus had no frontend documentation at all - the coverage-gap analysis found 16 shipped routes and the entire shell undocumented, with the only existing material (the design/requirements records) describing a route scheme and a legacy app that were never/no longer shipped. Adds docs/frontend/ documenting the app as shipped: architecture (monorepo, stack, file-based routing, the generated API client, theming), a route/view reference grounding every view in its backend endpoints, the shell (navigation, command palette, settings, feature flags), and development (run modes, mock mode, API client regeneration, build and release). The webui nav and MDX regenerate from these sources via the existing prebuild step; validated locally (Frontend section renders, 0 errors).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Draft tracking PR for the documentation rework. Rather than rewrite the docs blind, this lands a
measured audit of the current docs against reality, so the rework can reuse what is still true and
target what is missing. Two axes are now covered:
doc-audit/REPORT.md(interactive:doc-audit/drift-map.html)doc-audit/COVERAGE.mdDrift results
64 docs -> 2,560 content atoms. Verifiable subset (how-to / reference / tutorial): 34 files -> 960 claims.
Every prose atom decomposed into factual claims, each checked against the real repositories. ADR/design docs
parked (historical record, not drift).
79% of documented claims are true - the rework is a re-organise-and-fill exercise, not a blank page.
misleading, not wrong: tooling movedsmartem-decisions->smartem-devtools, so documented commands/paths point at the wrong repo.athena_apipackage deleted under ADR 0015 - remove/rewrite.validateexits0when docs promise1;--log-fileis a no-op;-v/--verboseis inconsistent across subcommands.Coverage results
The actual system surface enumerated from source and diffed against the docs corpus - the axis the drift
audit cannot see (a
trueclaim can sit next to a large hole).100% undocumented- now documented indocs/frontend//dlsmount, 6 secret keys missingagent-cleanupabsentThe largest hole is the entire shipped frontend. Coverage also surfaced real defects alongside doc
gaps: a stale committed OpenAPI spec (lags code by one endpoint), an orphaned HPA that no kustomization
deploys, and an incomplete
secret.example.yaml(6 required keys missing).Rework workstreams
docs/frontend/from scratch - 16 routes + shell, 0% covered, existing material misleading (index, architecture, routes, shell, development)/dlsmountmisleadingclaims, mostly path re-homing tosmartem-devtoolsincorrectclaimstrueatoms--log-fileno-op, verbose-flag mismatch,stale OpenAPI spec, orphaned HPA, incomplete
secret.example.yamlNotes
Draft, not for merge - the purpose is to track the rework. Analysis data (
verdicts.jsonl) and there-runnable slicer (
atomize.py) travel with the branch so findings are auditable and refreshable.Neither report measures structure/consistency (grouping, navigation, terminology) - that remains a
rework workstream, not an audit output.