Skip to content

chore(SDK-971): improve tsdoc tooling after first backfill round#2009

Open
mariechatfield wants to merge 1 commit into
mainfrom
marie/improve-tsdoc-skills
Open

chore(SDK-971): improve tsdoc tooling after first backfill round#2009
mariechatfield wants to merge 1 commit into
mainfrom
marie/improve-tsdoc-skills

Conversation

@mariechatfield
Copy link
Copy Markdown
Contributor

@mariechatfield mariechatfield commented Jun 4, 2026

Summary

Jira: SDK-971

Improvements to the internal TSDoc tooling after running the first phase of the backfill. Adjustments were driven by what we learned from actually running the agents at scale.

  • tsdoc-api-documenter agent: Expanded instructions with more precise rules for when to use @public vs @internal, how to handle re-exports, and common pitfalls (e.g. don't document symbols only exported for testing). Removed the tsdoc-file skill dependency — the agent now has the full guidance inline.
  • tsdoc-backfill agent: Tightened scope rules so the agent doesn't drift into undocumented territory or over-document internal symbols.
  • tsdoc-directory skill: Simplified — removed redundant guidance now covered by the agents directly.
  • tsdoc-file skill: Deleted — was superseded by the improved agent instructions.
  • knip command + script: Added .claude/commands/knip.md and .claude/scripts/knip-fix.sh to support running knip to surface unused exports and files after a backfill round, as a quality check.
  • knip config: Added .reports/config/knip.json with project-appropriate ignore patterns (test files, Storybook stories, etc.).
  • tsdoc stubs (build/tsdoc-stub.ts, build/tsdoc-stub-lib.ts): Simplified — removed unused options and dead paths exposed by the backfill work.
  • eslint config: Minor update to allowlist path for TSDoc coverage tracking.

Test plan

  • Run npm run build to confirm the stubs still compile cleanly
  • Spot-check that the knip script runs: npx knip --config .reports/config/knip.json

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Comment thread .claude/commands/knip.md
Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Support to run /knip <directory> directly, so that you can do a targeted removal of any unused code. Uses npx knip so we don't have to increase our developer dependencies. The full run is... a lot of unused code removal. Feels better to do in groups as we document

@mariechatfield mariechatfield marked this pull request as ready for review June 4, 2026 00:26
@mariechatfield mariechatfield requested a review from a team as a code owner June 4, 2026 00:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant