| name | update-guidelines |
| description | Ingest guideline changes from the azure-sdk repo into the knowledge base. Use for: update guidelines, ingest guidelines, sync guidelines, guideline changes, kb update, update KB, guideline ingestion, sync KB, guideline PR, guideline diff. |
| argument-hint | PR link, two SHAs, or two dates (e.g. 'PR #1234', 'abc123..def456', 'April 1 to April 30') |
Update Guidelines
When to Use
- Syncing guideline changes from the Azure/azure-sdk repo into the Copilot knowledge base
- Ingesting a specific PR's guideline changes
- Syncing guideline changes between two dates or two commit SHAs
Overview
The avc db ingest-guidelines command detects changes in the azure-sdk repo's guideline markdown files and syncs them to Cosmos DB. It compares a base SHA against a target SHA to find changed files, parses them, and upserts/deletes guidelines, examples, and memories accordingly.
This skill supports three input scenarios for resolving the base and target SHAs:
- PR link — Extract SHAs from a GitHub pull request
- Explicit SHAs — Use the SHAs directly
- Date range — Find the closest commits on
main to the given dates
IMPORTANT: Always run a dry-run first and confirm with the user before applying changes.
Environment
The user MUST specify which environment to update: staging or production. If not specified, ask the user — do NOT assume. This determines which Cosmos DB and App Configuration instance is modified.
Always pass --environment <env> to the CLI commands.
Language Filter
The user may optionally specify one or more languages to narrow the ingestion scope. If languages are specified, only guideline files for those languages (plus cross-language "general" guidelines) are processed.
Pass --language <lang1> <lang2> (or -l <lang1> <lang2>) to the CLI commands. Valid language names: python, java, dotnet, typescript, golang, cpp, rust, ios, android, clang. Case-insensitive aliases like C#, Go, Swift are also accepted.
If the user does not mention specific languages, omit the flag to process all languages.
Scenario 1: PR Link
The user provides a GitHub PR link (e.g. https://github.com/Azure/azure-sdk/pull/1234).
Step 1a: Extract the PR number
Parse the PR number from the URL.
Step 1b: Fetch PR details from GitHub API
Run this command to get the base and merge commit SHAs:
Invoke-RestMethod -Uri "https://api.github.com/repos/Azure/azure-sdk/pulls/<PR_NUMBER>" -Headers @{ "User-Agent" = "apiview-copilot" } | Select-Object -Property @{N='base_sha';E={$_.base.sha}}, @{N='merge_commit_sha';E={$_.merge_commit_sha}}, @{N='title';E={$_.title}}, @{N='state';E={$_.state}}, @{N='merged';E={$_.merged}} | Format-List
- Use
base.sha as the base SHA
- Use
merge_commit_sha as the target SHA
- If
merged is false, warn the user that the PR is not merged and the merge commit SHA may change
Step 1c: Confirm with user
Show the user:
- PR title and state
- Base SHA (first 8 chars)
- Target SHA (first 8 chars)
- Environment (staging or production)
Ask for confirmation before proceeding.
Then go to Phase 2: Dry Run.
Scenario 2: Explicit SHAs
The user provides two commit SHAs directly.
Confirm with the user:
- Base SHA (first 8 chars)
- Target SHA (first 8 chars)
- Environment (staging or production)
Then go to Phase 2: Dry Run.
Scenario 3: Date Range
The user provides two dates (e.g. "April 1 to April 30", "March 15 and March 20").
Step 3a: Resolve dates to SHAs
For each date, find the closest commit on main of the Azure/azure-sdk repo.
Use the GitHub Commits API with the until parameter to find the most recent commit on or before the given date:
For the base date:
(Invoke-RestMethod -Uri "https://api.github.com/repos/Azure/azure-sdk/commits?sha=main&until=<BASE_DATE>T23:59:59Z&per_page=1" -Headers @{ "User-Agent" = "apiview-copilot" })[0] | Select-Object -Property @{N='sha';E={$_.sha}}, @{N='date';E={$_.commit.committer.date}}, @{N='message';E={$_.commit.message.Split("`n")[0]}} | Format-List
For the target date:
(Invoke-RestMethod -Uri "https://api.github.com/repos/Azure/azure-sdk/commits?sha=main&until=<TARGET_DATE>T23:59:59Z&per_page=1" -Headers @{ "User-Agent" = "apiview-copilot" })[0] | Select-Object -Property @{N='sha';E={$_.sha}}, @{N='date';E={$_.commit.committer.date}}, @{N='message';E={$_.commit.message.Split("`n")[0]}} | Format-List
Replace <BASE_DATE> and <TARGET_DATE> with ISO dates (e.g. 2025-04-15).
Step 3b: Confirm with user
The resolved commit dates may not exactly match the user's requested dates. Always show the user what was resolved and ask for confirmation, especially if the commit date differs from the requested date by more than a day.
Show:
- Requested base date → Resolved commit date and SHA (first 8 chars) and commit message
- Requested target date → Resolved commit date and SHA (first 8 chars) and commit message
- Environment (staging or production)
Ask: "These are the closest commits to your requested dates. Proceed with dry run?"
Then go to Phase 2: Dry Run.
Phase 2: Dry Run
Always run a dry-run first. Use a 300-second timeout (the command can be slow due to LLM enrichment).
python cli.py db ingest-guidelines --environment <ENV> --base-sha <BASE_SHA> --target-sha <TARGET_SHA> --details [--language <LANG1> <LANG2>]
Include --language flags only if the user specified languages to filter.
Interpreting results
Read the terminal output. The command prints:
- Guidelines: N to create, N to update, N to delete, N unchanged
- Examples: N to create, N to update, N to delete, N unchanged
- Memories: N to absorb, N to retain
- Errors: any errors encountered
With --details, the JSON output includes before/after content for each change.
Present to user
Summarize what the dry run found:
- How many guidelines will be created/updated/deleted
- How many examples will be created/updated/deleted
- How many memories will be absorbed
- Any errors
- Remind them which environment this targets
Ask: "Ready to apply these changes to {environment}?"
Phase 3: Apply
Only after the user confirms the dry-run results, run the actual ingestion:
python cli.py db ingest-guidelines --environment <ENV> --base-sha <BASE_SHA> --target-sha <TARGET_SHA> --apply [--language <LANG1> <LANG2>]
Use a 300-second timeout. Include the same --language flags used in the dry run.
After completion, report the final counts to the user.
Gotchas
- Always dry-run first. Never skip the dry run. The ingestion modifies Cosmos DB and App Configuration.
- Environment matters. Staging and production have separate Cosmos DB instances. Double-check with the user.
- Large diffs are slow. If many files changed, the LLM enrichment step can take several minutes. Use
--details only on dry runs to inspect changes; omit it on the real run to save time.
- Language filter. Use
--language to scope to specific languages when debugging or testing. The filter also includes cross-language ("general") guidelines automatically.
- Merged PRs only. If a PR is not yet merged, the merge commit SHA is provisional and may change. Warn the user.
