@brainfish-ai/devdoc 0.1.41 → 0.1.43

package/ai-agents/.claude/skills/check-docs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: check-docs
-description: Quick health check for documentation issues. Reads context memory for validation.
+description: Quick health check for documentation issues. Verifies content against actual source files.
 ---
 
 ## Instructions
@@ -29,6 +29,31 @@ Run a quick audit of documentation health.
 - Check brand name capitalization
 - Validate API patterns match `api.conventions`
 
+### Step 0b: Source Verification (CRITICAL)
+
+**For each doc page, search for corresponding source files:**
+
+```bash
+# For auth docs, find auth source
+git ls-files | grep -iE "auth"
+rg -l "export.*login" --type ts
+
+# For API docs, find route handlers
+git ls-files | grep -iE "(route|api|controller)"
+```
+
+**Flag docs without verifiable sources:**
+```
+⚠️ UNVERIFIED DOCS (no matching source files)
+- docs/legacy/old-api.mdx - No source found
+- docs/guides/advanced.mdx - No source found
+
+Options:
+1. 🔄 Remove these docs
+2. ❓ Ask for source locations
+3. 📝 Mark as needs-review
+```
+
 ### Step 1: Get Documentation Type
 
 **Read `docs.json` for `docType` field:**
@@ -56,11 +81,17 @@ This helps tailor the checks:
 5. **Outdated Examples** - Compare imports against package exports
 6. **Stale Versions** - Check version numbers against package.json
 
+#### Source Verification Checks (CRITICAL):
+7. **Source File Exists** - For each doc, search for matching source file
+8. **Signature Match** - Compare documented signatures vs source
+9. **Type Accuracy** - Verify documented types match source types
+10. **Example Validity** - Check examples work with current source
+
 #### Context-Based Checks (if context.json exists):
-7. **Terminology** - Flag incorrect terms from `avoidTerms`
-8. **Brand Names** - Check capitalization matches `brandNames`
-9. **Product Name** - Ensure consistent use of `product.name`
-10. **API Patterns** - Verify examples follow `api.conventions`
+11. **Terminology** - Flag incorrect terms from `avoidTerms`
+12. **Brand Names** - Check capitalization matches `brandNames`
+13. **Product Name** - Ensure consistent use of `product.name`
+14. **API Patterns** - Verify examples follow `api.conventions`
 
 ### Output Format
 
@@ -81,19 +112,30 @@ Summary: X issues found
 ### Missing Pages (count)
    docs.json references 'page' but file not found
 
+### Source Verification Failed (count)
+   docs/api/auth.mdx → No source file found
+     Searched: src/**/*auth*.ts, lib/**/*auth*.ts
+     Options:
+       1. 🔄 Remove doc
+       2. ❓ Ask for path
+       3. 📝 Mark as TODO
+
+### Signature Mismatch (count)
+   docs/api/users.mdx → createUser signature wrong
+     Documented: createUser(name, email)
+     Source: createUser(options: CreateUserInput)
+     File: src/lib/users.ts:45
+
 ## Warnings
 
 ### Terminology Issues (count)
    file.mdx:line → Uses "charge" instead of "payment"
-   file.mdx:line → Uses "transaction" instead of "payment"
-   (per terminology.avoidTerms in context)
 
 ### Brand Name Issues (count)
    file.mdx:line → "productname" should be "ProductName"
 
 ### Outdated Code (count)
    file.mdx:line → import { oldFunc } from 'pkg'
-   'oldFunc' no longer exported, use 'newFunc'
 
 ### Orphan Pages (count)
    path/to/file.mdx (not in navigation)
@@ -104,6 +146,7 @@ Summary: X issues found
 ✓ All internal links resolve
 ✓ No syntax errors in code blocks
 ✓ Product name used consistently
