docs(ai): update lexicon sync guidance to prioritize method documentation

Without this patch, the lexicon sync skill and spec incorrectly emphasized
documenting types rather than methods. This led to adding JSDoc on type
aliases (which users don't directly interact with) instead of on the SDK
methods that users actually call.

This is a problem because:
- Users call methods like createCollection(), not types like HypercertCollection
- Method documentation is where users look for usage examples
- Type documentation becomes redundant when methods are well-documented
- Previous changes incorrectly marked type docs as complete when method docs weren't done

This patch solves the problem by:

- Updating sync-lexicons SKILL.md to emphasize method documentation over type docs
- Clarifying that method JSDoc should include @example tags showing new features
- Updating the spec to accurately reflect what documentation was actually completed
- Marking Change 2 and 3 as partially complete (tests done, method docs still needed)
- Adding notes explaining that Change 1 already has method docs with examples

Changes to sync-lexicons skill:
- Step 7 now focuses on documenting methods in HypercertOperationsImpl.ts
- Added guidance to keep type documentation minimal
- Updated example task list to mention method documentation explicitly
- Added "IMPORTANT: Document methods, not types" callout

Changes to spec:
- Change 1: Removed type doc tasks, noted method docs already exist
- Change 2: Marked method doc tasks as incomplete, added note
- Change 3: Marked method doc tasks as incomplete, added note

Spec: specs/lexicon-sync/v0.10.0-beta.4-v0.10.0-beta.11.md

Co-authored-by: Claude Code <claude-code@noreply.anthropic.com>

Author: aspiers

.claude/skills/sync-lexicons/SKILL.md

@@ -153,9 +153,10 @@ Example plan structure:
 
 **SDK Tasks**:
 
-- [ ] Add/update documentation for X
-- [ ] Add type exports for Y
-- [ ] Add usage examples
+- [ ] Add/update JSDoc documentation to methods (e.g., createX(), updateX())
+- [ ] Add type exports for Y if needed
+- [ ] Add usage examples in method documentation
+- [ ] Add/update tests
 - [ ] Build and test
 - [ ] Create changeset (minor/major - reason)
 
@@ -217,15 +218,18 @@ Present this plan to the user and ask:
 
 For the current change (e.g., "Change 1: Collection Item Weights"):
 
-1. **Update documentation** in `packages/sdk-core/src/services/hypercerts/types.ts`:
-   - Add JSDoc comments for new/changed types
-   - Add usage examples
+1. **Update method documentation** - Focus on documenting the methods users will call:
+   - Add/update JSDoc comments on SDK methods (e.g., `createCollection()`, `updateCollection()`)
+   - Add usage examples in method documentation showing new features
+   - Document parameters, return values, and behavior
    - Document breaking changes if any
+   - Location: `packages/sdk-core/src/repository/HypercertOperationsImpl.ts` and interfaces
 
 2. **Add type exports** if needed:
-   - Add type aliases for new lexicon types
-   - Add helper types for SDK operations
+   - Add type aliases for new lexicon types in `packages/sdk-core/src/services/hypercerts/types.ts`
+   - Add helper types for SDK operations (CreateParams, UpdateParams, etc.)
    - Export from appropriate modules
+   - Keep type documentation minimal - let method docs do the heavy lifting
 
 3. **Update SDK code** if needed:
    - Modify operations to support new fields
@@ -325,9 +329,15 @@ The sync process focuses on making SDK changes visible and usable to developers.
 
 ### Documentation Updates
 
-1. **Type documentation** - JSDoc comments explaining new features
-2. **Usage examples** - Code snippets showing how to use new fields/types
-3. **Breaking change notes** - Clear warnings about incompatible changes
+**IMPORTANT**: Document methods, not types. Users call methods, not types.
+
+1. **Method documentation** - JSDoc comments on SDK methods explaining new features
+   - Focus on `createX()`, `updateX()`, `getX()` methods in `HypercertOperationsImpl.ts`
+   - Document parameters, return values, and behavior
+   - Add `@example` tags showing how to use new fields
+2. **Usage examples** - Code snippets in method docs showing how to use new fields/types
+3. **Breaking change notes** - Clear warnings in method docs about incompatible changes
+4. **Type documentation** - Keep minimal; types should be self-explanatory from method docs
 
 ### Type System Updates
 

specs/lexicon-sync/v0.10.0-beta.4-v0.10.0-beta.11.md

@@ -25,8 +25,7 @@ implemented, validated, and reviewed before proceeding to the next.
 
 **SDK Tasks**:
 
-- [x] Add documentation to `HypercertCollectionItem` type about the weight property
-- [x] Add usage examples in type documentation
+- [x] Add usage examples in method documentation showing weighted items (already has example in createCollection)
 - [x] Verify `CollectionItemInput` helper type is correct (already supports itemWeight)
 - [x] Verify CRUD operations support itemWeight (createCollection/updateCollection already pass items through)
 - [x] Add/update tests for collections with weighted items
@@ -60,13 +59,15 @@ implemented, validated, and reviewed before proceeding to the next.
 - [x] Import `AppBskyRichtextFacet` from `@atproto/api` in interfaces.ts
 - [x] Add `shortDescriptionFacets` and `descriptionFacets` fields to `CreateHypercertParams`
 - [x] Update `create()` method in `HypercertOperationsImpl` to handle facet fields
-- [x] Add comprehensive documentation to `HypercertClaim` type about facets
-- [x] Add usage examples showing how to create facets for mentions, links, and tags
+- [ ] Add JSDoc documentation to `create()` method about facets
+- [ ] Add usage examples in method documentation showing how to create facets for mentions, links, and tags
 - [x] Add tests for creating hypercerts with facets
 - [x] Verify facets are properly validated by lexicon validator
 - [x] Build and test
 - [x] Create changeset (minor - new feature available)
 
+**Note**: Method documentation for facets is still needed but tests are complete.
+
 **Validation**:
 
 - [x] Format check passes (`pnpm format:check`)
@@ -93,11 +94,14 @@ implemented, validated, and reviewed before proceeding to the next.
 
 - [x] Verify `CreateCollectionParams` already supports avatar/banner (already supports)
 - [x] Verify `createCollection()` and `updateCollection()` methods handle avatar/banner (already implemented)
-- [x] Add usage examples showing avatar/banner in collections and projects
+- [ ] Add JSDoc documentation to `createCollection()` and `updateCollection()` methods about avatar
+- [ ] Add usage examples in method documentation showing avatar in collections and projects
 - [x] Add/update tests for collections with avatar and banner
 - [x] Build and test
 - [x] Create changeset (minor - new feature available)
 
+**Note**: Method documentation mentions banner but not avatar. Tests are complete.
+
 **Validation**:
 
 - [x] Format check passes (`pnpm format:check`)