chore(claude-md): prune CLAUDE.md per hygiene audit (companion to ppds#815) - #18
Merged
Conversation
…o ppds#XXX) Applies the per-line verdicts from the v1-launch hygiene audit (.plans/retro/findings/E-claudemd-hygiene.md in the ppds repo). BEFORE/AFTER: 62 lines -> 29 lines. DELETE: - Title duplication (README has it). - Structure listing (visible in directory tree). - Key Files (docusaurus.config.ts/sidebars.ts are obvious). - "Write marketing fluff" / "Write for the user goal" — vague aspirations. - "Use screenshots without alt text" — markdownlint MD045 enforces. MOVE: - Doc Types (Diátaxis) + Style rules -> .claude/skills/write-docs/SKILL.md (NEW). - Blog Voice -> .claude/skills/write-blog/SKILL.md (NEW). KEEP (passes 4-question test): - Commands table (3 npm scripts Claude cannot guess). - 2 NEVERs (don't document unimplemented features, don't duplicate code). - 3 ALWAYs (test code examples, link to source, use canonical terminology). - Branding pointer (canonical name list). - Pointer to the cross-repo governance doc. [claude-md-reviewed: 2026-04-18] Companion PR to PPDS feat/claudemd-governance.
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request refactors the repository's documentation and blog authoring guidelines by moving specific voice, structure, and style rules from CLAUDE.md into dedicated skill files (write-blog and write-docs). Feedback focuses on fixing a fragile relative link to a governance document, removing redundant rules that still exist in the main CLAUDE.md, and refining instructions regarding copy-pasteable code and accessibility for images.
… text) - CLAUDE.md L5: replace sibling relative path with absolute GitHub URL so the governance reference resolves on GitHub UI, in CI, and from workspace-restricted AI agents. - .claude/skills/write-docs/SKILL.md L38–47: rewrite the copy-pasteability rule to remove the ambiguous "fix mismatches in prod" phrasing, and delete the duplicated test/link/terminology bullets that already live in CLAUDE.md ALWAYS (the exact anti-pattern PR-B is preventing). - .claude/skills/write-blog/SKILL.md L44–48: distinguish informative images (need descriptive alt text) from decorative images (alt="") per WCAG. [claude-md-reviewed: 2026-04-19] Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
joshsmithxrm
marked this pull request as ready for review
April 19, 2026 09:35
joshsmithxrm
enabled auto-merge (squash)
April 19, 2026 09:39
joshsmithxrm
added a commit
that referenced
this pull request
Apr 19, 2026
Brings .claude/rules/branding.md in sync with what actually ships at v1. The freshly-pruned CLAUDE.md (#18) points to this file as the canonical name list, so stale content here actively misleads any AI session authoring docs. Changes: - Remove PPDS.Tools and PPDS ALM from the Components table (not shipping at v1, can be re-added when they do) - Remove ppds-tools and ppds-alm from the Repositories table - Remove the PSGallery link (no PPDS.Tools package) - Main repo description: SDK -> Libraries - Value prop: "standard SDK patterns" -> "standard Dataverse SDK patterns" (disambiguates Microsoft's SDK from PPDS libraries) - New Terminology section explicitly calling out libraries-vs-SDK and the NoSdkInPresentationAnalyzer rule that enforces the same convention in code Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2 tasks
joshsmithxrm
added a commit
that referenced
this pull request
Apr 19, 2026
#19) Brings .claude/rules/branding.md in sync with what actually ships at v1. The freshly-pruned CLAUDE.md (#18) points to this file as the canonical name list, so stale content here actively misleads any AI session authoring docs. Changes: - Remove PPDS.Tools and PPDS ALM from the Components table (not shipping at v1, can be re-added when they do) - Remove ppds-tools and ppds-alm from the Repositories table - Remove the PSGallery link (no PPDS.Tools package) - Main repo description: SDK -> Libraries - Value prop: "standard SDK patterns" -> "standard Dataverse SDK patterns" (disambiguates Microsoft's SDK from PPDS libraries) - New Terminology section explicitly calling out libraries-vs-SDK and the NoSdkInPresentationAnalyzer rule that enforces the same convention in code Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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
Prune ppds-docs
CLAUDE.mdper the v1-launch hygiene audit (62 → 29 lines).Companion to PPDS PR #815 (
feat/claudemd-governance) — that PR adds the governance hooks, thedocs/CLAUDE-MD-GOVERNANCE.mddoc, and the equivalent prune of the PPDS rootCLAUDE.md.Changes
CLAUDE.md62 → 29 lines per per-line verdicts in the hygiene audit table..claude/skills/write-docs/SKILL.md— Diátaxis classification, voice rules, doc lifecycle. Auto-loads when authoring docs..claude/skills/write-blog/SKILL.md— first-person voice, post structure, anti-patterns. Auto-loads when authoring blog posts.What was removed from CLAUDE.md
docusaurus.config.ts,sidebars.tsare obvious from any Docusaurus project).What was kept
Includes the
[claude-md-reviewed: 2026-04-18]marker per the new governance contract.Test plan
write-docsandwrite-blogskills load when expected.🤖 Generated with Claude Code