Repository navigation
Phase 7: documentation (X2–X7) - #13
Merged
Merged
Conversation
tools/Update-ParameterReference.ps1 reads the parameters: block of ai-code-review/stage-template.yml (name, type, default, allowed values, and the comment lines above each parameter as its description) and writes docs/parameters.md. With -Check it writes nothing and fails when the file is stale; the PowerShell CI job runs it that way, and PSScriptAnalyzer now covers tools/ too. The template gains comments for the parameters that had none, so every row has a description. The README links the reference instead of the placeholder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D8A4vweKZ8kvVx35iDBhzj
docs/troubleshooting.md covers the first-setup problems: the stage skipped on non-PR runs, comments refused because the service connection's identity is not in the Azure DevOps organisation or cannot contribute to pull requests (the step can still end green with no-comments), 401/403 from the model without the OpenAI User role, foundryTokenResource for classic Azure OpenAI, missing or overridden variables and self-hosted agent pools, plus a table of the engine's other error messages. The README links it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D8A4vweKZ8kvVx35iDBhzj
One page for the optional metrics service: the deploy steps in short (linking infra/README.md), connecting the pipeline's variable group, the four AUTH_MODE values with how the Entra check and the API key work and how to test a credential, what each dashboard panel shows, tenants, the pricing file and how to replace it, every environment variable, running locally, and a troubleshooting table. The README's metrics section shrinks to a summary that links it, so the environment variable table lives in one place. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D8A4vweKZ8kvVx35iDBhzj
The security policy covers supported versions; private reporting through GitHub's "Report a vulnerability" with response aims; exactly what each model request contains (system prompt and rules, prior review rounds with the first 150 characters of the bot's comments, branch names, file paths, numbered diff with 5 lines of context, deleted file paths when enabled) and what it does not; the prompt-injection model and its limits, including marker-tagged threads reaching the history block; every field of the metrics event, including branch names and commented file paths; credential handling; and a hardening checklist. The README's security section now summarises it and links it. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D8A4vweKZ8kvVx35iDBhzj
CONTRIBUTING.md covers the layout, local setup with the CI tool versions, the checks to run per area (including regenerating the parameter reference), pull request expectations, commit style as used in this repository, and the Developer Certificate of Origin. A new "DCO sign-off" CI job runs on pull requests and fails any non-merge commit without a Signed-off-by line for its author's email. Dependabot's and the AI assistant's commits are exempt, since a maintainer reviews and merges them. The README lists the job, links CONTRIBUTING.md and adds docs/ and tools/ to the layout; the changelog records the new documentation. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D8A4vweKZ8kvVx35iDBhzj
docs/assets/pr-review.png shows two PullPicket comment threads on a pull request diff, a WARNING with a suggested fix and a SUGGESTION, in the format the engine posts (severity emoji and word, then the text). It is a rendered illustration of a placeholder repository (contoso-web) and placeholder code, not a capture of a real project. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01D8A4vweKZ8kvVx35iDBhzj
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
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.
Requested by Ziad · project thread
Finishes Phase 7. There is one commit per item.
tools/Update-ParameterReference.ps1generatesdocs/parameters.mdfrom the comments instage-template.yml. The PowerShell CI job runs it with-Checkand fails if the file is stale. PSScriptAnalyzer now also coverstools/. Parameters that had no comment now have one.docs/troubleshooting.mdcovers: the stage skipped on non-PR runs, the identity not in the ADO org or unable to contribute to PRs, 401/403 from the model,foundryTokenResourcefor classic Azure OpenAI, missing or overridden variables, self-hosted pools, and a table of error messages.SECURITY.md: what each model request contains and what it leaves out, the prompt-injection model and its limits, the metrics event fields (including branch names and file paths), credential handling, a hardening checklist, and private reporting.docs/metrics.md: deploy, connecting the pipeline, the fourAUTH_MODEvalues, the dashboard panels, tenants, the pricing file, environment variables, running it locally, and troubleshooting. The README's metrics section is now a summary that links it.CONTRIBUTING.md: setup, checks, commit style and DCO. A new DCO sign-off CI job runs on PRs. Commits by Dependabot and the AI assistant are exempt.docs/assets/pr-review.pngis shown in the README. It is a rendered illustration of a placeholder repo (contoso-web), not a real capture.All README TODO placeholders are resolved, and the CHANGELOG is updated.
Needs you
SECURITY.mdpoints reporters at it.SECURITY.mdaims to acknowledge reports within 5 working days and assess them within 30. Change these if they don't suit you.Finding while writing X3 (not fixed here)
If the service connection's identity can't post to the PR, each comment fails with only a warning. The step then ends green with outcome
no-comments. This is documented, but it may be worth failing the step when every post fails.Testing
ai-code-reviewandtools.Update-ParameterReference.ps1 -Checkpasses, and it fails whendocs/parameters.mdis edited.Generated by Claude Code