docs: refresh all CLAUDE.md guides — correct, de-duplicate, trim (~68% smaller) - #702
docs: refresh all CLAUDE.md guides — correct, de-duplicate, trim (~68% smaller)#702ari-nz wants to merge 6 commits into
Conversation
bucket, dataset, notebook, system, wsi and qupath CLAUDE.md described APIs, CLI commands, classes and behaviour that do not exist in the code (multi-cloud storage, resumable downloads, handler ABCs, fake service methods, wrong QuPath version, etc.). Rewritten from the actual _service.py/_cli.py/__init__.py of each module, following a lean template: purpose, real public API, real CLI commands, non-obvious behaviour, dependencies. Point to source and pyproject rather than restating.
Root, src/aignostics, platform and application CLAUDE.md: fix stale facts (coverage 70/75 not 85, package at 1.4.0 not beta.7, no [gui] extra / launchpad command, application_version= param, phantom service methods, SDK schema version, State/Output enums vs models) and cut verbatim source dumps, ASCII art and generic tutorials. Apply DRY: point to pyproject / _sdk_metadata.py / platform CLAUDE.md instead of restating. Add a verified module-dependency graph (src/aignostics) and a run/item/artifact lifecycle state diagram (platform) as theme-safe mermaid.
tests/CLAUDE.md: replace fabricated directory tree and fixtures/ layout with the real tests/ and tests/resources/ contents, drop the invented COVERAGE_REQUIREMENTS dict, fix the schema-version and build_run_sdk_metadata examples, point markers to pyproject; cut generic pytest tutorial content. .github/CLAUDE.md: fix scheduled-workflow filenames and cadence (hourly + daily, not 6h/24h), ci-cd job list and triggers, Claude interactive/PR-review triggers, and the OS-runner test matrix; collapse duplicate tables.
Remove duplicated file lists and doubled MCP/user-agent sections in utils, fix the load_settings example (pydantic_settings.BaseSettings). Drop the stale reproduced health snippet in gui and point to system/CLAUDE.md for health enforcement.
Remove the hardcoded 'theme':'dark' mermaid init from the platform-workflow sequence diagram so GitHub renders it with its theme-aware default in both light and dark mode.
Add a PEP 621 maintainers array (Oliver Meyer, Arne Baumann) alongside authors.
Review notesPosted by Claude (Fable 5) via Claude Code, at the request of @ari-ai-gnostics. I verified the branch against the module source rather than reading the diff top-to-bottom. This is a strong, high-value change. It removes real liability rather than just trimming prose. Two distinct kinds of change worth separating when reviewing: 1. Six guides rewritten because they were fabricated ( 2. Core guides condensed (root 1872→1158, platform 1676→711, plus tests/CI/application/utils/gui). I checked the root guide's structure — every load-bearing section survived (Development Commands, Architecture Principles, Dependency Graph, SDK Usage, Code Standards, Build System, Testing Requirements, Important Notes). Tighter, not gutted. Suggestions for reviewers
Net: verifiable and, where I checked, correct. 👍 |
Codecov Report✅ All modified and coverable lines are covered by tests. |
|
1 participant
What
A full refresh of every
CLAUDE.mdin the repo (14 files), plus a README diagram fix and apyproject.tomlmaintainers addition.Each doc was reviewed against the actual current source, then either rewritten (where it described code that doesn't exist) or corrected and condensed (where the narrative was sound but stale/bloated). Guiding principle: state a fact once, then point — versions, markers, coverage config, deps, and API signatures now point to their source of truth (
pyproject.toml,_sdk_metadata.py, source files, or the owning doc) instead of being restated and drifting.The numbers
The 14
CLAUDE.mdfiles went from ~10,360 lines to ~3,300 — roughly a 68% cut (net +1,129 / −8,151 across the 17 changed files). What was removed falls into three buckets:bucketdocumented multi-cloud + encryption + resumable downloads (it's a GCS-only signed-URL wrapper);notebook/dataset/system/wsi/qupathinvented service methods, CLI commands, and handler classes;applicationhad a wrongversion_number=param repeated ~9×; coverage claimed "85% enforced" (it's 70/75 incodecov.yml); "NEW in v1.0.0-beta.7" framing (package is 1.4.0); scheduled-workflow filenames all renamed since_sdk_metadata.py); ASCII diagrams re-drawing a sentence; marker lists / coverage numbers / schema versions copied frompyproject.toml; two identical workflow tables in.github; a duplicate file list inutilsgrep/git/pytest; aspirational "Future Enhancements" / "Monitoring & Observability" / "Performance Optimization" sections describing nonexistent code; marketing ("battle-tested across thousands of CI/CD runs")The six module docs (
bucket,dataset,notebook,system,wsi,qupath) were majority-fabricated and were rewritten from scratch; the rest were corrected in place.Also in this PR
'theme':'dark'init that rendered as white-on-dark dumped onto GitHub's light background. Removed it so GitHub's theme-aware default handles both modes. (TheSOFTWARE_ARCHITECTURE.md/specifications/*.mddiagrams never had this and were left alone.)src/aignostics/CLAUDE.md(which also corrected the stale dependency text) and a run/item/artifact lifecycle state diagram inplatform/CLAUDE.md.pyproject.toml— added a PEP 621maintainersarray (Oliver Meyer, Arne Baumann).Reviewing
Six logical commits, each independently reviewable:
Not done (deferrable follow-ups)
src/aignostics/CLAUDE.md's per-module descriptions already cover orientation; happy to add short verified bullet lists as a follow-up if wanted.qupath/_service.pyinstall_qupathdocstring still says the default is"0.5.1"while the actual default isQUPATH_VERSION(0.6.0).