feat(document-review): add documentation review workflow#97
Open
mynhardtburger wants to merge 73 commits intoambient-code:mainfrom
Open
feat(document-review): add documentation review workflow#97mynhardtburger wants to merge 73 commits intoambient-code:mainfrom
mynhardtburger wants to merge 73 commits intoambient-code:mainfrom
Conversation
Add a new ACP workflow that systematically reviews project documentation for errors, inconsistencies, gaps, and quality issues. Includes 7 commands (/scan, /review, /verify, /test, /report, /fix, /speedrun) with a controller-based architecture following the bugfix workflow pattern. Key capabilities: - Auto-discovers and catalogs all documentation files - Evaluates docs against 7 quality dimensions (accuracy, completeness, consistency, clarity, currency, structure, examples) - Cross-references documentation claims against source code - Executes documented instructions to verify they work as written, with environment snapshot/revert for long-lived environments - Generates inline fix suggestions grouped by file Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Add the 7 command files and 7 skill files (controller + 6 phase skills) that were excluded from the prior commit by global .gitignore on .claude/. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
The template extraction and compact report format were applied to the wrong workflow (document-review). This reverts document-review to its original state and applies the changes to pr-doc-review instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Review and verify are independent after scan — split their output into separate findings files (findings-review.md, findings-verify.md) so they can run as parallel sub-agents. Remove test phase from the active workflow (skill retained). Update controller, report, fix, and templates accordingly. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
After review/verify sub-agents complete, a validation sub-agent checks their output for coverage (all inventory docs reviewed), structure (required fields present), and evidence quality (actual quotes, not vague claims). On failure, the failing sub-agent is re-dispatched with specific feedback. Max 1 retry per sub-agent. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
…eper checks Add four improvements adapted from redhat-docs-agent-tools techniques: - Incremental file processing to prevent context window exhaustion - Dual reviewer personas (developer lens / architect lens) by document type - Failure path coverage checks for procedural documents - Expanded code example validation with specific sub-checks and severities Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
After install-test succeeds and before cleanup, a new usage-test agent interacts with the installed project as a user would — executing documented API calls, CLI commands, and workflows against the live cluster. This verifies that usage documentation accurately reflects the actual experience. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Reviewers are notified immediately and the feedback loop via /handle-feedback can start right away. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Add explicit guidance requiring self-contained PR descriptions that explain the problem, list specific file locations, and cite the source of truth. Update the template example to demonstrate this format instead of a generic list of fix numbers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Review skill: - Expand Accuracy dimension to cover empty code blocks, wrong versions, and misleading placeholders (was producing 0 Accuracy findings) - Strengthen evidence requirement: must include direct quotes, not indirect descriptions Scan skill: - Require reading first 40 lines of each file to determine topic and audience instead of guessing from filename Verify skill: - Scan all fields/routes in code areas, not just documented ones, to catch more undocumented features (2 -> 4 found in benchmarks) - Require both doc quotes and code snippets as evidence Benchmarked against opendatahub-io/models-as-a-service (50 docs, Go source). Review Accuracy findings: 0 -> 7. Review evidence quality: 37 -> 110 code blocks. Verify undocumented features: 2 -> 4. Skill vs baseline advantage widened from +15pp to +25pp pass rate. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Remove the cluster-based phases (install-test, usage-test, cleanup) including their commands, skills, templates, and all references across the workflow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Extract the handle-feedback skill and command from document-review into its own workflow at workflows/handle-feedback/. This phase was already standalone (no controller dependency, discovers PRs via GitHub label), so it fits naturally as an independent workflow. New workflow includes ambient.json, CLAUDE.md, README.md, the skill, the command, and copies of the two shared scripts. References removed from document-review's ambient.json, CLAUDE.md, and controller SKILL.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Remove the create-prs phase, its command, skill, pr-log template, and the two helper scripts (now only used by handle-feedback workflow). Clean up all references in ambient.json, CLAUDE.md, controller SKILL.md, report SKILL.md, report template, and README.md. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
The validate skill was a structural quality gate that checked sub-agent output for coverage, filled placeholders, summary table math, required fields, and evidence quality. Modern models reliably follow output format instructions, making this check largely redundant. Removing it simplifies the controller significantly by eliminating the validation loop, retry logic, and related orchestration (~100 lines). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Converts the verify-docs Claude Code plugin into an ACP workflow. The workflow discovers project inputs, outputs, and behaviors from source code, then verifies documentation claims against those discoveries using a four-stage pipeline (reconnaissance, discovery, verification, reporting) with parallel subagents. Signed-off-by: myn <myn@redhat.com> Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Rewrite the verify skill from a flat 5-step process into a 3-stage pipeline (reconnaissance, discovery, verification) that systematically discovers what a project does from source code before cross-referencing against documentation. Add 8 specialized discovery agent reference files for parallel code scanning: env vars, CLI args, config schemas, API endpoints, data models, file I/O, external deps, and build/deploy targets. Add shared inventory fragment format spec. Update findings template with stale references, low-confidence findings, inventory coverage, and code inventory appendix sections. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
- Replace mcp-atlassian MCP dependency with direct Jira REST API calls via curl, authenticated with JIRA_URL/JIRA_EMAIL/JIRA_API_TOKEN env vars - Add pandoc for Markdown-to-Jira wiki markup conversion so descriptions render correctly in Jira (headings, tables, code blocks, etc.) - Change Epic naming: Epic Name uses report date, Summary includes date and scope (repositories) - Use full report.md content as Epic description - Simplify labels to acp:document-review plus user-provided labels (remove per-finding severity/dimension labels) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
…fix version - All metadata fields (project, component, labels, team, initial status) must be explicitly set or acknowledged as blank before issue creation - Add initial status field to transition issues after creation (e.g., Backlog, New, To Do) - Remove fix_version field from skill and command Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Compatible with ubi9/python-311 container image — no brew or dnf needed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Epic description now contains only the header portion of report.md (before ## Summary). The full report is attached to the epic via the Jira attachments API. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Do not set Jira issue priority by default. Leave it undefined unless the user explicitly instructs otherwise. Co-Authored-By: Claude <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
The old names were near-synonyms that didn't convey the distinction between doc-only quality analysis and doc-vs-code cross-referencing. Renames commands, skills, templates, artifact paths, and all references across ambient.json, CLAUDE.md, README.md, controller, report, fix, jira, and both renamed skills. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
The fix phase generated inline fix suggestions but is no longer needed. Removes the command, skill, and template files, and cleans up all references in ambient.json, CLAUDE.md, README.md, controller, and the report template. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
The new name is more descriptive — it immediately conveys that this command runs the entire review pipeline (scan → quality-review + code-check → report) rather than using gaming jargon. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Move Quick Start above Directory Structure and expand it with ACP loading instructions, env var reference table, and a warning about API token visibility in curl commands. Remove incorrect "optional" label from /code-check and "and fixes" from the summary since the workflow is read-only. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
WalkthroughAdds a new Document Review workflow: scanned inventory, quality and code-review phases (parallel), reporting, and optional Jira issue creation, plus controller, skill definitions, discovery agent specs, commands, templates, and ambient configuration. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant Controller
participant Scan
participant QualityReview
participant CodeCheck
participant Report
participant Jira
User->>Controller: /full-review
activate Controller
Controller->>Scan: run /scan
activate Scan
Scan->>Scan: discover docs, write artifacts/inventory.md
Scan-->>Controller: inventory ready
deactivate Scan
par QualityReview & CodeCheck
Controller->>QualityReview: run /quality-review
activate QualityReview
QualityReview->>QualityReview: review docs, write artifacts/findings-quality-review.md
QualityReview-->>Controller: quality findings ready
deactivate QualityReview
and
Controller->>CodeCheck: run /code-check
activate CodeCheck
CodeCheck->>CodeCheck: dispatch discovery agents, verify docs vs code
CodeCheck->>CodeCheck: write artifacts/findings-code-check.md
CodeCheck-->>Controller: code findings ready
deactivate CodeCheck
end
Controller->>Report: run /report
activate Report
Report->>Report: merge & dedupe findings, compute stats
Report->>Report: write artifacts/report.md
Report-->>Controller: report ready
deactivate Report
Controller->>User: report complete (suggest /jira)
alt User runs /jira
User->>Jira: /jira [args]
activate Jira
Jira->>Jira: parse report, create Epic + child issues via REST API
Jira-->>User: issues created
deactivate Jira
end
deactivate Controller
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
- Remove stale "optional" label from code-check in CLAUDE.md - Replace nonexistent "fix version" with "initial status" in README - Fix step numbering skip (3→5) in controller full-review flow Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
Replace Custom Workflow instructions with standard workflow selection since the workflow is auto-discovered after merge. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 12
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@workflows/document-review/.claude/commands/jira.md`:
- Around line 10-13: The prerequisites list for the /jira command is missing the
pandoc dependency required to convert Markdown to Jira wiki markup; update the
prerequisites section in workflows/document-review/.claude/commands/jira.md to
add that pandoc must be installed (e.g., install the pypandoc binary via pip
install pypandoc_binary) and reference that this requirement aligns with
workflows/document-review/.claude/skills/jira/SKILL.md so users have all
dependencies before running the /jira command.
In `@workflows/document-review/.claude/commands/scan.md`:
- Line 3: The controller path in
workflows/document-review/.claude/commands/scan.md currently hardcodes a
relative path (`.claude/skills/controller/SKILL.md`) which breaks when commands
run from repo root; update the path resolution in the `/scan` command to use an
absolute-from-repo path (e.g., resolve against process.cwd() or a repoRoot
constant) or call the dispatcher’s CWD-normalizer before loading the controller;
locate the controller import/require in the scan command and replace the
relative string with a deterministic resolver (or add a small helper to compute
repoRoot and join with `.claude/skills/controller/SKILL.md`) so controller
loading never depends on the current working directory.
In
`@workflows/document-review/.claude/skills/code-check/references/discovery-api-schema.md`:
- Line 51: The directive "Workflow is always `usage`" is ambiguous and
inconsistent with surrounding phase semantics; update the discovery-api-schema
reference to either remove this mode token or replace it with an explicit
instruction for the code-check phase (e.g., "During code-check, run discovery
only to collect schema references and emit validated tokens for the code-check
phase, not full execution"), and ensure the new text documents expected behavior
and agent outputs for the code-check phase so the discovery agent has a clear,
defined mode instead of the undefined `usage` token.
- Around line 15-35: The endpoint discovery patterns only match GET/POST and
miss other HTTP verbs and method-agnostic router forms; update the patterns to
include PUT, PATCH, DELETE, OPTIONS, HEAD and generic route/all/route(...) forms
across frameworks — e.g., add Go symbols like `router.Handle`, `r.PUT(`,
`r.PATCH(`, `r.DELETE(`, `r.OPTIONS(`, `r.HEAD(` and method-agnostic
`router.Route`/`router.All`; Python symbols like `@app.put(`, `@app.patch(`,
`@app.delete(`, `@app.options(`, `@app.head(` and Flask `@app.route(...,
methods=[...])`, Django `path(`/`re_path(` with method-dispatching views); and
Node/TypeScript symbols like `app.put(`, `app.patch(`, `app.delete(`,
`app.options(`, `app.head(`, `app.all(`, `router.route(` and NestJS
`@Put(`/`@Patch(`/`@Delete(`/`@All(`) so the discovery matches the “ALL
endpoints” contract in Line 3.
In
`@workflows/document-review/.claude/skills/code-check/references/discovery-build-deploy.md`:
- Line 58: The line/comment that pre-biases classification ("Workflow is almost
always `installation`") should be removed or replaced so the classifier defaults
to `both` for ambiguous cases; update the classification rule or constant that
enforces this bias (search for the string "Workflow is almost always
`installation`" or the rule that sets default workflow to `installation`) to
instead return `both` when uncertainty is detected, and ensure any unit tests or
documentation referencing the old bias are updated to reflect the new default.
In
`@workflows/document-review/.claude/skills/code-check/references/discovery-file-io.md`:
- Line 45: Update the wording that currently reads "Workflow: output files are
typically `usage`" to broaden the classification and add clarification: change
the phrase to indicate that output files can be `usage` or `installation`
depending on purpose, and add a short criteria sentence plus 2–3 examples
distinguishing the two (e.g., usage: logs, reports, generated examples;
installation: deployment manifests, installers, setup scripts). Locate and edit
the line containing the exact text "Workflow: output files are typically
`usage`" and adjust surrounding documentation to include the decision rule and
examples so readers can distinguish `usage` vs `installation` outputs.
In `@workflows/document-review/.claude/skills/code-check/SKILL.md`:
- Around line 167-188: The finding classification schema currently lists only
"Accuracy" and "Completeness" as allowed values while the doc text defines a
"Staleness" finding type, causing dropped/misclassified stale findings; update
the schema/enum that defines allowed finding types to include "Staleness" (and
ensure any validation or parsing logic accepts it), map "Staleness" to the
intended severity ("High") consistent with the list, and adjust any code that
branches on "Accuracy"/"Completeness" (e.g., validation routines or serializers)
to handle "Staleness" as a first-class classification.
In `@workflows/document-review/.claude/skills/controller/SKILL.md`:
- Line 38: The document contains conflicting phase-order rules: one sentence
says “Phases can be skipped or reordered” while another requires “Scan must run
first” (Controller rule). Make the rules consistent by updating the wording so
the Scan phase is explicitly required to run before other phases (and cannot be
reordered) or alternatively allow skipping but state the precedence clearly; for
example, change the ambiguous sentence to “Phases may be skipped or reordered
except the Scan phase, which must run first,” and update any duplicate instances
(the same text around the other occurrence) to the same phrasing so the
Controller’s phase-order policy is unambiguous.
In `@workflows/document-review/.claude/skills/report/SKILL.md`:
- Around line 74-77: Update Step 4's reporting to check both optional outputs
instead of only artifacts/findings-code-check.md: detect presence of
artifacts/findings-code-check.md and the corresponding quality-review output
(e.g., artifacts/findings-quality-review.md or the project's actual quality file
name), and emit explicit messages for all three cases—only code-check missing,
only quality-review missing (report partial scope), and both missing (no
optional phases performed). Modify the function or block that currently inspects
artifacts/findings-code-check.md (Step 4 logic) to perform both existence checks
and produce the appropriate reason text in the generated report.
- Around line 21-24: The guidance for missing findings is too narrow: update the
message that currently references only `artifacts/findings-quality-review.md`,
`artifacts/findings-code-check.md` and the `/quality-review` command to instead
mention all valid ways to generate findings (e.g., recommend running
`/quality-review`, `/code-check`, or `/full-review`), and adjust any explanatory
text to say "If neither artifacts/findings-quality-review.md nor
artifacts/findings-code-check.md exists, inform the user and recommend running
`/quality-review`, `/code-check`, or `/full-review` to generate report inputs."
Use the same artifact filenames and command names in the updated guidance so the
change is localized to the SKILL.md text.
In `@workflows/document-review/.claude/skills/scan/SKILL.md`:
- Around line 87-93: The fenced discovery pattern block (the triple-backtick
code fence containing the glob lines **/*.md, **/*.rst, **/*.adoc, docs/**/*,
doc/**/*) is missing a language tag and triggers markdownlint MD040; fix it by
adding a language identifier (e.g., text) to the opening code fence so it
becomes ```text, leaving the inner lines unchanged and keeping the closing
triple backticks as is.
In `@workflows/document-review/README.md`:
- Line 50: Update the README warning about `/jira` and JIRA_API_TOKEN to
recommend a safe default workflow (use a masked/secure prompt or credential
store / pre-configured auth helper) instead of instructing users to paste a raw
token into the session; mention `/jira` and JIRA_API_TOKEN explicitly, show how
to configure a secure option (e.g., masked input or environment-backed secret
manager) as the primary example, and keep raw-token-in-session as a clearly
marked discouraged fallback only.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 83d66f28-6614-4429-9f6f-ecac4a4ea2b7
📒 Files selected for processing (28)
workflows/document-review/.ambient/ambient.jsonworkflows/document-review/.claude/commands/code-check.mdworkflows/document-review/.claude/commands/full-review.mdworkflows/document-review/.claude/commands/jira.mdworkflows/document-review/.claude/commands/quality-review.mdworkflows/document-review/.claude/commands/report.mdworkflows/document-review/.claude/commands/scan.mdworkflows/document-review/.claude/skills/code-check/SKILL.mdworkflows/document-review/.claude/skills/code-check/references/discovery-api-schema.mdworkflows/document-review/.claude/skills/code-check/references/discovery-build-deploy.mdworkflows/document-review/.claude/skills/code-check/references/discovery-cli-args.mdworkflows/document-review/.claude/skills/code-check/references/discovery-config-schema.mdworkflows/document-review/.claude/skills/code-check/references/discovery-data-models.mdworkflows/document-review/.claude/skills/code-check/references/discovery-env-vars.mdworkflows/document-review/.claude/skills/code-check/references/discovery-external-deps.mdworkflows/document-review/.claude/skills/code-check/references/discovery-file-io.mdworkflows/document-review/.claude/skills/code-check/references/inventory-format.mdworkflows/document-review/.claude/skills/controller/SKILL.mdworkflows/document-review/.claude/skills/jira/SKILL.mdworkflows/document-review/.claude/skills/quality-review/SKILL.mdworkflows/document-review/.claude/skills/report/SKILL.mdworkflows/document-review/.claude/skills/scan/SKILL.mdworkflows/document-review/CLAUDE.mdworkflows/document-review/README.mdworkflows/document-review/templates/findings-code-check.mdworkflows/document-review/templates/findings-quality-review.mdworkflows/document-review/templates/inventory.mdworkflows/document-review/templates/report.md
Comment on lines
+10
to
+13
| ## Prerequisites | ||
|
|
||
| - `artifacts/report.md` must exist (run `/report` first) | ||
| - `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` environment variables must be set |
There was a problem hiding this comment.
Add missing pandoc prerequisite.
The /jira command requires pandoc to convert Markdown to Jira wiki markup, but this prerequisite is not listed. According to workflows/document-review/.claude/skills/jira/SKILL.md:11-21, pandoc must be installed via pip install pypandoc_binary. This should be documented here to ensure users have all required dependencies before running the command.
📝 Proposed addition
## Prerequisites
- `artifacts/report.md` must exist (run `/report` first)
+- `pandoc` must be installed (install via `pip install pypandoc_binary`)
- `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` environment variables must be set📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ## Prerequisites | |
| - `artifacts/report.md` must exist (run `/report` first) | |
| - `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` environment variables must be set | |
| ## Prerequisites | |
| - `artifacts/report.md` must exist (run `/report` first) | |
| - `pandoc` must be installed (install via `pip install pypandoc_binary`) | |
| - `JIRA_URL`, `JIRA_EMAIL`, and `JIRA_API_TOKEN` environment variables must be set |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/commands/jira.md` around lines 10 - 13, The
prerequisites list for the /jira command is missing the pandoc dependency
required to convert Markdown to Jira wiki markup; update the prerequisites
section in workflows/document-review/.claude/commands/jira.md to add that pandoc
must be installed (e.g., install the pypandoc binary via pip install
pypandoc_binary) and reference that this requirement aligns with
workflows/document-review/.claude/skills/jira/SKILL.md so users have all
dependencies before running the /jira command.
| @@ -0,0 +1,7 @@ | |||
| # /scan | |||
|
|
|||
| Read `.claude/skills/controller/SKILL.md` and follow it. | |||
There was a problem hiding this comment.
Make controller path unambiguous to avoid command breakage
Line 3 hardcodes a relative path that only works if the runtime CWD is the workflow root. If commands run from repo root, controller loading fails and /scan cannot execute. Use an absolute-from-repo path (or document/normalize CWD in the dispatcher) consistently across all command files.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/commands/scan.md` at line 3, The controller
path in workflows/document-review/.claude/commands/scan.md currently hardcodes a
relative path (`.claude/skills/controller/SKILL.md`) which breaks when commands
run from repo root; update the path resolution in the `/scan` command to use an
absolute-from-repo path (e.g., resolve against process.cwd() or a repoRoot
constant) or call the dispatcher’s CWD-normalizer before loading the controller;
locate the controller import/require in the scan command and replace the
relative string with a deterministic resolver (or add a small helper to compute
repoRoot and join with `.claude/skills/controller/SKILL.md`) so controller
loading never depends on the current working directory.
workflows/document-review/.claude/skills/code-check/references/discovery-api-schema.md
Show resolved
Hide resolved
| 4. Note API versioning patterns (path prefix like `/v1/`, header-based, etc.) | ||
| 5. Check for middleware that applies auth, rate limiting, or other | ||
| cross-cutting concerns | ||
| 6. Workflow is always `usage` |
There was a problem hiding this comment.
Clarify or remove the Workflow is always \usage`` directive
Line 51 introduces a mode token that is undefined in this reference and inconsistent with surrounding phase semantics. This is likely to cause mis-execution or confusion for the discovery agent. Replace it with an explicit, documented instruction tied to the code-check phase behavior.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@workflows/document-review/.claude/skills/code-check/references/discovery-api-schema.md`
at line 51, The directive "Workflow is always `usage`" is ambiguous and
inconsistent with surrounding phase semantics; update the discovery-api-schema
reference to either remove this mode token or replace it with an explicit
instruction for the code-check phase (e.g., "During code-check, run discovery
only to collect schema references and emit validated tokens for the code-check
phase, not full execution"), and ensure the new text documents expected behavior
and agent outputs for the code-check phase so the discovery agent has a clear,
defined mode instead of the undefined `usage` token.
| 3. Catalog CI/CD workflows and their triggers | ||
| 4. List all Kustomize overlays, Helm values, or Terraform variables | ||
| 5. Find deployment/setup scripts and their arguments | ||
| 6. Workflow is almost always `installation` |
There was a problem hiding this comment.
Avoid pre-biasing workflow classification to installation.
“Workflow is almost always installation” conflicts with the shared heuristic that ambiguous cases should default to both. This can systematically mis-tag items and degrade downstream merge/report accuracy.
Suggested adjustment
-6. Workflow is almost always `installation`
+6. Classify workflow using the inventory-format heuristics:
+ - `installation` for build/deploy-only usage
+ - `usage` for runtime usage
+ - `both` when present in both contexts
+ - when unclear, default to `both`📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 6. Workflow is almost always `installation` | |
| 6. Classify workflow using the inventory-format heuristics: | |
| - `installation` for build/deploy-only usage | |
| - `usage` for runtime usage | |
| - `both` when present in both contexts | |
| - when unclear, default to `both` |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@workflows/document-review/.claude/skills/code-check/references/discovery-build-deploy.md`
at line 58, The line/comment that pre-biases classification ("Workflow is almost
always `installation`") should be removed or replaced so the classifier defaults
to `both` for ambiguous cases; update the classification rule or constant that
enforces this bias (search for the string "Workflow is almost always
`installation`" or the rule that sets default workflow to `installation`) to
instead return `both` when uncertainty is detected, and ensure any unit tests or
documentation referencing the old bias are updated to reflect the new default.
| Run scan → quality-review + code-check (parallel) → report automatically, pausing | ||
| only for critical decisions. | ||
|
|
||
| Phases can be skipped or reordered at the user's discretion. |
There was a problem hiding this comment.
Controller has conflicting phase-order rules.
“Phases can be skipped or reordered” conflicts with “Scan must run first.” This ambiguity can produce divergent controller behavior across runs.
Suggested wording fix
-Phases can be skipped or reordered at the user's discretion.
+Phases may be requested in any order, but dependency requirements still apply
+(e.g., run `/scan` before phases that require `artifacts/inventory.md`).Also applies to: 47-47
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/skills/controller/SKILL.md` at line 38, The
document contains conflicting phase-order rules: one sentence says “Phases can
be skipped or reordered” while another requires “Scan must run first”
(Controller rule). Make the rules consistent by updating the wording so the Scan
phase is explicitly required to run before other phases (and cannot be
reordered) or alternatively allow skipping but state the precedence clearly; for
example, change the ambiguous sentence to “Phases may be skipped or reordered
except the Scan phase, which must run first,” and update any duplicate instances
(the same text around the other occurrence) to the same phrasing so the
Controller’s phase-order policy is unambiguous.
Comment on lines
+21
to
+24
| - **Findings must exist.** If neither | ||
| `artifacts/findings-quality-review.md` nor | ||
| `artifacts/findings-code-check.md` exists, inform the user and | ||
| recommend running `/quality-review` first. |
There was a problem hiding this comment.
Missing-findings guidance is too narrow.
If both findings files are absent, recommending only /quality-review is incomplete; /code-check or /full-review are equally valid ways to generate report inputs.
Suggested adjustment
-- **Findings must exist.** If neither
- `artifacts/findings-quality-review.md` nor
- `artifacts/findings-code-check.md` exists, inform the user and
- recommend running `/quality-review` first.
+- **Findings must exist.** If neither
+ `artifacts/findings-quality-review.md` nor
+ `artifacts/findings-code-check.md` exists, inform the user and
+ recommend running `/quality-review`, `/code-check`, or `/full-review`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - **Findings must exist.** If neither | |
| `artifacts/findings-quality-review.md` nor | |
| `artifacts/findings-code-check.md` exists, inform the user and | |
| recommend running `/quality-review` first. | |
| - **Findings must exist.** If neither | |
| `artifacts/findings-quality-review.md` nor | |
| `artifacts/findings-code-check.md` exists, inform the user and | |
| recommend running `/quality-review`, `/code-check`, or `/full-review`. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/skills/report/SKILL.md` around lines 21 -
24, The guidance for missing findings is too narrow: update the message that
currently references only `artifacts/findings-quality-review.md`,
`artifacts/findings-code-check.md` and the `/quality-review` command to instead
mention all valid ways to generate findings (e.g., recommend running
`/quality-review`, `/code-check`, or `/full-review`), and adjust any explanatory
text to say "If neither artifacts/findings-quality-review.md nor
artifacts/findings-code-check.md exists, inform the user and recommend running
`/quality-review`, `/code-check`, or `/full-review` to generate report inputs."
Use the same artifact filenames and command names in the updated guidance so the
change is localized to the SKILL.md text.
Comment on lines
+74
to
+77
| Check whether optional phases were skipped and note the reason in the report: | ||
|
|
||
| - If `artifacts/findings-code-check.md` does not exist, note that code verification was not | ||
| performed. |
There was a problem hiding this comment.
Skipped-phase reporting should cover both optional inputs.
Step 4 only documents missing findings-code-check.md. When quality-review is skipped but code-check exists, report scope is also partial and should be explicitly noted.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/skills/report/SKILL.md` around lines 74 -
77, Update Step 4's reporting to check both optional outputs instead of only
artifacts/findings-code-check.md: detect presence of
artifacts/findings-code-check.md and the corresponding quality-review output
(e.g., artifacts/findings-quality-review.md or the project's actual quality file
name), and emit explicit messages for all three cases—only code-check missing,
only quality-review missing (report partial scope), and both missing (no
optional phases performed). Modify the function or block that currently inspects
artifacts/findings-code-check.md (Step 4 logic) to perform both existence checks
and produce the appropriate reason text in the generated report.
Comment on lines
+87
to
+93
| ``` | ||
| **/*.md | ||
| **/*.rst | ||
| **/*.adoc | ||
| docs/**/* | ||
| doc/**/* | ||
| ``` |
There was a problem hiding this comment.
Add a language tag to the fenced discovery pattern block.
Line 87 opens a fenced block without a language, which will trip markdownlint (MD040) in docs CI.
Proposed fix
-```
+```text
**/*.md
**/*.rst
**/*.adoc
docs/**/*
doc/**/*</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **IMPORTANT**
> Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 87-87: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/skills/scan/SKILL.md` around lines 87 - 93,
The fenced discovery pattern block (the triple-backtick code fence containing
the glob lines **/*.md, **/*.rst, **/*.adoc, docs/**/*, doc/**/*) is missing a
language tag and triggers markdownlint MD040; fix it by adding a language
identifier (e.g., text) to the opening code fence so it becomes ```text, leaving
the inner lines unchanged and keeping the closing triple backticks as is.
workflows/document-review/README.md
Outdated
| | `JIRA_TEAM` | No | `team=<name>` | Default team name | | ||
| | `JIRA_INITIAL_STATUS` | No | `status=<name>` | Workflow transition after creation (e.g., `Backlog`) | | ||
|
|
||
| > **Warning:** `/jira` uses `curl` to call the Jira REST API directly because the Atlassian MCP does not support creating epics or issues. Your `JIRA_API_TOKEN` will be visible in the session history. |
There was a problem hiding this comment.
Documented token exposure needs a safer default workflow.
The README currently normalizes secret leakage (“token will be visible in session history”). Please make the recommended path non-leaking by default (masked secret input / secure credential store / pre-configured auth helper), and keep raw-token-in-session as a discouraged fallback only.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/README.md` at line 50, Update the README warning
about `/jira` and JIRA_API_TOKEN to recommend a safe default workflow (use a
masked/secure prompt or credential store / pre-configured auth helper) instead
of instructing users to paste a raw token into the session; mention `/jira` and
JIRA_API_TOKEN explicitly, show how to configure a secure option (e.g., masked
input or environment-backed secret manager) as the primary example, and keep
raw-token-in-session as a clearly marked discouraged fallback only.
…overage - Add explicit Severity field to quality-review and code-check finding templates and skill instructions so the report phase can merge findings without reclassifying them. - Change code-check result-type severity from hard-coded to guidance-based, letting the agent assess each finding individually. - Pipe Jira credentials via stdin (curl --config -) instead of passing them as command-line arguments, preventing exposure in process listings. - Add Java and Ruby search patterns to all 7 language-specific discovery agents and the recon framework-detection step. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
There was a problem hiding this comment.
Actionable comments posted: 3
♻️ Duplicate comments (5)
workflows/document-review/.claude/skills/code-check/references/discovery-api-schema.md (2)
66-66:⚠️ Potential issue | 🟠 MajorReplace the hard-coded workflow mode with explicit phase behavior
Line 66 still uses
Workflow is always usage, which is ambiguous for discovery behavior and output expectations. Replace it with explicit code-check phase instructions and expected output semantics.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/document-review/.claude/skills/code-check/references/discovery-api-schema.md` at line 66, Replace the hard-coded statement "Workflow is always `usage`" with an explicit description of the code-check phase and expected outputs: update the section that currently contains the line "Workflow is always `usage`" to specify the phase name (e.g., "code-check"), enumerate the behavior for that phase (what inputs are validated, what checks are run), and define expected output semantics (pass/fail results, error formats, and example response shape). Ensure the new wording replaces the ambiguous text and includes concrete expectations for discovery behavior and output to guide implementers and validators.
17-49:⚠️ Potential issue | 🟠 MajorEndpoint discovery still under-covers non-GET/POST routes
Line 17 through Line 49 still biases patterns toward GET/POST and generic
router.tokens. This can miss PUT/PATCH/DELETE/OPTIONS/HEAD and method-agnostic forms, which breaks the “ALL endpoints” requirement in Line 3.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/document-review/.claude/skills/code-check/references/discovery-api-schema.md` around lines 17 - 49, Expand the endpoint-discovery patterns to cover non-GET/POST methods and method-agnostic forms: add tokens for PUT/PATCH/DELETE/OPTIONS/HEAD (e.g., r.PUT / r.PATCH / r.DELETE, `@app.put` / `@app.patch` / app.delete, app.options / app.head, Express .put/.patch/.delete/.options/.head, NestJS `@Put/`@Patch/@Delete/@Options/@Head, Spring `@PutMapping/`@PatchMapping/@DeleteMapping/@RequestMapping(method=...), JAX-RS `@PUT/`@PATCH/@DELETE/@OPTIONS/@HEAD), and include method-agnostic patterns like app.route(..., methods=[...]), router.add_route, router.Handle/router.HandleFunc with method params, match/any/resources/: and generic `router.`/`route(`/`app.route(` tokens so discovery meets the “ALL endpoints” requirement.workflows/document-review/templates/findings-code-check.md (1)
34-47:⚠️ Potential issue | 🟠 MajorInclude
Sourcein code-check finding recordsLine 34–47 should include a
Sourcefield (e.g.,code-check) so consolidated reporting can merge and trace findings consistently without inference.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/document-review/templates/findings-code-check.md` around lines 34 - 47, The finding entry in the template block (the record that lists Severity/Dimension/Doc location/Code location/Documented claim/Actual behavior/Evidence/Fix) is missing a Source field; update the template in workflows/document-review/templates/findings-code-check.md to add a "Source: code-check" (or equivalent canonical source token) alongside the other metadata fields so automated reporting can merge these findings reliably—ensure the new "Source" line appears for the specific finding that references DEFAULT_MAX_RETRIES = 5 and the README Configuration claim.workflows/document-review/.claude/skills/code-check/SKILL.md (1)
170-205:⚠️ Potential issue | 🟠 MajorFinding schema still excludes
Staleness.Line 204 conflicts with Lines 170-193: you define stale findings but the allowed
Dimensionvalues omitStaleness, which risks dropped or mislabeled findings.As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."Proposed fix
-- **Dimension**: Accuracy or Completeness +- **Dimension**: Accuracy, Completeness, or Staleness🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/document-review/.claude/skills/code-check/SKILL.md` around lines 170 - 205, The docs introduce a "Staleness" finding type but the allowed Dimension values exclude it, causing mismatches; update the findings schema to include "Staleness" as a valid Dimension value (and any related enums/validation logic) and adjust the findings generation/validation code and templates that reference the Dimension list (e.g., the findings schema/enum and the templates/findings-code-check.md usage of "Dimension") so that "Staleness" is accepted and rendered consistently in outputs and tests.workflows/document-review/README.md (1)
50-50:⚠️ Potential issue | 🟠 MajorUse a non-leaking default for
/jiracredentials.Line 50 still normalizes exposing
JIRA_API_TOKENin session history. The README should recommend a secure default workflow first (masked prompt / secret manager / pre-configured environment), and keep raw token pasting as an explicit discouraged fallback.As per coding guidelines, "Focus on major issues impacting performance, readability, maintainability and security. Avoid nitpicks and avoid verbosity."Suggested README adjustment
-> **Warning:** `/jira` uses `curl` to call the Jira REST API directly because the Atlassian MCP does not support creating epics or issues. Credentials are piped via stdin (`curl --config -`) to avoid exposure in process listings, but your `JIRA_API_TOKEN` will still be visible in the session history. +> **Security note:** `/jira` uses `curl` to call the Jira REST API directly because the Atlassian MCP does not support creating epics or issues. +> **Recommended (default):** provide `JIRA_API_TOKEN` via a secure secret source (masked input, environment-backed secret manager, or pre-configured auth helper) so the raw token is never pasted into chat/session text. +> Credentials are piped via stdin (`curl --config -`) to avoid exposure in process listings. +> **Discouraged fallback:** pasting a raw token into the session, which can expose it in session history.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@workflows/document-review/README.md` at line 50, Update the README note for the /jira endpoint to recommend a non-leaking default: instruct users to obtain credentials via a masked prompt (interactive secret entry), a secret manager, or pre-configured environment variables/secrets injection in CI/CD, and present piping raw JIRA_API_TOKEN into curl as an explicit discouraged fallback; keep the warning about session history exposure and mention using secure storage or masked input as the preferred workflow (refer to the README section about /jira).
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In
`@workflows/document-review/.claude/skills/code-check/references/discovery-env-vars.md`:
- Around line 73-75: Update the test-file exclusion pattern list that currently
reads "Exclude matches in test files (paths containing `test/`, `_test.go`,
`test_`, `.test.`, `__tests__`) UNLESS the variable also appears in non-test
code" to include additional common test patterns—e.g., `tests/`, `spec/`,
`*_test.py`, `*.spec.ts`, `*.spec.js`—so the ruleset filters more test-only env
vars while preserving the existing exception that a variable is included if it
also appears in non-test code; locate and modify the text block containing that
exclusion list and ensure the wording and examples reflect the expanded
patterns.
In `@workflows/document-review/.claude/skills/jira/SKILL.md`:
- Around line 97-103: The curl examples currently inject raw JSON via -d '...'
which breaks if injected report text contains quotes/newlines; replace these
examples to show building the request body with a JSON serializer (e.g., jq -n
or similar) and then pass the serialized output to curl (using --data `@-` or
--data-binary `@-`) instead of inline -d; update the snippets around the curl
invocation (the lines using printf 'user = "%s:%s"' and the curl --config -
call) to demonstrate generating a safe JSON payload with jq and piping or
referencing that payload to curl so quotes/newlines are properly escaped.
In `@workflows/document-review/templates/findings-quality-review.md`:
- Around line 31-38: The findings template is missing a Source field which
downstream merging requires; update the finding block in
workflows/document-review/templates/findings-quality-review.md (the block
containing "**Severity:** Critical", "**Dimension:** Accuracy", "**File:**
`path/to/document.md:42`", "**Issue:** ...", "**Evidence:** ...", "**Fix:**
...") by adding a line "- **Source:** quality-review" so every finding entry
includes the required provenance field for machine merging.
---
Duplicate comments:
In
`@workflows/document-review/.claude/skills/code-check/references/discovery-api-schema.md`:
- Line 66: Replace the hard-coded statement "Workflow is always `usage`" with an
explicit description of the code-check phase and expected outputs: update the
section that currently contains the line "Workflow is always `usage`" to specify
the phase name (e.g., "code-check"), enumerate the behavior for that phase (what
inputs are validated, what checks are run), and define expected output semantics
(pass/fail results, error formats, and example response shape). Ensure the new
wording replaces the ambiguous text and includes concrete expectations for
discovery behavior and output to guide implementers and validators.
- Around line 17-49: Expand the endpoint-discovery patterns to cover
non-GET/POST methods and method-agnostic forms: add tokens for
PUT/PATCH/DELETE/OPTIONS/HEAD (e.g., r.PUT / r.PATCH / r.DELETE, `@app.put` /
`@app.patch` / app.delete, app.options / app.head, Express
.put/.patch/.delete/.options/.head, NestJS `@Put/`@Patch/@Delete/@Options/@Head,
Spring `@PutMapping/`@PatchMapping/@DeleteMapping/@RequestMapping(method=...),
JAX-RS `@PUT/`@PATCH/@DELETE/@OPTIONS/@HEAD), and include method-agnostic patterns
like app.route(..., methods=[...]), router.add_route,
router.Handle/router.HandleFunc with method params, match/any/resources/: and
generic `router.`/`route(`/`app.route(` tokens so discovery meets the “ALL
endpoints” requirement.
In `@workflows/document-review/.claude/skills/code-check/SKILL.md`:
- Around line 170-205: The docs introduce a "Staleness" finding type but the
allowed Dimension values exclude it, causing mismatches; update the findings
schema to include "Staleness" as a valid Dimension value (and any related
enums/validation logic) and adjust the findings generation/validation code and
templates that reference the Dimension list (e.g., the findings schema/enum and
the templates/findings-code-check.md usage of "Dimension") so that "Staleness"
is accepted and rendered consistently in outputs and tests.
In `@workflows/document-review/README.md`:
- Line 50: Update the README note for the /jira endpoint to recommend a
non-leaking default: instruct users to obtain credentials via a masked prompt
(interactive secret entry), a secret manager, or pre-configured environment
variables/secrets injection in CI/CD, and present piping raw JIRA_API_TOKEN into
curl as an explicit discouraged fallback; keep the warning about session history
exposure and mention using secure storage or masked input as the preferred
workflow (refer to the README section about /jira).
In `@workflows/document-review/templates/findings-code-check.md`:
- Around line 34-47: The finding entry in the template block (the record that
lists Severity/Dimension/Doc location/Code location/Documented claim/Actual
behavior/Evidence/Fix) is missing a Source field; update the template in
workflows/document-review/templates/findings-code-check.md to add a "Source:
code-check" (or equivalent canonical source token) alongside the other metadata
fields so automated reporting can merge these findings reliably—ensure the new
"Source" line appears for the specific finding that references
DEFAULT_MAX_RETRIES = 5 and the README Configuration claim.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 069f7d28-6da8-415c-bfe5-bd6c765baae6
📒 Files selected for processing (13)
workflows/document-review/.claude/skills/code-check/SKILL.mdworkflows/document-review/.claude/skills/code-check/references/discovery-api-schema.mdworkflows/document-review/.claude/skills/code-check/references/discovery-cli-args.mdworkflows/document-review/.claude/skills/code-check/references/discovery-config-schema.mdworkflows/document-review/.claude/skills/code-check/references/discovery-data-models.mdworkflows/document-review/.claude/skills/code-check/references/discovery-env-vars.mdworkflows/document-review/.claude/skills/code-check/references/discovery-external-deps.mdworkflows/document-review/.claude/skills/code-check/references/discovery-file-io.mdworkflows/document-review/.claude/skills/jira/SKILL.mdworkflows/document-review/.claude/skills/quality-review/SKILL.mdworkflows/document-review/README.mdworkflows/document-review/templates/findings-code-check.mdworkflows/document-review/templates/findings-quality-review.md
Comment on lines
+73
to
+75
| 3. Exclude matches in test files (paths containing `test/`, `_test.go`, | ||
| `test_`, `.test.`, `__tests__`) UNLESS the variable also appears in | ||
| non-test code |
There was a problem hiding this comment.
Broaden test-file exclusion patterns to reduce false positives
Line 73’s exclusion list is too narrow and will capture many test-only environment variables, which pollutes inventory and report deduplication quality. Add common patterns like tests/, spec/, *_test.py, *.spec.ts, and *.spec.js.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In
`@workflows/document-review/.claude/skills/code-check/references/discovery-env-vars.md`
around lines 73 - 75, Update the test-file exclusion pattern list that currently
reads "Exclude matches in test files (paths containing `test/`, `_test.go`,
`test_`, `.test.`, `__tests__`) UNLESS the variable also appears in non-test
code" to include additional common test patterns—e.g., `tests/`, `spec/`,
`*_test.py`, `*.spec.ts`, `*.spec.js`—so the ruleset filters more test-only env
vars while preserving the existing exception that a variable is included if it
also appears in non-test code; locate and modify the text block containing that
exclusion list and ensure the wording and examples reflect the expanded
patterns.
Comment on lines
+97
to
+103
| ```bash | ||
| printf 'user = "%s:%s"\n' "$JIRA_EMAIL" "$JIRA_API_TOKEN" | \ | ||
| curl --config - \ | ||
| -X POST \ | ||
| -H "Content-Type: application/json" \ | ||
| -d '...' \ | ||
| "$JIRA_URL/rest/api/2/issue" |
There was a problem hiding this comment.
Use JSON-safe payload construction for Jira requests
Line 97–103 and Line 182–206 rely on raw -d '...' payload examples while injecting rich text from findings. Any quotes/newlines in report content can break JSON and fail issue creation. Build request bodies with a JSON serializer (jq -n/equivalent) and pass the generated payload to curl.
Suggested doc update pattern
- curl --config - \
- -X POST \
- -H "Content-Type: application/json" \
- -d '...' \
- "$JIRA_URL/rest/api/2/issue"
+ payload="$(jq -n \
+ --arg project "$PROJECT_KEY" \
+ --arg summary "$SUMMARY" \
+ --arg description "$DESCRIPTION_WIKI" \
+ '{
+ fields: {
+ project: { key: $project },
+ summary: $summary,
+ description: $description
+ }
+ }')"
+ curl --config - \
+ -X POST \
+ -H "Content-Type: application/json" \
+ --data "$payload" \
+ "$JIRA_URL/rest/api/2/issue"Also applies to: 182-206
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/skills/jira/SKILL.md` around lines 97 -
103, The curl examples currently inject raw JSON via -d '...' which breaks if
injected report text contains quotes/newlines; replace these examples to show
building the request body with a JSON serializer (e.g., jq -n or similar) and
then pass the serialized output to curl (using --data `@-` or --data-binary `@-`)
instead of inline -d; update the snippets around the curl invocation (the lines
using printf 'user = "%s:%s"' and the curl --config - call) to demonstrate
generating a safe JSON payload with jq and piping or referencing that payload to
curl so quotes/newlines are properly escaped.
Comment on lines
+31
to
+38
| - **Severity:** Critical | ||
| - **Dimension:** Accuracy | ||
| - **File:** `path/to/document.md:42` | ||
| - **Issue:** The documented command uses a flag that doesn't exist. | ||
| - **Evidence:** `pip install --global mypackage` | ||
| (`--global` is not a valid pip flag) | ||
| - **Fix:** Change `--global` to `--user` or remove the flag entirely. | ||
|
|
There was a problem hiding this comment.
Add an explicit Source field to each finding entry
Line 31–38 omits Source (quality-review/code-check), but downstream report merging depends on phase provenance. Add - **Source:** quality-review to the template’s finding block to keep artifact schema consistent and machine-mergeable.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/templates/findings-quality-review.md` around lines
31 - 38, The findings template is missing a Source field which downstream
merging requires; update the finding block in
workflows/document-review/templates/findings-quality-review.md (the block
containing "**Severity:** Critical", "**Dimension:** Accuracy", "**File:**
`path/to/document.md:42`", "**Issue:** ...", "**Evidence:** ...", "**Fix:**
...") by adding a line "- **Source:** quality-review" so every finding entry
includes the required provenance field for machine merging.
- Add a title, brief description, output path, and prerequisites or arguments to each command file so users see useful context when invoking commands. - Move /full-review out of the numbered phase list in CLAUDE.md into a separate Convenience Commands section since it is a composite command, not a distinct phase. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> Signed-off-by: Mynhardt Burger <mynhardt@gmail.com> rh-pre-commit.version: 2.3.2 rh-pre-commit.check-secrets: ENABLED
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@workflows/document-review/.claude/commands/code-check.md`:
- Line 9: The command currently uses a relative controller path (the string
".claude/skills/controller/SKILL.md") which is cwd-dependent and can fail;
update the command to reference a repo-root-qualified controller path instead
(i.e., construct the path starting from the repository root rather than a
relative path) so the tool always resolves the controller regardless of working
directory, and ensure any tests or callers that invoke the command use the same
repo-root-qualified form.
In `@workflows/document-review/.claude/commands/full-review.md`:
- Line 6: The hardcoded controller reference
".claude/skills/controller/SKILL.md" depends on the current working directory
and can break the /full-review flow; update the code that builds or reads this
path to compute it relative to the script file (e.g., using __dirname or
import.meta.url with path.resolve/path.join) or resolve the repository root
reliably (git rev-parse or a repo-root helper) and then join "
.claude/skills/controller/SKILL.md", replacing any direct use of the literal
".claude/skills/controller/SKILL.md" so the dispatcher for /full-review always
finds the controller regardless of CWD.
In `@workflows/document-review/.claude/commands/report.md`:
- Line 10: The reference "Read `.claude/skills/controller/SKILL.md` and follow
it." uses a relative path that can fail at runtime; update that string to a
repo-root-qualified path (i.e., prepend the repository-root indicator so the
path resolves reliably at runtime) wherever it appears in the report.md,
ensuring the controller skill is referenced with the full repo-root-qualified
file path instead of the bare relative path.
In `@workflows/document-review/CLAUDE.md`:
- Line 11: The heading "Convenience Commands" currently uses a level-3 heading
(###) which skips an expected level-2 under the document structure; change the
heading markup for "Convenience Commands" from ### to ## so it properly follows
the previous section level and satisfies MD001, ensuring heading hierarchy is
consistent.
- Around line 18-20: The markdown uses relative paths that assume the workflow
CWD; update the references to be repo-root-qualified so they resolve regardless
of working directory—replace `.claude/skills/controller/SKILL.md` and
`.claude/skills/{name}/SKILL.md` with explicit repo-root paths (e.g., prefix
with `/` or the repository root variable you use) throughout this document so
users running commands from the repo root won't get broken links or
instructions; ensure any other similar references in this file follow the same
pattern.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: df9ab888-c0da-4897-92cc-bd912f091aac
📒 Files selected for processing (6)
workflows/document-review/.claude/commands/code-check.mdworkflows/document-review/.claude/commands/full-review.mdworkflows/document-review/.claude/commands/quality-review.mdworkflows/document-review/.claude/commands/report.mdworkflows/document-review/.claude/commands/scan.mdworkflows/document-review/CLAUDE.md
|
|
||
| **Requires:** `/scan` must have been run first. | ||
|
|
||
| Read `.claude/skills/controller/SKILL.md` and follow it. |
There was a problem hiding this comment.
Use a repo-root-qualified controller path to prevent command breakage.
This relative path depends on current working directory and can fail outside workflows/document-review/.
Proposed fix
-Read `.claude/skills/controller/SKILL.md` and follow it.
+Read `workflows/document-review/.claude/skills/controller/SKILL.md` and follow it.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Read `.claude/skills/controller/SKILL.md` and follow it. | |
| Read `workflows/document-review/.claude/skills/controller/SKILL.md` and follow it. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/commands/code-check.md` at line 9, The
command currently uses a relative controller path (the string
".claude/skills/controller/SKILL.md") which is cwd-dependent and can fail;
update the command to reference a repo-root-qualified controller path instead
(i.e., construct the path starting from the repository root rather than a
relative path) so the tool always resolves the controller regardless of working
directory, and ensure any tests or callers that invoke the command use the same
repo-root-qualified form.
| Runs scan → quality-review + code-check (parallel) → report in one shot, | ||
| pausing only for critical decisions. Results are written to `artifacts/`. | ||
|
|
||
| Read `.claude/skills/controller/SKILL.md` and follow it. |
There was a problem hiding this comment.
Controller path should not depend on CWD.
If dispatcher runs from repo root, this reference may fail and block /full-review.
Proposed fix
-Read `.claude/skills/controller/SKILL.md` and follow it.
+Read `workflows/document-review/.claude/skills/controller/SKILL.md` and follow it.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Read `.claude/skills/controller/SKILL.md` and follow it. | |
| Read `workflows/document-review/.claude/skills/controller/SKILL.md` and follow it. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/commands/full-review.md` at line 6, The
hardcoded controller reference ".claude/skills/controller/SKILL.md" depends on
the current working directory and can break the /full-review flow; update the
code that builds or reads this path to compute it relative to the script file
(e.g., using __dirname or import.meta.url with path.resolve/path.join) or
resolve the repository root reliably (git rev-parse or a repo-root helper) and
then join " .claude/skills/controller/SKILL.md", replacing any direct use of the
literal ".claude/skills/controller/SKILL.md" so the dispatcher for /full-review
always finds the controller regardless of CWD.
|
|
||
| **Requires:** `/scan` must have been run first. | ||
|
|
||
| Read `.claude/skills/controller/SKILL.md` and follow it. |
There was a problem hiding this comment.
Make controller reference deterministic (repo-root path).
Current path is CWD-sensitive and may fail in common execution contexts.
Proposed fix
-Read `.claude/skills/controller/SKILL.md` and follow it.
+Read `workflows/document-review/.claude/skills/controller/SKILL.md` and follow it.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Read `.claude/skills/controller/SKILL.md` and follow it. | |
| Read `workflows/document-review/.claude/skills/controller/SKILL.md` and follow it. |
| **Requires:** At least one of `/quality-review` or `/code-check` must have | ||
| been run first. | ||
|
|
||
| Read `.claude/skills/controller/SKILL.md` and follow it. |
There was a problem hiding this comment.
Fix controller skill path to avoid runtime resolution failures.
Use a repo-root-qualified path here as well.
Proposed fix
-Read `.claude/skills/controller/SKILL.md` and follow it.
+Read `workflows/document-review/.claude/skills/controller/SKILL.md` and follow it.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Read `.claude/skills/controller/SKILL.md` and follow it. | |
| Read `workflows/document-review/.claude/skills/controller/SKILL.md` and follow it. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/.claude/commands/report.md` at line 10, The
reference "Read `.claude/skills/controller/SKILL.md` and follow it." uses a
relative path that can fail at runtime; update that string to a
repo-root-qualified path (i.e., prepend the repository-root indicator so the
path resolves reliably at runtime) wherever it appears in the report.md,
ensuring the controller skill is referenced with the full repo-root-qualified
file path instead of the bare relative path.
| 4. **Report** (`/report`) — Consolidate all findings into a single deduplicated report | ||
| 5. **Jira** (`/jira`) — *(Optional)* Create Jira epic with child bugs/tasks from the report | ||
|
|
||
| ### Convenience Commands |
There was a problem hiding this comment.
Fix heading level increment (MD001).
### Convenience Commands skips an ## level under the current structure.
Proposed fix
-### Convenience Commands
+## Convenience Commands📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| ### Convenience Commands | |
| ## Convenience Commands |
🧰 Tools
🪛 markdownlint-cli2 (0.22.0)
[warning] 11-11: Heading levels should only increment by one level at a time
Expected: h2; Actual: h3
(MD001, heading-increment)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/CLAUDE.md` at line 11, The heading "Convenience
Commands" currently uses a level-3 heading (###) which skips an expected level-2
under the document structure; change the heading markup for "Convenience
Commands" from ### to ## so it properly follows the previous section level and
satisfies MD001, ensuring heading hierarchy is consistent.
Comment on lines
+18
to
+20
| The workflow controller lives at `.claude/skills/controller/SKILL.md`. | ||
| It defines how to execute phases, recommend next steps, and handle transitions. | ||
| Phase skills are at `.claude/skills/{name}/SKILL.md`. |
There was a problem hiding this comment.
Path references are ambiguous outside workflow-root CWD.
These references should be repo-root-qualified to avoid broken instructions when users execute from repository root.
Proposed fix
-The workflow controller lives at `.claude/skills/controller/SKILL.md`.
+The workflow controller lives at `workflows/document-review/.claude/skills/controller/SKILL.md`.
It defines how to execute phases, recommend next steps, and handle transitions.
-Phase skills are at `.claude/skills/{name}/SKILL.md`.
+Phase skills are at `workflows/document-review/.claude/skills/{name}/SKILL.md`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| The workflow controller lives at `.claude/skills/controller/SKILL.md`. | |
| It defines how to execute phases, recommend next steps, and handle transitions. | |
| Phase skills are at `.claude/skills/{name}/SKILL.md`. | |
| The workflow controller lives at `workflows/document-review/.claude/skills/controller/SKILL.md`. | |
| It defines how to execute phases, recommend next steps, and handle transitions. | |
| Phase skills are at `workflows/document-review/.claude/skills/{name}/SKILL.md`. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@workflows/document-review/CLAUDE.md` around lines 18 - 20, The markdown uses
relative paths that assume the workflow CWD; update the references to be
repo-root-qualified so they resolve regardless of working directory—replace
`.claude/skills/controller/SKILL.md` and `.claude/skills/{name}/SKILL.md` with
explicit repo-root paths (e.g., prefix with `/` or the repository root variable
you use) throughout this document so users running commands from the repo root
won't get broken links or instructions; ensure any other similar references in
this file follow the same pattern.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
consistency
Useful as a "garbage collection" process which can be scheduled to run occasionally (eg. every 2 weeks) to highlight issues. Use the
/jiraskill after the report is generated to create a Jira epic with child bugs/tasks to track the resolution.Workflow
/scan→/quality-review+/code-check(parallel) →/report→/jira(optional)Or run
/full-reviewfor the full pipeline in one shot (excluding/jira).Commands
/scan/quality-review/code-check/report/jira/full-review