@brainfish-ai/devdoc 0.1.32 → 0.1.34

package/ai-agents/.claude/skills/blame-doc/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: blame-doc
+description: Analyze documentation for duplicates, outdated content, and discrepancies with codebase
+---
+
+## Instructions
+
+Perform a deep analysis of documentation quality, finding issues that need attention.
+
+### Step 0: Read Context
+
+**Read `.devdoc/context.json` if it exists** for product info and terminology.
+
+**Read `docs.json`** to understand documentation structure.
+
+### Step 1: Scan Codebase
+
+Analyze the source code to understand:
+- Exported functions, classes, types
+- API endpoints and routes
+- Configuration options
+- Feature flags and capabilities
+
+### Step 2: Analyze Documentation
+
+Scan all MDX files for:
+- Topics covered
+- Code examples used
+- Features documented
+- API references
+
+### Step 3: Generate Blame Report
+
+```
+Documentation Blame Report
+==========================
+
+Generated: [date]
+Files analyzed: X docs, Y source files
+
+## 🔴 Critical Issues
+
+### Duplicate Content (count)
+
+Content that appears in multiple places, causing maintenance burden:
+
+| Topic | Files | Recommendation |
+|-------|-------|----------------|
+| Authentication setup | auth.mdx, quickstart.mdx, api/overview.mdx | Consolidate to auth.mdx, link from others |
+| Error handling | errors.mdx, troubleshooting.mdx | Merge into single page |
+
+**Details:**
+- `auth.mdx:15-45` and `quickstart.mdx:80-110` contain nearly identical OAuth setup instructions
+- `errors.mdx` and `troubleshooting.mdx` both list the same error codes
+
+### Outdated Documentation (count)
+
+Docs that don't match current codebase:
+
+| File | Issue | Current State |
+|------|-------|---------------|
+| api/users.mdx | Wrong signature | `getUser(id)` is now `getUser(id, options)` |
+| config.mdx | Missing options | `timeout` and `retries` not documented |
+| quickstart.mdx | Old version | References v1.x, current is v2.x |
+
+**Details:**
+- `api/users.mdx:23` shows `getUser(id: string)` but code has `getUser(id: string, options?: UserOptions)`
+- `config.mdx` missing 3 new configuration options added in v2.0
+
+### Code-Doc Discrepancies (count)
+
+Mismatches between documented and actual behavior:
+
+| File | Documented | Actual |
+|------|------------|--------|
+| api/auth.mdx | Returns `{ token }` | Returns `{ token, expiresAt }` |
+| guides/setup.mdx | Requires Node 14+ | package.json requires Node 18+ |
+| api/errors.mdx | Error code 401 | Code throws 403 for this case |
+
+## 🟡 Warnings
+
+### Undocumented Features (count)
+
+Code exists but no documentation:
+
+- `src/utils/retry.ts` - Retry utility with backoff (exported, no docs)
+- `src/api/webhooks.ts` - Webhook handlers (3 endpoints, no docs)
+- `src/config/advanced.ts` - Advanced options (12 options, not in config.mdx)
+
+### Stale Examples (count)
+
+Code examples that may not work:
+
+| File | Line | Issue |
+|------|------|-------|
+| quickstart.mdx | 45 | Uses deprecated `init()`, should be `initialize()` |
+| api/fetch.mdx | 23 | Import path changed from `pkg` to `pkg/client` |
+
+### Inconsistent Terminology
+
+Terms used differently across docs:
+
+| Term | Variations Found | Recommended |
+|------|------------------|-------------|
+| API key | "api key", "API Key", "apiKey", "api-key" | "API key" |
+| endpoint | "endpoint", "route", "URL", "path" | "endpoint" |
+
+## 🟢 Good Practices Found
+
+✓ All public exports have corresponding docs
+✓ Code examples have language tags
+✓ Consistent use of components (Note, Warning, etc.)
+
+## Recommendations
+
+### High Priority
+1. **Consolidate auth docs** - Merge duplicate OAuth content into single source
+2. **Update API signatures** - 5 files have outdated function signatures
+3. **Document webhooks** - Major feature with zero documentation
+
+### Medium Priority
+4. **Version bump** - Update all version references to v2.x
+5. **Standardize terminology** - Create glossary in context.json
+
+### Low Priority
+6. **Add missing options** - Document 12 config options
+7. **Fix stale examples** - Update deprecated imports
+```
+
+## Analysis Techniques
+
+### Finding Duplicates
+
+Look for:
+1. **Exact matches** - Same paragraphs in multiple files
+2. **Similar code blocks** - Nearly identical examples
+3. **Repeated explanations** - Same concept explained multiple times
+4. **Copy-paste patterns** - Setup instructions repeated
+
+### Finding Outdated Content
+
+Compare:
+1. **Function signatures** - Params, return types
+2. **Import paths** - Package structure changes
+3. **Version numbers** - In code vs docs
+4. **Default values** - Changed defaults
+5. **Error messages** - Updated error text
+
+### Finding Discrepancies
+
+Check:
+1. **Return types** - What docs say vs code returns
+2. **Required fields** - Optional vs required mismatches
+3. **Behavior descriptions** - Edge cases documented incorrectly
+4. **Prerequisites** - Wrong versions, missing dependencies
+
+## Output Actions
+
+After generating report, suggest:
+
+"Found X issues. Would you like me to:
+1. **Fix outdated docs** - Update signatures and versions
+2. **Consolidate duplicates** - Merge redundant content
+3. **Create missing docs** - Stub pages for undocumented features
+4. **Update terminology** - Standardize across all files"
+
+## Integration with Other Skills
+
+- After blame analysis → `/update-doc` to fix issues
+- For new undocumented features → `/create-doc`
+- When ready to save → `/commit-doc`