Update Guidelines Agent Skill

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.