chore(claude): audit contribution guidelines for skill coverage and enforcement - #2009
Open
mindapivessa wants to merge 6 commits into
Open
mindapivessa wants to merge 6 commits into
mindapivessa wants to merge 6 commits into
Conversation
Audits the four "Reference Files" guideline docs (content-guidelines.md,
ia-guidelines.md, mintlify-reference.md, scripts/README.md) for enforcement
gaps and closes them:
- Add three Claude skills that were missing coverage entirely:
- mintlify-components: component selection while *authoring* MDX, not
just linting after the fact
- writing-spec-pages: Specifications-tab page types/structure/writing
rules (content-guidelines.md had ~100 lines with zero skill coverage)
- writing-changelog-entries: changelog section structure and file
naming convention (also zero prior skill coverage)
- Fix a broken relative link in lint.md (../../mintlify-reference.md was
missing the docs/ segment)
- Add the missing .claude/commands/doc-feedback.md — CLAUDE.md has
documented `/doc-feedback` as a command since before this change, but
the command file never existed, only the underlying skill
- Merge the "Base app" brand-spelling rule into docs/content-guidelines.md
(Brand Terminology). It previously existed only inside a forked copy in
.cursor/rules/content-guide.mdc, invisible to any Claude Code skill
- Slim .cursor/rules/content-guide.mdc and mintlify.mdc from full forked
copies of the canonical docs down to pointers, removing the second
source of truth that had already drifted
- Cross-link doc-feedback.md to the new skills and add an "Enforced by"
column to CLAUDE.md's References table
docs/content-guidelines.md and docs/ia-guidelines.md stay in docs/ — they're
gated by .github/ia-governance.json (IA Gate / Guideline Files, 1 Governance
Owner approval), and the config also lists bare root-level filenames as
protected paths, suggesting relocation could bypass the gate. The Claude
skills are the enforcement layer on top of these files, not a replacement.
npm test passes (85/85).
Generated with Toshi
Drop the ### Accessibility subsection (alt text, link text, heading hierarchy, keyboard nav, color contrast) per request. Note: scripts/lint-mdx.js still enforces the related checks in code (a11y/alt-text, a11y/link-text, a11y/image-frame, heading/starts-at-h2, heading/redundant-page-title) and its comments cite this prose as rationale — linter behavior is unchanged, only the doc description is gone. Removing the rules themselves would be a separate change. npm test passes (85/85). Generated with Toshi
Reviewed Writing Rules for points that were generic technical-writing
boilerplate rather than Base-specific, enforced, or otherwise actionable:
- Language and Style: dropped "use clear, direct language" (tautological),
"present tense for current states, future tense for outcomes" (unenforced,
confusing framing), "keep sentences concise" and "use parallel structure"
(vague, unverifiable). Kept second person, active voice, jargon/define
terms, and consistent terminology (the last is enforced by
scripts/check-terminology.js).
- Merged Content Organization and User-Centered Approach: both had
low-signal generic advice ("lead with the most important information",
"focus on user goals", "anticipate common questions", "write for
scannability" — the last also duplicated a line from the Accessibility
section removed last commit). Kept the concrete, actionable bullets
(numbered steps, prerequisites, expected outcomes, keyword-rich headings,
troubleshooting, verification steps) as a single Content Organization
list.
- API Documentation: dropped "cover complete request/response cycles" —
redundant with "show both success and error response examples".
- Grouping Rules: the section had two paragraphs restating the same "3+
pages -> nested group" rule almost verbatim. Merged into one paragraph.
Specification Pages, Changelog Entries, Component Selection, Code Examples,
and Required Page Structure were left untouched — those are Base-specific,
concrete, and mostly linter-enforced.
npm test passes (85/85).
Generated with Toshi
Reviewed for unnecessary points the same way as content-guidelines.md.
Unlike content-guidelines.md, this file is almost entirely Base-specific
"belongs / does not belong" placement rules — there's no generic
technical-writing filler to cut. Found two genuine issues instead:
- Get Started > Solutions and the Build on Base tab both stated the exact
same governance sentence verbatim ("Before adding a new solution or
renaming a section, you need approval from Eric Brown and Mind
Apivessa..."). Only the Build on Base instance maps to an actual CI
check (IA Gate / Build on Base Solutions in .github/ia-governance.json,
scoped to that tab); duplicating the full sentence risked the two
drifting if the approvers ever change. Replaced the Get Started copy
with a cross-reference to the canonical one.
- Get Started > Get Funding's "Does not belong" bullet ended with a
dangling, ungrammatical fragment ("Full detail on the programs.") that
didn't parse as either a belongs or does-not-belong statement and added
no actionable meaning. Removed it.
Everything else (tab/section belongs-does-not-belong rules, Decision Log,
Naming Conventions, Navigation Structure, Placeholder Pages) is
Base-specific and directly used by the docs-ia skill, so left as-is.
npm test passes (85/85).
Generated with Toshi
Contributor
|
Preview deployment for your docs. Learn more about Mintlify Previews.
💡 Tip: Enable Automations to automatically generate PRs for you. |
Collaborator
🟡 Heimdall Review Status
|
youssefea
reviewed
Sep 24, 2026
youssefea
reviewed
Sep 24, 2026
@youssefea flagged on the Brand Terminology section (added when this PR merged it in from .cursor/rules/content-guide.mdc) that it may be stale given the Base App rebranding. Removing it entirely rather than updating it — nobody on this thread has the current authoritative spelling, and shipping guidance that's already suspected stale is worse than shipping none. - docs/content-guidelines.md: removed the Brand Terminology subsection - .cursor/rules/content-guide.mdc: removed the verbatim-kept copy and the paragraph explaining the migration (now moot) If a current Base App naming convention exists, it should be added back as a fresh PR from whoever owns that decision, not carried over from the old Cursor rule. npm test passes (85/85). Generated with Toshi
youssefea
reviewed
Sep 24, 2026
Approval requires 1 of the 2 named Governance Owners, matching .github/ia-governance.json (governanceOwners: ericbrown99, mindapivessa; count: 1) — not sign-off from both. npm test passes (85/85). Generated with Toshi
youssefea
approved these changes
Sep 24, 2026
This branch was successfully deployed
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
3 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.
What changed? Why?
Audited the four "Reference Files" in
CLAUDE.md(content-guidelines.md,ia-guidelines.md,mintlify-reference.md,scripts/README.md) to make enforcement easier for Claude Code agents:content-guidelines.md's Specification Pages and Changelog Entries sections (~165 lines) had zero skill coverage, and Mintlify component guidance was only linked from the linter (after-the-fact, not while authoring):.claude/skills/mintlify-components.md.claude/skills/spec-pages.md.claude/skills/changelog-entries.mdlint.mdwas missing adocs/segment;CLAUDE.mdhas documented/doc-feedbackas a command since before this PR but the command file never existed (only the skill) — added.claude/commands/doc-feedback.md..cursor/rules/content-guide.mdcandmintlify.mdcwere full forked copies of the canonicaldocs/*.mdfiles and had already drifted from them — most notably a "Base app" brand-spelling rule that existed only in the Cursor copy, invisible to any Claude skill. Slimmed both Cursor rules down to pointers at the canonicaldocs/*.mdfiles so there's a single source of truth going forward. (The Base app spelling rule itself was dropped rather than carried over — see point 5.)content-guidelines.md: removed the Accessibility subsection, generic/unenforceable technical-writing boilerplate (present/future tense, parallel structure, "write clear language", etc.), a redundant API-docs bullet, and a near-verbatim duplicated paragraph in Grouping Rules.ia-guidelines.md: removed a verbatim-duplicated governance sentence (Get Started > Solutions vs. Build on Base tab — only the Build on Base one maps to an actual CI gate) and a dangling, ungrammatical fragment in the Get Funding section.ia-guidelines.mdsaid Build on Base changes need approval from "Eric Brown and Mind Apivessa" — it's actually or, matching.github/ia-governance.json(governanceOwners: [ericbrown99, mindapivessa],count: 1).docs/content-guidelines.mdanddocs/ia-guidelines.mdintentionally stay indocs/— they're gated by.github/ia-governance.json(IA Gate / Guideline Files, 1 Governance Owner approval), which also lists bare root-level filenames as protected paths, suggesting relocation could silently bypass the gate. The new Claude skills are the enforcement layer on top of these files, not a replacement.Notes to reviewers
docs/content-guidelines.mdanddocs/ia-guidelines.md, which will tripIA Gate / Guideline Files— needs 1 Governance Owner approval (ericbrown99 or mindapivessa) before merge..mdxpages ordocs.jsonnav changed — all edited files are contributor/agent-facing.md/.mdcguideline files, not rendered site content.How has it been tested?
npm testpasses (85/85) after every commit..claude/skills/*.md,.claude/commands/doc-feedback.md).Screenshots
N/A (no user-facing changes — this PR only touches contributor-facing guideline docs, Claude skills, and Cursor rules, none of which are rendered Mintlify pages)