+✓ All docs have verified source files
 ```
 
 ## Checks By DocType
@@ -129,6 +172,36 @@ Summary: X issues found
 
 ## Detailed Checks
 
+### Source Verification (CRITICAL)
+
+**For each documentation page:**
+```bash
+# 1. Extract topic from doc path
+# docs/api/auth.mdx → topic: "auth"
+
+# 2. Search for source files
+git ls-files | grep -iE "auth"
+rg -l "export.*(login|authenticate)" --type ts
+
+# 3. Read source and doc, compare:
+#    - Function signatures
+#    - Parameter types
+#    - Return types
+#    - Error codes
+```
+
+**If source not found:**
+```
+⚠️ UNVERIFIED: docs/api/auth.mdx
+No source file found for authentication documentation.
+
+Options:
+1. 🔄 Auto-correct IA - Remove this doc
+2. ✏️ Rename doc - Match what exists
+3. 📝 Mark as TODO - Keep with warning
+4. ❓ Ask for path - Where is it implemented?
+```
+
 ### Link Validation
 - Internal links (`href="/path"`)
 - Anchor links (`href="#section"`)
@@ -139,6 +212,7 @@ Summary: X issues found
 - Valid syntax (basic check)
 - Import statements resolve
 - Uses correct primary language from context
+- **Examples match source code**
 
 ### Navigation Validation
 - All pages in docs.json exist
@@ -149,6 +223,7 @@ Summary: X issues found
 - Frontmatter present (title, description)
 - No H1 headings (title from frontmatter)
 - Images have alt text
+- **Sources cited in frontmatter**
 
 ### Terminology Validation (from context)
 - No terms from `avoidTerms` used

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

@@ -1,27 +1,20 @@
 ---
 name: create-doc
-description: Create new documentation pages interactively. Analyzes codebase and guides you through the process.
+description: Create new documentation pages interactively. Searches codebase to ensure accuracy.
 ---
 
 ## Instructions
 
 When user wants to create documentation:
 
-### Step 0: Read Context & Code Graph
+### Step 0: Read Context
 
-**First, read `.devdoc/context.json` if it exists:**
+**Read `.devdoc/context.json` if it exists:**
 - Use `product.name` for product references
 - Apply `terminology.glossary` for correct terms
 - Use `documentation.codeExamples.primaryLanguage` for code
 - Read templates from `documentation.templates`
 
-**Then, read `.devdoc/code-graph.json` if it exists:**
-- Use `modules` array to understand codebase structure
-- Reference exact function signatures from `exports`
-- Use `types` array for type definitions
-- Find examples in `examples` array
-- Reference `errors` for error handling docs
-
 ### Step 1: Understand What to Create
 
 Ask the user:
@@ -66,36 +59,142 @@ Based on their choice:
 - Ask clarifying questions
 - Understand the scope and purpose
 
-### Step 3: Analyze Codebase (if applicable)
+### Step 3: Search Codebase (CRITICAL - No Hallucination)
+
+**ALWAYS search and read actual files before generating content:**
+
+#### 3a. Search for Relevant Files
+
+```bash
+# Find files related to the topic
+git ls-files | grep -iE "(auth|login|session)"  # for auth docs
+
+# Search file contents for specific terms
+rg -l "export.*function.*createUser" --type ts
+rg -l "class.*Authentication" --type ts
 
-When documenting code:
+# Find types and interfaces
+rg -l "interface.*User|type.*User" --type ts
 
-**If `.devdoc/code-graph.json` exists:**
+# Find examples
+git ls-files | grep -iE "(example|test|spec)"
 ```
-Read from code-graph.json:
-- modules[].exports → Function signatures, params, returns
-- types[] → Type definitions
-- examples[] → Code examples
-- api.endpoints[] → API routes
-- errors[] → Error types
+
+#### 3b. Read the Files Found
+
+For each relevant file:
+1. **Read the file** - Get actual implementation
+2. **Extract key info:**
+   - Function signatures and parameters
+   - Type definitions
+   - Error codes and messages
+   - Code examples from tests
+
+#### 3c. Assess Information Sufficiency
+
 ```
+┌─────────────────────────────────────────────┐
+│ ASSESSMENT                                  │
+├─────────────────────────────────────────────┤
+│ ✅ Sufficient - Found source files          │
+│    → Proceed with real data                 │
+│                                             │
+│ ⚠️ Partial - Some gaps                      │
+│    → Generate with TODOs for gaps           │
+│                                             │
+│ ❌ Insufficient - No relevant files         │
+│    → FLAG and offer options                 │
+└─────────────────────────────────────────────┘
+```
+
+#### 3d. Handle Insufficient Information
+
+**If files not found, present options:**
 
-**If code-graph.json doesn't exist:**
 ```
