ds-doctor
Skill8 starsChanged 3 months agoMITView on GitHub
Audit whether a design system can be enforced, and generate its conformance manifest (ds/MANIFEST.md + ds/tokens.json).
The file
Files
ds-doctor
Audit the design system as the subject — its contracts, tokens, guidelines, and machine surface — and produce the one artifact everything downstream reads: the conformance manifest. A conformance gate is only as precise as the standard it enforces: nobody can police "use the right component" against a DS that never says whether Chip or Tag is right, and an agent generating work can't follow guidelines that exist only in a maintainer's head.
This skill is report-only and every output must survive a cold read — both terms, the family rules they summarize, and the plans/ directory conventions are defined in ../ds-drift/references/conventions.md. Read it now; it is short and load-bearing.
Skill rules
- This skill's writes are the manifest pair —
ds/MANIFEST.md+ds/tokens.json— and plans underplans/; documentation gaps become doc-fix plans, never edits (report-only applies to the DS's source and docs exactly as it does to app code). - Regeneration rewrites
generatedzones and preserveshand-maintainedzones verbatim. The zone markers are defined in the manifest spec, one marker per section. On a conflict between a hand zone and regenerated content, stop and report which section conflicts; resolving it is the DS owner's call.
Done means
A run is done when: the readiness summary names every category ready / partial / absent with a one-line reason; every finding cites file:line (or the precisely named absent file); the manifest pair, if written, validates against the spec — schema number stamped, generated zones complete, hand zones byte-identical to before; and each selected doc-fix plan survives a cold read. The quality check in Phase 4 confirms this before you finish.
Workflow
Phase 1 — Recon
Read references/manifest-spec.md first — the manifest is the run's primary output, and knowing its exact shape (zones, header stamps, tokens.json schema) determines what the audit must collect. Then locate the subject: the DS package(s) and public entry points, prop types, docs (MDX, Storybook stories, doc sites in-repo), token sources (CSS custom properties, Tailwind config, theme objects, token packages), changelog/deprecation records, and any existing ds/MANIFEST.md — read its hand-maintained zones first; they are prior decisions, not audit targets. Record the exact commands that build docs/stories and typecheck the package; they become verification gates in doc-fix plans.
Phase 2 — Audit
Audit against the categories in references/readiness-playbook.md — read it now: component contracts, token layer, guidelines & policy, machine surface, deprecation hygiene. The audit's organizing question is always: could an agent that has never seen this codebase use — or police — this correctly from what's written down? For large systems, fan out read-only subagents per category with the playbook path, the recon facts, a findings-only instruction, and a verbatim copy of family rules 3–5 (subagents inherit nothing).
Phase 3 — Vet
Open every cited location yourself before it reaches the table. Expected failure classes: guidance that exists but lives somewhere unindexed (a finding about discoverability, not absence — say which); intentionally undocumented internals (not every export is public API — check the entry point); duplicates across subagents. Record rejections in the plans index.
Phase 4 — Present, then write
Present, in order: the readiness summary (per category: ready / partial / absent, with the one-line reason), the vetted findings table ordered by leverage — where impact is measured in downstream effect: a gap that makes a whole category unenforceable outranks any single missing docstring — and a manifest diff preview (what regeneration will change, hand zones untouched). Then ask which findings become doc-fix plans; default suggestion, the top 3–5.
On confirmation: write the manifest pair per the spec and the selected plans per references/plan-template.md into plans/ with the shared index. Doc-fix plans are ideal cheap-executor work; write them that way. Before finishing, run the plan template's quality bar over each plan, re-check the manifest against the spec's zone and header requirements, and confirm every clause of Done means above.
State gaps plainly with evidence and downstream cost, credit what's already good, and prefer "this area is ready" over invented findings. The readiness summary should be quotable in a planning meeting.
Invocation variants
- Bare invocation → full workflow above.
manifest→ the fast path: regenerate the manifest pair from current DS state, report only the blockers that make it incomplete (e.g. unresolvable token references), skip the full findings table. Run this after any DS release.component <name>→ audit one component's contract in depth; useful before promoting an extraction candidate.tokens→ token-layer category only.quick/deep→ effort dial for the audit;deepreads every exported component,quicksamples the highest-traffic ones (by import count in sibling apps, if visible).--issues→ also publish selected plans as GitHub issues. Follow ../ds-drift/references/closing-the-loop.md — read it before creating anything.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

