📝 docs: improve askAI plugin documentation

[azigler]

trafficstars

Updates documentation for the askAI plugin to provide clearer information about data privacy, API usage, and getting started with recommended use cases. Includes better formatting, more precise descriptions of the plugin's functionality, and improved examples of how to use the askAI integration with OpenAI's latest model.

The documentation and FAQ now better explains the data privacy of using AI features with third-party providers. The FAQ section has been streamlined for better readability and understanding of gitStream's capabilities in regards to AI.___

PR Description by askLB('Describe PR')

• Updated documentation to clarify gitStream's access to code and AI plugin usage.
• Revised AI plugin integration to require OpenAI's gpt-4o-2024-08-06 model and an API token.
• Refined examples and parameters in askAI plugin reference to match new implementation.

The purpose of these changes is to enhance clarity and functionality of gitStream's AI integration documentation and plugin usage, ensuring users understand configuration requirements and potential impacts. Please rate this askLB description:

• [ ] Excellent
• [x] Good Enough
• [ ] Needs Improvement

✨ PR Description

Purpose: Standardize and enhance the AI integration features across gitStream documentation and configurations, improving clarity and consistency in AI-powered PR workflows.

Main changes:

• Unified naming and formatting of askAI plugin features across all documentation files
• Improved AI prompt configurations with clearer role definitions and structured outputs
• Enhanced plugin documentation with better security notes and standardized example formats

Generated by LinearB AI and added by gitStream. _{AI-generated content may contain inaccuracies. Please verify before using. We’d love your feedback! 🚀}

[jit-ci[bot]]

Hi, I’m Jit, a friendly security platform designed to help developers build secure applications from day zero with an MVS (Minimal viable security) mindset.

In case there are security findings, they will be communicated to you as a comment inside the PR.

Hope you’ll enjoy using Jit.

Questions? Comments? Want to learn more? Get in touch with us.

[PavelLinearB]

/gs run `{{ source | LinearB_AI(prompt="Perform a detailed code review of the provided code diff. For each modified file:

1. Identify issues that require changes (e.g., bugs, performance, readability, or maintainability improvements). Do not include descriptions of changes already implemented in the diff unless explaining their impact.
2. Attribute each issue to the specific file path and line number. Include unchanged code if relevant to the issue.
3. For each issue:
   • Provide a collapsible section titled with the issue type, file path, and line number(s).
   • Include actionable suggestions and refactored code snippets formatted as GitHub markdown.
   • Clearly explain the issue and how the suggested improvement addresses it.

Focus strictly on actionable, specific feedback. Avoid generic comments, restating existing changes, or unrelated observations.") }}`

/gs_run_result

Documentation Consistency Issue - askAI plugin references (multiple files)

Several documentation files have inconsistent quotation marks around label values:

# Before
The PR has a label "askai tests"
The PR has a label "askai cr"
The PR has a label "askai document"

# After
The PR has a label `askai tests`
The PR has a label `askai cr`
The PR has a label `askai document` 

Update all askAI plugin documentation to use consistent backticks for label references to improve readability and follow technical documentation best practices.

Affected files:

• docs/automations/integrations/askAI/add-tests/README.md
• docs/automations/integrations/askAI/code-review/README.md
• docs/automations/integrations/askAI/document/README.md
• docs/automations/integrations/askAI/improve/README.md
• docs/automations/integrations/askAI/summarize-pr/README.md

API Documentation Issue - plugins/filters/askAI/index.js:1-10

The JSDoc comments have incorrect parameter type and inconsistent documentation:

// Before
* @param {Object} token - The token to the AI model.
* @example {{ branch | generateDescription(pr, repo, source) }}

// After  
* @param {string} token - Your OpenAI API token.
* @example {{ source | askAI("Experienced developer", "Summarize the changes in this PR in bullet points.", env.OPEN_AI_TOKEN) }}

Update the JSDoc comments to:

1. Fix incorrect parameter type for token (Object -> string)
2. Update example to match actual usage
3. Provide more descriptive parameter documentation

This improves API documentation accuracy and helps developers use the plugin correctly.

Content Structure Issue - docs/integrations/askAI.md:1-43

The ordering of askAI use cases is inconsistent and could be better organized:

Current order:
1. Summarize PR
2. PR Review Checklist 
3. PR Improvements
4. Documentation
5. Tests

Suggested order:
1. Summarize PR (High-level overview)
2. PR Review Checklist (Detailed analysis)
3. PR Improvements (Actionable changes)
4. Documentation (Supporting materials)
5. Tests (Quality assurance)

Reorder the sections to follow a logical progression from high-level overview to specific implementations. This improves readability and helps users better understand the capabilities progression.