-Scan the codebase for:
-- Function signatures and JSDoc/docstrings
-- Type definitions and interfaces
-- Usage examples in tests
-- README sections about this feature
+⚠️ UNCLEAR TOPIC: [topic]
+
+Searched for:
+  - src/**/*auth*.ts → Not found
+  - lib/**/*auth*.ts → Not found
+
+Options:
+  1. 🔄 **Skip this doc** - Remove from plan
+  2. ✏️  **Different topic** - Document something else
+  3. 📝 **Mark as TODO** - Create placeholder
+  4. ❓ **Ask for path** - "Where is [topic] implemented?"
+
+Choose an option (1-4):
 ```
 
-Show user what you found:
-"I found in code-graph.json:
-- Module: `auth` with 5 exports (login, logout, verifyToken...)
-- Types: User, AuthToken, Session
-- Examples: `examples/auth-flow.ts`
+#### 3e. Detect Feature Flags & Duplicates
 
-Should I proceed with generating documentation for these?"
+**Search for feature flags:**
+```bash
+# Find feature flag patterns
+rg -l "featureFlag|feature_flag|isEnabled|FF_" --type ts
+rg "if.*\(.*feature|process\.env\.FEATURE" --type ts
+rg "LaunchDarkly|Unleash|Split|flagsmith" --type ts
+```
+
+**Search for duplicate/similar features:**
+```bash
+# Find similar function names
+rg "export.*(login|authenticate|signIn)" --type ts -l
+rg "export.*(createUser|addUser|registerUser)" --type ts -l
+```
+
+**Flag findings for user guidance:**
+```
+⚠️ FEATURE FLAGS DETECTED:
+
+📍 src/lib/auth/index.ts:45
+   if (featureFlags.newAuthFlow) { ... }
+   
+   This feature has TWO implementations:
+   - OLD: lines 50-80 (current default)
+   - NEW: lines 82-120 (behind feature flag)
+   
+   Question: Document which version?
+   1. Current (old) implementation
+   2. New implementation (feature flagged)
+   3. Both with toggle notice
+
+⚠️ DUPLICATE FEATURES DETECTED:
+
+Found similar functions:
+- src/lib/auth/login.ts → login()
+- src/lib/auth/v2/authenticate.ts → authenticate()
+- src/lib/legacy/signIn.ts → signIn()
+
+Question: Which should be documented?
+1. Document primary (login.ts)
+2. Document all with comparison
+3. Mark legacy as deprecated
+```
+
+#### 3f. Show What Was Found
+
+```
+📂 FILES FOUND for [topic]:
+
+✓ src/lib/auth/index.ts (main auth module)
+  - login(email, password): Promise<Token>
+  - logout(): void
+  - verifyToken(token): boolean
+
+✓ src/lib/auth/types.ts
+  - interface User { id, email, role }
+  - type AuthToken { token, expiresAt }
+
+✓ tests/auth.test.ts
+  - Example usage patterns
+
+⚠️ FEATURE FLAGS: newAuthFlow (src/lib/auth/index.ts:45)
+⚠️ DUPLICATES: authenticate() in v2/, signIn() in legacy/
+
+Proceed with generating documentation from these files?
+```
 
 ### Step 4: Choose Template
 
@@ -109,51 +208,117 @@ Read the appropriate template from `.devdoc/templates/`:
 | Quick start | `quickstart.md` |
 | FAQ/Issues | `troubleshooting.md` |
 
-### Step 5: Generate Content
+### Step 5: Draft Content (From Real Files Only)
+
+**CRITICAL: Only use data from files you actually read.**
 
-Create the documentation:
+Draft the documentation (DO NOT WRITE YET):
 
 1. **Read the template** for structure guidance
 2. **Apply context** (terminology, voice, language)
-3. **Use code-graph.json** for accuracy:
-   - Get exact function signatures from `exports`
-   - Get type definitions from `types`
-   - Reference examples from `examples` array
-   - Document errors from `errors` array
+3. **Use ONLY data from searched files:**
+   - Get exact function signatures from source files
+   - Get type definitions from actual type files
+   - Reference examples from test files or examples folder
+   - Document errors from error handling code
 4. **Include mermaid diagrams** for flows/architecture
-5. **Add real code examples** from codebase/code-graph
+5. **Add real code examples** copied from codebase
 6. **Use proper MDX components** (Steps, Cards, Tabs, etc.)
+7. **Cite sources** - Note which files info came from
+8. **Mark feature flags** - Note conditional features
+9. **Note duplicates** - Reference related/similar features
+
+**NEVER generate content without reading source files first.**
+
+### Step 6: Review Content with User (MANDATORY)
+
+**ALWAYS show the complete draft for user review before writing:**
 
-**Example using code-graph:**
 ```
