docs: add Tools & Workflows section to AI Risk Hub documentation#2636
docs: add Tools & Workflows section to AI Risk Hub documentation#2636andrzej-janczak wants to merge 5 commits intomasterfrom
Conversation
|
Overall readability score: 54.12 (🟢 +0)
View detailed metrics🟢 - Shows an increase in readability
Averages:
View metric targets
|
Up to standards ✅🟢 Issues
|
![codacy-production[bot]](https://avatars.githubusercontent.com/in/56611?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull Request Overview
The documentation updates for the AI Risk Hub are generally well-structured and align with the expected content for the 'Tools & workflows' section. Codacy indicates the PR is up to standards with no new quality issues. However, a medium-severity Markdown syntax error was found in an example detection string that needs correction to avoid rendering issues. There is also a consistency gap between the category definitions and the filtering options documented. Addressing these items is recommended before merging.
About this PR
- The PR description is empty and no Jira ticket is provided. This lack of context makes it difficult to verify if the documentation completely and accurately reflects the intended product requirements.
Test suggestions
- Verify the presence and correctness of the anchor link in the table of contents.
- Verify the documentation for detection categories (Usage and Workflow) is complete.
- Verify the explanation of the navigation hierarchy (Repositories > Files > Lines).
- Verify that filtering options are documented according to the UI implementation.
🗒️ Improve review quality by adding custom instructions
|
|
||
| ### Navigating tool details | ||
|
|
||
| Clicking a tool card opens a detail view grouped by detection pattern (for example, "Generated with [Claude Code]" or "Generated by Claude"). For each detection pattern, you can drill into: |
There was a problem hiding this comment.
🟡 MEDIUM RISK
The brackets in [Claude Code] will be interpreted as a Markdown link. Since this is an example of a detection string, use backticks to ensure it renders correctly as literal text.
| Clicking a tool card opens a detail view grouped by detection pattern (for example, "Generated with [Claude Code]" or "Generated by Claude"). For each detection pattern, you can drill into: | |
| Clicking a tool card opens a detail view grouped by detection pattern (for example, "Generated with `[Claude Code]`" or "Generated by Claude"). For each detection pattern, you can drill into: |
| - **Repositories** — filter by specific repository names | ||
| - **Categories** — filter by detection category and subcategory: | ||
| - Usage: Code marker, Commit | ||
| - Workflow: Commands, Gitignore, Hooks, Instructions, Settings, Skills |
There was a problem hiding this comment.
⚪ LOW RISK
Suggestion: This list of subcategories is incomplete compared to the categories defined on line 204. For consistency, consider including 'Agent definitions', 'Governance files', and 'IDE configuration'.
| - Workflow: Commands, Gitignore, Hooks, Instructions, Settings, Skills | |
| - Workflow: Agent definitions, Commands, Gitignore, Governance files, Hooks, IDE configuration, Instructions, Settings, Skills |
There was a problem hiding this comment.
Pull request overview
Adds documentation to the AI Risk Hub page describing the new Tools & workflows view, including how detections are categorized and how to navigate/filter tool details, supported by updated UI screenshots.
Changes:
- Adds a new “Tools & workflows” section to the AI Risk Hub documentation and links it from the page’s internal navigation.
- Documents detection categories (Usage vs Workflow) and drill-down navigation for tool detections.
- Adds a new “Tools & workflows detail” screenshot asset.
Reviewed changes
Copilot reviewed 1 out of 3 changed files in this pull request and generated 1 comment.
| File | Description |
|---|---|
| docs/organizations/ai-risk-hub.md | Adds the “Tools & workflows” section, including screenshots and filtering/navigation details. |
| docs/organizations/images/ai-risk-tools-wf-expanded.png | Adds a new screenshot used by the new section. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - **Repositories** — filter by specific repository names | ||
| - **Categories** — filter by detection category and subcategory: | ||
| - Usage: Code marker, Commit | ||
| - Workflow: Commands, Gitignore, Hooks, Instructions, Settings, Skills |
There was a problem hiding this comment.
The category label "Gitignore" is inconsistent with the earlier reference to the actual file name .gitignore and may be unclear to readers. Consider changing this item to .gitignore (or whatever exact label appears in the UI) for accuracy and consistency.
| - Workflow: Commands, Gitignore, Hooks, Instructions, Settings, Skills | |
| - Workflow: Commands, .gitignore, Hooks, Instructions, Settings, Skills |
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 5 changed files in this pull request and generated no new comments.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
andrzej-janczak
force-pushed
the
feature/ai-inv
branch
from
9541385 to
cb8245a
Compare
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 1 out of 5 changed files in this pull request and generated 1 comment.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| - [Overview](#overview) | ||
| - [AI Inventory](#ai-inventory) | ||
| - [AI assets](#ai-assets) | ||
| - [Tools & workflows](#tools-workflows) |
There was a problem hiding this comment.
The intra-page link #tools-workflows likely won’t match the autogenerated heading ID for ## Tools & workflows under MkDocs/Python-Markdown (the & is stripped, typically producing an anchor like #tools--workflows). This will make the TOC link broken. Consider either updating the link target to the generated anchor, or adding an explicit heading id via {: id="tools-workflows" } and keeping the link as-is.
| - [Tools & workflows](#tools-workflows) | |
| - [Tools & workflows](#tools--workflows) |
Live: https://feature-ai-inv--docs-codacy.netlify.app/organizations/ai-risk-hub/