Formatting Issue - docs/downloads/automation-library/integrations/askAI/*.cm files

The comment headers in AI automation files have inconsistent formatting:

# Before
# ✨ gitStream Review ✨

# After
## gitStream askAI: <purpose> for this PR <emoji>

Standardize the comment headers across all askAI automation files to use:

1. Consistent heading level (##)
2. Standard prefix "gitStream askAI:"
3. Descriptive purpose
4. Relevant emoji
5. Suffix "for this PR"

This improves visual consistency and makes automation outputs more immediately recognizable.

Affected files:

• askAI_CR.cm
• askAI_document.cm
• askAI_improve.cm
• askAI_summarize.cm
• askAI_tests.cm

[PavelLinearB]

/gs run `{{ source | LinearB_AI(prompt="Perform a precise code review based on the provided diff. Identify only necessary changes (e.g., bugs, performance, readability, maintainability). Ignore descriptions of already implemented changes.

For each issue:

• Assign it to the correct file and line number. Reference unchanged lines only if necessary.
• Use a collapsible section with a short, clear title:
  Format → <details><summary><Issue Type - File Path (Line X)></summary><Issue content as described below></details>
• Give a direct, actionable fix. No vague suggestions.
• Provide a code diff in GitHub markdown (+ for additions, - for removals).
• Explain why the fix is needed and how it improves the code.

🚫 Avoid redundant changes (e.g., reformatting without actual improvement).
📂 Sort issues by file and line number.

Focus only on essential, high-impact improvements.") }}`

/gs_run_result

Improvement - plugins/filters/askAI/index.js (Line 98)

The filter function for array context could be simplified and fixed. Current implementation has a bug where it filters the context twice:

- return context.filter(element =>
-   typeof element !== 'object' ? true : context.filter(shouldIncludeFile)
- );
+ return context.filter(element => 
+   typeof element !== 'object' || shouldIncludeFile(element)
+ );

This change:

1. Fixes the bug where non-object elements were being included but object elements were being filtered twice
2. Simplifies the logic to a single filter operation
3. Improves readability with clearer boolean logic
4. Avoids unnecessary array iteration

Improvement - askAI config files (Multiple files)

The AI prompts across config files should include a consistent footer message. Add to all askAI_*.cm files:

 comment: |
   {{ source | askAI(...) }}
+  ---
+  _Generated by gitStream askAI using GPT-4. Human review recommended._

This improves:

1. Consistency across AI-generated comments
2. Transparency about AI generation
3. Sets proper expectations for human reviewers
4. Maintains compliance with AI disclosure best practices

Optional format improvement - docs/automations/integrations/askAI/*/README.md (Multiple files)

The example section formatting in askAI documentation could be standardized across all files for better readability:

 # Title
 
-<!-- --8<-- [start:example]-->
-Description text.
+<!-- --8<-- [start:example]-->
+## Overview
+Description text.
+
+## Usage
 !!! info "Configuration Description"

This improves:

1. Consistency across documentation
2. Easier scanning and navigation
3. Clear separation of overview and usage sections

[PavelLinearB]

/gs run `{{ source | LinearB_AI(prompt=" Perform a precise code review based on the provided diff. Identify only necessary changes (e.g., bugs, performance, readability, maintainability) to the new code. Don't describe the existing code changes in the diff.

For each issue:

• Assign it to the correct file and line number. Reference unchanged lines only if necessary.
• Use a collapsible section with a short, clear title:
  Format → <details><summary><Issue Type - File Path (Line[s] X[-Y])></summary><Issue details></details>
• Give a direct, actionable fix. No vague suggestions.
• Provide a code diff in GitHub markdown (+ for additions, - for removals).
• Explain why the fix is needed and how it improves the code.

Avoid redundant changes (e.g., reformatting without actual improvement).
Sort issues by file path and line number. ") }}`

/gs_run_result

Consistency - docs/automations/integrations/askAI/*/README.md (Multiple files)

Add missing `starter_kits: [genai]` to the following files: - docs/automations/integrations/askAI/summarize-pr/README.md

This ensures consistent metadata across all askAI automation docs.

Formatting - docs/downloads/automation-library/integrations/askAI/askAI_summarize.cm (Line 40)

Add missing footer text:

            {{ source | askAI("experienced software developer focused on code reviews",
              "Review the PR code diff.
-              - Summarize the changes in the PR in an unordered list.", env.OPEN_AI_TOKEN) }}
+              - Summarize the changes in the PR in an unordered list.", env.OPEN_AI_TOKEN) }}
+            _This response was generated by the gitStream askAI plugin._

For consistency with other askAI automation files and improved user feedback.

Documentation - plugins/filters/askAI/reference.md (Line 25)

Change example to reflect updated persona style:

-{{ source | askAI("Experienced developer", "Summarize the changes in this PR in bullet points.", env.OPEN_AI_TOKEN) }}
+{{ source | askAI("experienced software developer focused on code reviews", "Review the PR code diff.\n- Summarize the changes in the PR in an unordered list.", env.OPEN_AI_TOKEN) }}

The example should match the consistent style used in the actual automation files for better developer guidance.

[MishaKav]

/gs run {{ source | LinearB_AI(prompt='This PR looks big, can you suggest how i can split it in multiple PRs?') }}

/gs_run_result Based on the PR content, here's a suggested breakdown into smaller, focused PRs:

1. Documentation Updates PR:

• Update README files and descriptions for all askAI automations
• Standardize titles and descriptions across documentation
• Add security notes and clarifications about AI integration

2. Configuration Files PR:

• Update all .cm configuration files
• Standardize prompts and output formats
• Add consistent footer messages
• Update AI role definitions

3. Core Plugin Updates PR:

• Update askAI plugin implementation
• Update plugin documentation and reference
• Update JSDoc comments and descriptions
• Add file exclusion patterns

4. FAQ and Integration Guide PR:

• Update FAQ section with AI-related questions
• Update integration documentation
• Add new screenshots and examples
• Update security and permissions information

This breakdown allows for:

• Easier review process
• Better tracking of changes
• Reduced risk with smaller changes
• Logical grouping of related changes

[gitstream-cm[bot]]

✨ PR Review Suggestion

LGTM

This review was generated by LinearB AI and Added by gitStream

[gitstream-cm[bot]]

✨ PR Review

LGTM

Generated by LinearB AI and added by gitStream. _{AI-generated content may contain inaccuracies. Please verify before using. We’d love your feedback! 🚀}

[gitstream-cm[bot]]

A screenshot of the relevant part of docs after the changes is a life saver 🛟

[vim-zz]

/gs review