-// From code-graph.json:
-{
-  "name": "login",
-  "type": "function",
-  "signature": "login(email: string, password: string): Promise<AuthToken>",
-  "params": [...]
-}
+═══════════════════════════════════════════════════════════
+                    CONTENT REVIEW
+═══════════════════════════════════════════════════════════
+
+📄 FILE: docs/guides/authentication.mdx
+
+───────────────────────────────────────────────────────────
+                    DRAFT CONTENT
+───────────────────────────────────────────────────────────
+
+---
+title: Authentication
+description: Learn how to authenticate users in your app
+sources: ["src/lib/auth/index.ts", "src/lib/auth/types.ts"]
+---
+
+## Overview
+
+Authentication allows users to securely access your application...
 
-// Generate accurate documentation:
 ## login(email, password)
+
 Authenticate user and return JWT token.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| email | string | User email address |
+| password | string | User password |
+
+**Returns:** `Promise<AuthToken>`
+
+### Example
+
+```typescript
+import { login } from '@package/auth';
+
+const token = await login('user@example.com', 'password');
+```
+
+## Next Steps
+
+...
+
+───────────────────────────────────────────────────────────
+                    NOTICES
+───────────────────────────────────────────────────────────
+
+⚠️ FEATURE FLAG: newAuthFlow
+   This feature has a new implementation behind a flag.
+   Currently documenting: OLD implementation
+   
+🔄 DUPLICATE: authenticate() exists in src/lib/auth/v2/
+   Consider: Document both or mark one as preferred?
+
+───────────────────────────────────────────────────────────
+                    OPTIONS
+───────────────────────────────────────────────────────────
+
+1. ✅ **Approve** - Create file with this content
+2. ✏️  **Edit** - Tell me what to change
+3. 🔄 **Switch version** - Document feature-flagged version instead
+4. ➕ **Add duplicate** - Include related feature documentation
+5. ❌ **Cancel** - Don't create this file
+
+Choose an option:
 ```
 
-### Step 6: Propose File Location
+### Step 7: Propose File Location
 
-Suggest where to save:
+After content approval, suggest where to save:
 
 "I'll create this page at: `docs/guides/{topic}.mdx`
 
 Does this location work, or would you prefer somewhere else?"
 
-### Step 7: Create and Update Navigation
+### Step 8: Create and Update Navigation
+
+**Only after user approves content AND location:**
 
 1. Write the MDX file
 2. Ask: "Should I add this to the navigation in docs.json?"
 3. If yes, update docs.json with the new page
 
-### Step 8: Summary
+### Step 9: Summary
 
 "Created:
 - `docs/guides/{topic}.mdx` - {description}
@@ -225,11 +390,58 @@ Generates similar documentation following the template structure.
 
 ---
 
+## Key Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Search before generate** | ALWAYS search/read files before writing |
+| **No hallucination** | Only use data from actual source files |
+| **Review before write** | ALWAYS show draft to user for approval |
+| **Flag feature flags** | Detect and highlight conditional features |
+| **Flag duplicates** | Identify similar/related features |
+| **Use mermaid diagrams** | Visualize architecture, flows, sequences |
+| **Cite sources** | Note which files information came from |
+
 ## Quality Guidelines
 
-- Extract real code examples, don't fabricate
-- Include error handling in examples
+- **SEARCH FIRST** - Never generate without reading source files
+- **REVIEW WITH USER** - Always show draft before creating file
+- **DETECT FEATURE FLAGS** - Search for conditional features
+- **DETECT DUPLICATES** - Find similar functions/features
+- Extract real code examples from actual files
+- Flag insufficient info and offer auto-correct options
+- Include error handling from source code
 - Add TODO markers for sections needing human review
-- Use mermaid diagrams for complex flows
 - Link to related documentation
 - Apply terminology from context.json
+- Cite source files in frontmatter
+
+## Mermaid Diagram Requirements
+
+**ALWAYS include mermaid diagrams for:**
+
+| Content Type | Diagram | Example |
+|--------------|---------|---------|
+| Architecture | `flowchart TB` | System components |
+| Data flow | `flowchart LR` | Request processing |
+| API calls | `sequenceDiagram` | Auth flow |
+| State machine | `stateDiagram-v2` | Lifecycle |
+| Data models | `erDiagram` | Database schema |
+
+**Example for architecture docs:**
+```mermaid
+flowchart TB
+    Client --> API
+    API --> Auth
+    API --> Service
+    Service --> DB[(Database)]
+```
+
+**Example for API docs:**
+```mermaid
+sequenceDiagram
+    Client->>API: POST /login
+    API->>Auth: Validate
+    Auth-->>API: Token
+    API-->>Client: 200 OK
+```