SuperClaude/.claude/commands/shared/research-first.yml

# Research-First Professional Standards

## Mandatory Research Triggers [C:10]

```yaml
External_Libraries:
  Detection_Patterns:
    - import .* from ['"][^./]['"]  # Non-relative imports
    - require\(['"][^./]['"]  # CommonJS non-relative
    - from (\w+) import  # Python imports
    - using \w+;  # C# namespaces
    - implementation ['"].*:.*['"]  # Gradle dependencies
    
  Required_Research:
    JS/TS:
      - React: hooks, components, state mgmt
      - Vue: composition API, directives, reactivity
      - Angular: services, DI, modules
      - Express: middleware, routing, error handling
      - Next.js: SSR, SSG, API routes, app dir
      - Node.js: built-in modules, streams, cluster
    
    Python:
      - Django: models, views, middleware, admin
      - Flask: blueprints, extensions, request handling
      - FastAPI: dependency injection, async, pydantic
      - NumPy/Pandas: array operations, dataframes
      - TensorFlow/PyTorch: models, training, deployment
    
    Other:
      - Database: SQL syntax, ORM patterns, migrations
      - Cloud: AWS/GCP/Azure service APIs
      - Testing: framework-specific assertions, mocks
      - Build tools: webpack, vite, rollup configs

Component_Creation:
  UI_Keywords:
    - button, form, modal, dialog, dropdown
    - table, list, grid, card, accordion
    - nav, menu, sidebar, header, footer
    - chart, graph, visualization, dashboard
    
  Required_Actions:
    - Check existing components in project
    - Search design system if available
    - Use Magic builder for new components
    - WebSearch for accessibility patterns
    - Verify responsive design requirements

API_Integration:
  Patterns:
    - REST: endpoints, methods, authentication
    - GraphQL: queries, mutations, schemas
    - WebSocket: events, connections, protocols
    - SDK/Client: initialization, methods, errors
    
  Required_Checks:
    - Official API documentation
    - Authentication methods
    - Rate limits and quotas
    - Error response formats
    - Versioning and deprecations
```

## Implementation Blockers

```yaml
Guessing_Indicators:
  Phrases_To_Block:
    - "might work"
    - "should probably"
    - "I think this"
    - "typically would"
    - "usually looks like"
    - "common pattern is"
    - "often implemented as"
    
  Required_Instead:
    - "According to [source]"
    - "Documentation states"
    - "Official example shows"
    - "Verified pattern from"
    - "Testing confirms"

Confidence_Requirements:
  Minimum_Score: 90%
  
  Evidence_Types:
    Official_Docs: 100%
    Tutorial_From_Maintainer: 95%
    Recent_Blog_Post: 85%
    Stack_Overflow_Accepted: 80%
    GitHub_Issue_Resolution: 85%
    No_Evidence: 0% (BLOCK)
    
  Score_Calculation:
    - Must have at least one 95%+ source
    - Multiple 80%+ sources can combine
    - Age penalty: -5% per year old
    - Verification: Test/example adds +10%
```

## Research Workflows

```yaml
Library_Research_Flow:
  1. Detect library reference in code/request
  2. Check if already in package.json/requirements
  3. C7 resolve-library-id → get-docs
  4. If C7 fails → WebSearch "library official docs"
  5. Extract key patterns:
     - Installation method
     - Basic usage examples
     - Common patterns
     - Error handling
     - Best practices
  6. Cache results for session
  7. Cite sources in implementation

Component_Research_Flow:
  1. Identify UI component need
  2. Search existing codebase first
  3. Check project's component library
  4. Magic builder search with keywords
  5. If no match → WebSearch "component accessibility"
  6. Implement with citations
  7. Note any deviations from patterns

API_Research_Flow:
  1. Identify API/service to integrate
  2. WebSearch "service official API docs"
  3. Find authentication documentation
  4. Locate endpoint references
  5. Check for SDK/client library
  6. Review error handling patterns
  7. Note rate limits and constraints
```

## Professional Standards

```yaml
Source_Attribution:
  Required_Format: "// Source: [URL or Doc Reference]"
  
  Placement:
    - Above implementation using pattern
    - In function documentation
    - In commit messages for new patterns
    
Citation_Examples:
  Good:
    - "// Source: React docs - https://react.dev/reference/react/useState"
    - "// Pattern from: Express.js error handling guide"
    - "// Based on: AWS S3 SDK documentation v3"
    
  Bad:
    - "// Common pattern"
    - "// Standard approach"
    - "// Typical implementation"

Uncertainty_Handling:
  When_Docs_Unavailable:
    - State explicitly: "Documentation not found for X"
    - Provide rationale: "Using pattern similar to Y because..."
    - Mark as provisional: "// TODO: Verify when docs available"
    - Suggest alternatives: "Consider using documented library Z"
    
  When_Multiple_Patterns:
    - Show options: "Documentation shows 3 approaches:"
    - Explain tradeoffs: "Option A is simpler but less flexible"
    - Recommend based on context: "For this use case, B is optimal"
    - Cite each source
```

## Enforcement Mechanisms

```yaml
Pre_Implementation_Checks:
  Parse_Code_For:
    - Import statements
    - Function calls to external libs
    - Component definitions
    - API endpoint references
    
  Block_If:
    - External library with no research
    - New component type without pattern check
    - API usage without documentation
    - Confidence score below 90%
    
  Warning_If:
    - Documentation is >2 years old
    - Using deprecated patterns
    - Multiple conflicting sources
    - Community solution vs official

Session_Research_Cache:
  Store:
    - Library: version, patterns, examples
    - Components: accessibility, variants
    - APIs: endpoints, auth, limits
    
  Reuse:
    - Same library → use cached patterns
    - Note: "Using previously researched pattern"
    - Invalidate on version change

Integration_Points:
  Commands:
    - build: Check all imports
    - improve: Verify optimization patterns  
    - troubleshoot: Search known issues first
    - design: Research architectural patterns
    
  Personas:
    - frontend: Extra UI/UX research
    - backend: API/database patterns
    - architect: System design patterns
    - security: Vulnerability databases
```

## Examples

```yaml
Good_Implementation:
  Request: "Add user authentication to Express app"
  
  Research_Steps:
    1. C7 resolve-library-id("express")
    2. C7 get-docs(topic: "authentication middleware")
    3. WebSearch "express session best practices 2024"
    4. Check project for existing auth patterns
    
  Implementation:
    ```javascript
    // Source: Express.js docs - https://expressjs.com/en/guide/using-middleware.html
    // Pattern: Session-based authentication with secure defaults
    
    const session = require('express-session');
    const MongoStore = require('connect-mongo');
    
    // Source: OWASP session management cheat sheet
    app.use(session({
      secret: process.env.SESSION_SECRET,
      resave: false,
      saveUninitialized: false,
      cookie: {
        secure: process.env.NODE_ENV === 'production',
        httpOnly: true,
        maxAge: 1000 * 60 * 60 * 24 // 24 hours
      },
      store: MongoStore.create({
        mongoUrl: process.env.MONGODB_URI
      })
    }));
    ```

Bad_Implementation_Blocked:
  Request: "Add user authentication to Express app"
  
  Without_Research:
    ```javascript
    // BLOCKED: No documentation reference
    // This might work for authentication
    app.use((req, res, next) => {
      if (req.session && req.session.user) {
        next();
      } else {
        res.redirect('/login');
      }
    });
    ```
    
  Error: "External library usage requires documentation. Please research Express.js authentication patterns first."
```

---
*Research-First: Ensuring professional, evidence-based implementations*