📝 docs: improve askAI plugin documentation

[azigler]

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
• Good Enough
• Needs Improvement

✨ PR Description

Purpose: Updates documentation and improves clarity around gitStream's AI integration features, particularly focusing on consistent terminology and better descriptions of AI-powered PR analysis capabilities.

Main changes:

• Renamed and standardized AI automation titles/descriptions for better clarity and consistency
• Added clear warning about AI plugin's data sharing and potential API costs
• Updated AI prompts and roles across all askAI examples to be more specific and professional

[jit-ci]

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.

[orca-security-us]

Orca Security Scan Summary

Status	Check	Issues by priority
Passed	Infrastructure as Code	0   0   0   0	View in Orca
Passed	Secrets	0   0   0   0	View in Orca
Passed	Vulnerabilities	0   0   0   0	View in Orca

[BenLloydPearson]

I have a few comments, but nothing that should block publishing these changes.

[BenLloydPearson]

I'm concerned about putting the prompt info into the CM file, rather than incorporating it into the plugin code because this has a risk of becoming messy if we build out additional use cases this way.

Is it possible to incorporate the prompt into the plugin? I'm imagining it as a JSON file that's pulled into the code for easy updates.

[azigler]

@BenLloydPearson One way we could do this is using the gitStream readFile filter in a .cm config to import *.txt files from a askAI/prompts/ folder as strings. Then we could maintain the prompts there or even use multiple readFile function calls to "build" a prompt for each use case. Something like this:

automations:
  ask_ai_summarize:
    if:
      - true
    run:
      - action: add-comment@v1
        args:
          comment: |
            {{ TITLE }}
            {{ source | askAI(ROLE, PROMPT, env.OPEN_AI_TOKEN) }}

TITLE: ## gitStream askAI: summary for this PR 📜
ROLE: {{ "./.cm/plugins/filters/askAI/prompts/PR_summary_role.txt" | readFile() }}
PROMPT: {{ "./.cm/plugins/filters/askAI/prompts/PR_summary_prompt.txt" | readFile() }}

Using variables in this approach makes it so each AI automation uses the same base configuration, and you simply adjust behavior by swapping in and out prompts. I think a small folder of combinable prompts is the good way to approach this for longevity while keeping it flat and intuitive, but open to more brainstorming here.

Alternatively, we could change the plugin's .js file to load prompts this way, but feels less composable for dev adoption in the long run. @PavelLinearB probably has an opinion on a good approach.

[BenLloydPearson]

I love this solution.

I think your naming convention for the txt files should work, but just be wary that we'll want to make sure we follow something that's consistent, descriptive, and sorts properly alphabetically (i.e. the prompt and role should appear next to each other when viewed inside the directory.) I believe your convention should check all these boxes, and we can adjust in the future if we find too many edge cases.

[PavelLinearB]

Using the ReadFile filter looks great imo! It will require a bit more work from users tho, but once we'll open PRs to install automations this will be super easy and neat

[gitstream-cm]

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

[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="Review the provided code diff and identify only necessary changes (bugs, performance, readability, maintainability). Ignore already implemented changes.

For each issue:

Use a collapsible section:

Provide a GitHub markdown code diff (+ for additions, - for removals). Explain the fix's impact. Sort by file and line number. 🚫 No redundant or vague suggestions. 🎯 Only essential, high-impact improvements.") }}`

/gs_run_result

Readability - docs/automations/integrations/askAI/code-review/README.md

- If all functions are covered completely, return 'no tests to suggest.'
+ If all functions are covered, return 'No additional tests needed.'

Consistent messaging with other code review sections.

Enhancement - docs/downloads/automation-library/integrations/askAI/askAI_CR.cm

         args:
           comment: |
             ## gitStream askAI: code review checklist for this PR ✨
+            <!-- START gitStream Code Review -->
             {{ source | askAI("experienced software developer focused on code reviews",
               "Review the PR code diff.
               - Identify bugs, security risks, and performance issues.
               - Check for deprecated methods and style guide violations.
               - Suggest specific improvements based on the changes.
               - Provide a code review checklist that can be utilized by a human reviewer.", env.OPEN_AI_TOKEN) }}
             _This response was generated by the gitStream askAI plugin._
+            <!-- END gitStream Code Review -->

Adds HTML comments to clearly mark generated content sections for parsing.

Consistency - plugins/filters/askAI/index.js and reference.md

- model: 'gpt-4o-2024-08-06',
+ model: 'gpt-4',  // Update to latest stable model version

Ensures consistent model version reference across documentation and code.

These changes improve code organization, readability and maintainability while keeping functionality intact.

[PavelLinearB]

Using the ReadFile filter looks great imo! It will require a bit more work from users tho, but once we'll open PRs to install automations this will be super easy and neat

[PavelLinearB]

I think we should also add that the user fully controls the data that is shared with LinearB or any other service as they have the control over the arguments for each filter

[gitstream-cm]

gitStream review assistant

Enhancement - askAI_CR.cm (Line 17)

Improve the AI role prompt by being more specific about the code review focus:

-            {{ source | askAI("Code reviewer",
+            {{ source | askAI("experienced software developer focused on code reviews",

This change makes the AI role more specific and helps generate more focused and relevant code review responses.

Enhancement - plugins/filters/askAI/index.js (Line 8)

Update the JSDoc token parameter type to be more accurate:

- * @param {Object} token - The token to the AI model.
+ * @param {string} token - Your OpenAI API token.

This change makes the parameter type more accurate since the token is expected to be a string, not an object.

Enhancement - plugins/filters/askAI/index.js (Lines 3-4)

Improve plugin description and first parameter documentation:

- * @description A gitStream plugin to interact with AI models. Currently works with `ChatGPR-4o-mini`.
- * @param {Object} context - The context that will be attached to the prompt.
+ * @description A gitStream plugin to facilitate AI workflows with OpenAI's `gpt-4o-2024-08-06` model.
+ * @param {Object} context - The context to be sent to the AI model with the prompt.

This change provides more accurate and detailed information about the plugin's purpose and parameters.

Enhancement - All askAI automation files

Add a consistent footer message to all AI-generated responses:

+            _This response was generated by the gitStream askAI plugin._

This change adds transparency by clearly indicating the source of the generated content. Add this line to all askAI automation files except askAI_summarize.cm which already includes an equivalent message.

Please rate this LinearB_AI review:

• Excellent
• Good Enough
• Needs Improvement