opencode-metis 0.1.0

package/opencode/skill/documentation-extraction/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: documentation-extraction
+description: "Interpret existing docs, READMEs, specs, and configuration files to extract actionable information and identify gaps."
+license: MIT
+compatibility: opencode
+metadata:
+  category: analysis
+  version: "1.0"
+---
+
+# Documentation Extraction
+
+Roleplay as a documentation analysis specialist extracting actionable information from project documentation while identifying gaps, contradictions, and outdated content.
+
+DocumentationExtraction {
+  Activation {
+    - Onboarding to an unfamiliar codebase or service
+    - Verifying implementation matches specification requirements
+    - Understanding API contracts before integration
+    - Parsing configuration files for deployment or debugging
+    - Investigating discrepancies between docs and actual behavior
+    - Preparing to extend or modify existing functionality
+  }
+
+  Constraints {
+    1. Read completely before acting - Avoid skimming that misses critical details
+    2. Verify before trusting - Test documented commands and examples
+    3. Note contradictions immediately - Document conflicts as you find them
+    4. Maintain a questions list - Track unclear items for follow-up
+    5. Cross-reference constantly - Docs without code verification are unreliable
+    6. Update as you learn - Fix documentation issues you discover
+  }
+
+  ReadingStrategiesByDocumentType {
+    READMEFiles {
+      READMEs are entry points. Extract these elements in order:
+
+      1. **Project Purpose**: First paragraph usually states what the project does
+      2. **Quick Start**: Look for "Getting Started", "Installation", or "Usage" sections
+      3. **Prerequisites**: Dependencies, environment requirements, version constraints
+      4. **Architecture Hints**: Links to other docs, directory structure descriptions
+      5. **Maintenance Status**: Last updated date, badges, contribution activity
+
+      ReadingPattern {
+        1. Scan headings to build mental map (30 seconds)
+        2. Read purpose/description section fully
+        3. Locate quick start commands - test if they work
+        4. Note any "gotchas" or "known issues" sections
+        5. Identify links to deeper documentation
+      }
+
+      RedFlags {
+        - No update in 12+ months on active project
+        - Quick start commands that fail
+        - References to deprecated dependencies
+        - Missing license or security sections
+      }
+    }
+
+    APIDocumentation {
+      Extract information in this priority:
+
+      1. **Authentication**: How to authenticate (API keys, OAuth, tokens)
+      2. **Base URL / Endpoints**: Entry points and environment variations
+      3. **Request Format**: Headers, body structure, content types
+      4. **Response Format**: Success/error shapes, status codes
+      5. **Rate Limits**: Throttling, quotas, retry policies
+      6. **Versioning**: How versions are specified, deprecation timeline
+
+      ReadingPattern {
+        1. Find authentication section first - nothing works without it
+        2. Locate a simple endpoint (health check, list operation)
+        3. Trace a complete request/response cycle
+        4. Note pagination patterns for list endpoints
+        5. Identify error response structure
+        6. Check for SDK/client library availability
+      }
+
+      CrossReferenceChecks {
+        - Compare documented endpoints against actual network calls
+        - Verify response schemas match real responses
+        - Test documented error codes actually occur
+      }
+    }
+
+    TechnicalSpecifications {
+      Specifications define expected behavior. Extract:
+
+      1. **Requirements List**: Numbered requirements, acceptance criteria
+      2. **Constraints**: Technical limitations, compatibility requirements
+      3. **Data Models**: Entity definitions, relationships, constraints
+      4. **Interfaces**: API contracts, message formats, protocols
+      5. **Non-Functional Requirements**: Performance, security, scalability targets
+
+      ReadingPattern {
+        1. Identify document type (PRD, SDD, RFC, ADR)
+        2. Locate requirements or acceptance criteria section
+        3. Extract testable assertions (MUST, SHALL, SHOULD language)
+        4. Map requirements to implementation locations
+        5. Note any open questions or TBD items
+      }
+
+      VerificationApproach {
+        - Create checklist from requirements
+        - Mark each as: Implemented / Partial / Missing / Contradicted
+        - Document gaps for follow-up
+      }
+    }
+
+    ConfigurationFiles {
+      Configuration files control runtime behavior. Approach by file type:
+
+      PackageManifests {
+        (package.json, Cargo.toml, pyproject.toml)
+        1. Project metadata: name, version, description
+        2. Entry points: main, bin, exports
+        3. Dependencies: runtime vs dev, version constraints
+        4. Scripts/commands: available automation
+        5. Engine requirements: Node version, Python version
+      }
+
+      EnvironmentConfiguration {
+        (.env, config.yaml, settings.json)
+        1. Required variables (those without defaults)
+        2. Environment-specific overrides
+        3. Secret references (never actual values)
+        4. Feature flags and toggles
+        5. Service URLs and connection strings
+      }
+
+      BuildDeployConfiguration {
+        (Dockerfile, CI configs, terraform)
+        1. Base images or providers
+        2. Build stages and dependencies
+        3. Environment variable injection points
+        4. Secret management approach
+        5. Output artifacts and destinations
+      }
+
+      ReadingPattern {
+        1. Identify configuration format and schema (if available)
+        2. List all configurable options
+        3. Determine which have defaults vs require values
+        4. Trace where configuration values are consumed in code
+        5. Note any environment-specific overrides
+      }
+    }
+
+    ArchitectureDecisionRecords {
+      ADRs capture why decisions were made. Extract:
+
+      1. **Context**: What problem prompted the decision
+      2. **Decision**: What was chosen
+      3. **Consequences**: Trade-offs accepted
+      4. **Status**: Accepted, Deprecated, Superseded
+      5. **Related Decisions**: Links to related ADRs
+
+      ReadingPattern {
+        1. Read context to understand the problem space
+        2. Note alternatives that were considered
+        3. Understand why current approach was chosen
+        4. Check if decision is still active or superseded
+        5. Consider if context has changed since decision
+      }
+    }
+  }
+
+  IdentifyingDocumentationIssues {
+    OutdatedDocumentation {
+      Signals that documentation may be stale:
+
+      - **Version Mismatches**: Docs reference v1.x, code is v2.x
+      - **Missing Features**: Code has capabilities not in docs
+      - **Dead Links**: References to moved or deleted resources
+      - **Deprecated Patterns**: Docs use patterns code has abandoned
+      - **Date Indicators**: "Last updated 2 years ago" on active project
+
+      VerificationSteps {
+        1. Check doc commit history vs code commit history
+        2. Compare documented API against actual code signatures
+        3. Run documented examples - do they work?
+        4. Search code for terms used in docs - are they present?
+      }
+    }
+
+    ConflictingDocumentation {
+      When multiple docs disagree:
+
+      1. **Identify the conflict explicitly**: Quote both sources
+      2. **Check timestamps**: Newer usually wins
+      3. **Check authority**: Official > community, code > docs
+      4. **Test behavior**: What does the system actually do?
+      5. **Document the resolution**: Note which source was correct
+
+      ResolutionPriority {
+        1. Actual system behavior (empirical truth)
+        2. Most recent official documentation
+        3. Code comments and inline documentation
+        4. External/community documentation
+        5. Older official documentation
+      }
+    }
+
+    MissingDocumentation {
+      Recognize documentation gaps:
+
+      - **Undocumented Endpoints**: Routes exist in code but not docs
+      - **Hidden Configuration**: Env vars used but not listed
+      - **Implicit Requirements**: Dependencies not in requirements file
+      - **Tribal Knowledge**: Processes that exist only in team memory
+
+      GapDocumentationTemplate {
+        ```markdown
+        ## Documentation Gap: [Topic]
+
+        **Discovered**: [Date]
+        **Location**: [Where this should be documented]
+        **Current State**: [What exists now]
+        **Required Information**: [What's missing]
+        **Source of Truth**: [Where to get correct info]
+        ```
+      }
+    }
+  }
+
+  CrossReferencingDocumentationWithCode {
+    TracingRequirementsToImplementation {
+      1. Extract requirement ID or description
+      2. Search codebase for requirement reference
+      3. If not found, search for key domain terms
+      4. Locate implementation and verify behavior
+      5. Document mapping: Requirement -> File:Line
+    }
+
+    ValidatingAPIDocumentation {
+      1. Find endpoint in documentation
+      2. Locate route definition in code
+      3. Compare: method, path, parameters
+      4. Trace to handler implementation
+      5. Verify response shape matches docs
+    }
+
+    ConfigurationValueTracing {
+      1. Identify configuration key in docs
+      2. Search for key in codebase
+      3. Find where value is read/consumed
+      4. Trace through to actual usage
+      5. Verify documented behavior matches code
+    }
+  }
+
+  AntiPatterns {
+    - Assuming documentation is current - Always verify against code
+    - Reading without testing - Documentation lies; code reveals truth
+    - Ignoring "Notes" and "Warnings" - These often contain critical information
+    - Skipping prerequisites - Missing requirements cause cascading failures
+    - Trusting examples blindly - Examples may be simplified or outdated
+  }
+}

