Trim design docs: cut narrative, keep reference#43
Merged
Conversation
Force-rewrite of every design doc in docs/ to remove non-essential narrative and keep only what someone reading the file today needs to use or extend dotagent. Code unchanged. Stats: 1718 lines → 556 lines (68% reduction). No content lost that isn't already in the code, tests, or git history. ### docs/CLAUDE_MD_DESIGN.md 555 → 109 lines - Removed: "Why we went from compendium → manifest" history (the redesign shipped; rationale lives in git log). - Removed: token-economics prose + comparison table (one-time argument, not reference material). - Removed: dev↔QA cycle ASCII diagram (gates live in src/dotagent/render/workflow.py + project CLI; doc copy drifts). - Removed: roadmap (most shipped; remaining items in conversation). - Removed: glossary (duplicates section content). - Removed: file-references table (now in the "Related" footer of each doc). - Kept: four-layer model, ownership rule (cleaner table), schema + coverage gates, tier model, how-to-extend, related. ### docs/SERVICE_REPO_CLAUDE_MD.md 403 → 113 lines - Removed: redundant intro paragraphs (TL;DR + "Why a service repo needs its own CLAUDE.md" said the same thing twice). - Removed: full inherited-paths dump (17 paths verbatim; replaced with the path-shape pattern + "see schema"). - Removed: full render-output excerpt (long markdown block; the format is verifiable via `dotagent manifest --tier service-repo`). - Kept: three-tier comparison table, three entry groups (local/contract/inherited), four locked design defaults, git.yaml-project-root-only rationale, auto-regen behaviour, CI guarantees, known limitations. ### docs/DERIVED_FILES_DESIGN.md 230 → 98 lines - Removed: per-generator "Why generated" prose paragraphs (one table row each is enough). - Removed: full schema code-block (lives in canonical_structure.py). - Removed: separate "Output guarantees" section (banner format is in the wiring section). - Kept: top-level table of every generator dotagent owns (extended to include CLAUDE.md / SCOPE.md / CONTRACTS.md / git.md / PLAN.md / contract.frozen.md / contracts.md — was missing those before), per-file detail for the three v0.4.10 additions, wiring + fail-soft + safe-from-any-state notes, limitations. ### docs/HAND_MAINTAINED_DOCS_CONVENTION.md 209 → 128 lines - Removed: implementation prose under "Implementation" (just point at the four files that need updating in unison). - Removed: "If you change this convention" duplicate prose. - Kept (per explicit user request — verbatim preservation): hard-boundary block, structure tree, entry point + per-feature record shape + naming + join keys, dotagent WILL/WILL NOT lists, coexistence table, **verbatim source spec at bottom**. ### docs/DOC_COVERAGE_CLI.md 231 → 108 lines - Removed: duplicate output-format examples (json shows the data; markdown/text formats are the same data in different shapes). - Removed: Coda-side pseudocode + "How Coda uses this" prose (Coda is a different codebase; integration belongs there). - Kept: usage + flags table, severity model table, mapping-rules table, json output sample, hard-boundary, limitations. ### docs/linkedin-followup-post.md 90 lines → DELETED - Marketing/social content. Not dotagent design or operation. Lives in git history if ever needed. ### Tests All 732 tests still pass. The doc trim doesn't touch code; no references to removed files anywhere in src/ or tests/.
dilawarabbas1
pushed a commit
that referenced
this pull request
May 20, 2026
dilawarabbas1
added a commit
that referenced
this pull request
May 20, 2026
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
2 participants
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
Force-rewrite of every design doc in
docs/to remove non-essential narrative. Code unchanged.1718 lines → 556 lines (68% reduction). No content lost that isn't already in the code, tests, or git history.
CLAUDE_MD_DESIGN.mdSERVICE_REPO_CLAUDE_MD.mdDERIVED_FILES_DESIGN.mdHAND_MAINTAINED_DOCS_CONVENTION.mdDOC_COVERAGE_CLI.mdlinkedin-followup-post.mdTest plan
grep -r linkedin-followup\|CODA_PROMPT\|CODE_AUDIT_PLAN docs/ src/ tests/— zero stale refs to removed/renamed docs.What this is not
This is only a doc trim. No schema changes, no renderer changes, no CLI changes, no test changes.
Generated by Claude Code