ai-docs-submit

name	ai-docs-submit
description	Submit generated WDK DDI API reference documentation as a PR to the wdk-ddi repo. Use when: submitting docs, creating a PR for DDI docs, pushing documentation changes.
argument-hint	Specify a header name (e.g. soundwireclass) and the path to the CSV file. The output\ subfolder next to the CSV must contain generated docs.

Submit DDI Docs

Submit generated API reference documentation as a pull request to the wdk-ddi Azure DevOps repo using the ADO REST API.

No local repo clone required. Branch creation, file push, and PR creation are all done via the ADO REST API.

Parameters

Parameter	Value
Header Name	Provided by the user (e.g. soundwireclass)
CSV Path	Provided by the user at any local path
Working Directory	Derived from CSV path (parent folder of the CSV file)
Output Directory	{working_dir}\output\
ADO Org	https://dev.azure.com/cpubwin
ADO Project	drivers
Docs Repo	wdk-ddi
Target Branch	main
Source Branch	Auto-generated as {user-alias}/{header}-update (e.g. brbenefield/soundwireclass-update)
User Alias	Auto-detected from CSV Owner column, $env:USERNAME, or az account show

Prerequisites

• The output folder {working_dir}\output\ must contain generated documentation files (from the ai-docs-generate skill).
• Tip: To run all three steps (inventory → generate → submit) with no interaction, use the ai-docs-autopilot skill instead.
• Azure CLI (az) should be available for auth token acquisition. If not, the agent will prompt for an ADO Personal Access Token (PAT) once per session (scope: Code Read+Write, Pull Request Contribute).

Procedure

1. Strip the .h extension from the user-provided header name to get {header} (e.g. soundwireclass.h → soundwireclass).

2. Resolve the user alias for branch naming ({user-alias}). The alias identifies who is submitting the PR, not who owns the APIs. Try these sources in order and use the first non-empty value: a. The Windows username: $env:USERNAME. b. The Azure CLI identity: az account show --query user.name -o tsv, extracting the alias portion before @.

3. Resolve paths. The user provides the CSV path. Derive the working and output directories:

   $csvPath = "{user-provided CSV path}"
   if (-not (Test-Path $csvPath)) {
       Write-Error "CSV not found at $csvPath."
       return
   }
   $workingDir = Split-Path $csvPath -Parent
   $outputDir = Join-Path $workingDir "output"
   $entries = Import-Csv $csvPath
   

   If the CSV does not exist, inform the user and stop. Use the CSV entries to identify the API entities for the commit message and PR description.

4. Verify the output directory exists and contains files:

   $outputFiles = Get-ChildItem -Path $outputDir -Filter "*.md" -ErrorAction SilentlyContinue
   if (-not $outputFiles -or $outputFiles.Count -eq 0) {
       Write-Error "No generated docs found in $outputDir. Run ai-docs-generate first."
       return
   }
   

5. Obtain ADO auth token. Try Azure CLI first, then fall back to prompting for a PAT:

   try {
       $token = (az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv 2>$null)
       if (-not $token) { throw "No token" }
       $headers = @{ Authorization = "Bearer $token"; "Content-Type" = "application/json" }
   } catch {
       $pat = Read-Host "Enter ADO PAT (scope: Code Read+Write, PR Contribute)"
       $base64 = [Convert]::ToBase64String([Text.Encoding]::ASCII.GetBytes(":$pat"))
       $headers = @{ Authorization = "Basic $base64"; "Content-Type" = "application/json" }
   }
   $adoBase = "https://dev.azure.com/cpubwin/drivers/_apis/git/repositories"
   

6. Get the latest commit SHA on main. This is required as the oldObjectId for the push:

   $refs = Invoke-RestMethod -Uri "$adoBase/wdk-ddi/refs?filter=heads/main&api-version=7.0" -Headers $headers
   $mainSha = $refs.value[0].objectId