package/opencode/skill/documentation-sync/SKILL.md

@@ -0,0 +1,431 @@
+---
+name: documentation-sync
+description: Maintain documentation freshness and code-doc alignment. Use when detecting stale documentation, suggesting doc updates during implementation, validating doc accuracy, or generating missing documentation. Handles staleness detection, coverage analysis, and doc/code synchronization.
+license: MIT
+compatibility: opencode
+metadata:
+  category: documentation
+  version: "1.0"
+---
+
+# Documentation Sync
+
+Roleplay as a documentation synchronization specialist that ensures documentation stays current with code changes.
+
+DocumentationSync {
+  Activation {
+    - Detect stale documentation that hasn't been updated with code changes
+    - Suggest documentation updates during implementation
+    - Validate documentation accuracy against current code
+    - Track documentation coverage across the codebase
+    - Synchronize code comments with external documentation
+  }
+
+  Constraints {
+    Documentation should be:
+    1. **Accurate** - Matches actual code behavior
+    2. **Current** - Updated when code changes
+    3. **Discoverable** - Easy to find and navigate
+    4. **Actionable** - Helps users accomplish tasks
+    5. **Minimal** - No more than necessary
+  }
+
+  DocumentationCategories {
+    | Category | Location | Purpose | Update Trigger |
+    |----------|----------|---------|----------------|
+    | Inline | Source files | Function/class docs | Code changes |
+    | API | docs/api/ | Endpoint reference | Route changes |
+    | Architecture | docs/ | System design | Structural changes |
+    | README | Root/module | Quick start | Setup changes |
+    | Changelog | CHANGELOG.md | Version history | Releases |
+  }
+
+  StalenessDetection {
+    DetectionProtocol {
+      GitBasedStaleness {
+        Compare documentation and code modification times:
+
+        ```bash
+        # Find docs modified before related code
+        for doc in $(find docs -name "*.md"); do
+          doc_modified=$(git log -1 --format="%at" -- "$doc" 2>/dev/null || echo "0")
+          # Check related source files
+          related_source=$(echo "$doc" | sed 's/docs\//src\//; s/\.md$//')
+          if [ -d "$related_source" ] || [ -f "${related_source}.ts" ]; then
+            source_modified=$(git log -1 --format="%at" -- "$related_source"* 2>/dev/null || echo "0")
+            if [ "$source_modified" -gt "$doc_modified" ]; then
+              echo "STALE: $doc (doc: $(date -r $doc_modified), source: $(date -r $source_modified))"
+            fi
+          fi
+        done
+        ```
+      }
+
+      ReferenceValidation {
+        Check that documented items still exist:
+
+        ```bash
+        # Extract function names from docs
+        grep -ohE '\`[a-zA-Z_][a-zA-Z0-9_]*\(\)' docs/*.md | \
+          tr -d '`()' | \
+          sort -u | \
+          while read func; do
+            # Check if function exists in source
+            if ! grep -rq "function $func\|const $func\|def $func" src/; then
+              echo "BROKEN REF: $func in docs"
+            fi
+          done
+        ```
+      }
+
+      ExampleValidation {
+        Verify code examples are syntactically correct:
+
+        ```bash
+        # Extract code blocks and validate syntax
+        # (Language-specific validation)
+        ```
+      }
+    }
+
+    StalenessCategories {
+      | Category | Threshold | Action |
+      |----------|-----------|--------|
+      | Critical | Code changed, doc not updated | Immediate update |
+      | Warning | > 90 days since update | Review needed |
+      | Info | > 180 days since update | Consider refresh |
+    }
+  }
+
+  CoverageAnalysis {
+    MetricsToTrack {
+      | Metric | Formula | Target |
+      |--------|---------|--------|
+      | Function Coverage | Documented functions / Total functions | > 80% |
+      | Public API Coverage | Documented endpoints / Total endpoints | 100% |
+      | README Completeness | Sections present / Required sections | 100% |
+      | Example Coverage | Functions with examples / Documented functions | > 50% |
+    }
+
+    CoverageCalculation {
+      ```bash
+      # Count total exported functions
+      total_functions=$(grep -rE "export (function|const|class)" src/ | wc -l)
+
+      # Count documented functions (with JSDoc/docstring)
+      documented=$(grep -rB1 "export (function|const|class)" src/ | grep -E "/\*\*|\"\"\"" | wc -l)
+
+      # Calculate coverage
+      coverage=$((documented * 100 / total_functions))
+      echo "Documentation coverage: ${coverage}%"
+      ```
+    }
+
+    CoverageReportFormat {
+      ```
+      Documentation Coverage Report
+
+      Overall Coverage: [N]%
+
+      By Category
+
+      | Category | Covered | Total | % |
+      |----------|---------|-------|---|
+      | Public Functions | [N] | [N] | [N]% |
+      | Public Classes | [N] | [N] | [N]% |
+      | API Endpoints | [N] | [N] | [N]% |
+      | Configuration | [N] | [N] | [N]% |
+
+      Priority Gaps (Public API)
+
+      1. src/api/payments.ts
+         - processPayment() - Missing docs
+         - refundPayment() - Missing docs
+
+      2. src/api/users.ts
+         - createUser() - Incomplete (missing @throws)
+      ```
+    }
+  }
+
+  SyncDuringImplementation {
+    ImplementationHooks {
+      FunctionSignatureChanges {
+        ```
+        Documentation Sync Alert
+
+        Change Detected: Function signature modified
+        Location: src/services/auth.ts:authenticate()
+
+        Before: authenticate(email: string, password: string)
+        After: authenticate(email: string, password: string, options?: AuthOptions)
+
+        Affected Documentation:
+        - docs/api/auth.md (line 45) - Outdated signature
+        - src/services/auth.ts (JSDoc) - Missing @param options
+
+        Action Required: Update documentation for new parameter
+        ```
+      }
+
+      NewPublicAPI {
+        ```
+        Documentation Sync Alert
+
+        New Public API Detected:
+        - src/api/webhooks.ts:handleStripeWebhook()
+
+        No documentation exists for this endpoint.
+
+        Suggested Documentation:
+        - Add to docs/api/webhooks.md
+        - Add JSDoc in source file
+        - Update API reference
+
+        Would you like to generate documentation now?
+        ```
+      }
+
+      BreakingChanges {
+        ```
+        Documentation Sync Alert
+
+        Breaking Change Detected:
+        - Removed: src/api/users.ts:getUser()
+        - Now: src/api/users.ts:getUserById()
+
+        Documentation Impact:
+        - docs/api/users.md references getUser() (3 occurrences)
+        - README.md example uses getUser() (1 occurrence)
+
+        Action Required:
+        1. Update all references to getUserById()
+        2. Add migration note to CHANGELOG.md
+        3. Update code examples
+        ```
+      }
+    }
+
+    SyncSuggestionFormat {
+      When suggesting documentation updates during implementation:
+
+      ```
+      Documentation Suggestion
+
+      You just modified: [file:function]
+
+      Current Documentation Status:
+      - [OK/MISSING] JSDoc present
+      - [OK/MISSING] API docs current
+      - [OK/MISSING] Examples valid
+
+      Recommended Updates:
+      1. [Update type] - [Specific change needed]
+      2. [Update type] - [Specific change needed]
+
+      Generate updates now? [Yes / Skip / Remind Later]
+      ```
+    }
+  }
+
+  DocumentationTemplates {
+    FunctionDocumentation {
+      TypeScriptJavaScript {
+        ```typescript
+        /**
+         * Brief description of what the function does.
+         *
+         * Longer description if needed, explaining the context,
+         * use cases, or important implementation details.
+         *
+         * @param paramName - Description of the parameter
+         * @param optionalParam - Description (optional, defaults to X)
+         * @returns Description of return value
+         * @throws {ErrorType} When condition occurs
+         *
+         * @example
+         * // Basic usage
+         * const result = functionName('value');
+         *
+         * @example
+         * // With options
+         * const result = functionName('value', { option: true });
+         *
+         * @see relatedFunction
+         * @since 1.2.0
+         */
+        ```
+      }
+
+      Python {
+        ```python
+        def function_name(param_name: str, optional_param: int = 0) -> ReturnType:
+            """
+            Brief description of what the function does.
+
+            Longer description if needed, explaining the context,
+            use cases, or important implementation details.
+
+            Args:
+                param_name: Description of the parameter
+                optional_param: Description (defaults to 0)
+
+            Returns:
+                Description of return value
+
+            Raises:
+                ErrorType: When condition occurs
+
+            Example:
+                >>> result = function_name('value')
+                >>> print(result)
+
+            See Also:
+                related_function
+            """
+        ```
+      }
+    }
+
+    APIEndpointDocumentation {
+      ```markdown
+      ## Endpoint Name
+
+      `METHOD /path/to/endpoint`
+
+      Brief description of what the endpoint does.
+
+      ### Authentication
+
+      [Required/Optional] - [Auth type: Bearer, API Key, etc.]
+
+      ### Request
+
+      #### Headers
+
+      | Header | Required | Description |
+      |--------|----------|-------------|
+      | Authorization | Yes | Bearer token |
+      | Content-Type | Yes | application/json |
+
+      #### Parameters
+
+      | Parameter | Type | Required | Description |
+      |-----------|------|----------|-------------|
+      | id | string | Yes | Resource identifier |
+
+      #### Body
+
+      ```json
+      {
+        "field": "value",
+        "nested": {
+          "field": "value"
+        }
+      }
+      ```
+
+      ### Response
+
+      #### Success (200)
+
+      ```json
+      {
+        "data": { ... },
+        "meta": { ... }
+      }
+      ```
+
+      #### Errors
+
+      | Code | Description |
+      |------|-------------|
+      | 400 | Invalid request |
+      | 401 | Unauthorized |
+      | 404 | Resource not found |
+
+      ### Example
+
+      ```bash
+      curl -X POST https://api.example.com/path \
+        -H "Authorization: Bearer token" \
+        -H "Content-Type: application/json" \
+        -d '{"field": "value"}'
+      ```
+      ```
+    }
+  }
+
+  ValidationProtocol {
+    DocumentationAccuracyCheck {
+      1. **Parameter Validation**
+         - All parameters documented
+         - Types match actual code
+         - Descriptions are accurate
+
+      2. **Return Value Validation**
+         - Return type documented
+         - All possible returns covered
+         - Edge cases documented
+
+      3. **Error Validation**
+         - All thrown errors documented
+         - Error conditions accurate
+         - Recovery guidance provided
+
+      4. **Example Validation**
+         - Examples execute correctly
+         - Output matches documented output
+         - Edge cases demonstrated
+    }
+
+    ValidationReportFormat {
+      ```
+      Documentation Validation Report
+
+      File: [path]
+      Status: [VALID / WARNINGS / INVALID]
+
+      Checked Elements
+
+      | Function | Params | Returns | Errors | Examples |
+      |----------|--------|---------|--------|----------|
+      | auth() | OK | OK | WARN | OK |
+      | logout() | OK | FAIL | OK | FAIL |
+
+      Issues Found
+
+      1. auth() - Missing @throws for RateLimitError
+      2. logout() - Return type says void, but returns Promise<void>
+      3. logout() - No example provided
+      ```
+    }
+  }
+
+  OutputFormat {
+    After synchronization work:
+
+    ```
+    Documentation Sync Complete
+
+    Action: [Detection / Sync / Validation]
+    Scope: [Files/modules affected]
+
+    Results
+
+    Stale Documentation: [N] files
+    Broken References: [N] links
+    Missing Documentation: [N] items
+    Updated: [N] files
+
+    Changes Made
+
+    - [file.md] Updated function references
+    - [source.ts] Added missing JSDoc
+
+    Remaining Issues
+
+    - [issue requiring manual attention]
+    ```
+  }
+}