ai-docs-inventory

Inventory Header

Read a pre-provided CSV of target API filenames, cross-reference each entry against existing docs, stubs, and published content via the ADO REST API, classify their status, and finalize the CSV for use with the ai-docs-generate skill.

No local repo clones required. All repo interactions use the Azure DevOps REST API.

Parameters

Prerequisites

• The user provides a header name and a path to a CSV file. That is the only user requirement.
• 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.

File Naming Conventions

Map each API entity to a filename using these prefixes:

The filename pattern is: {prefix}-{header}-{api_name_lowercase}.md

Where {header} is the header name without the .h extension.

Header Landing Page

On the stubs branch, the header landing page is always named na-{header}.md. When it is copied to wdk-ddi-src/content/{header}/ on the main branch, it is renamed to index.md. In the published docs repo, it also appears as index.md. When cross-referencing, check for na-{header}.md on the stubs branch and index.md on main and in the published docs repo.

Legacy Filename Exceptions

Some existing files in the published docs repo or on main may have non-standard filenames (e.g. an extra underscore like ns-header-_struct_name.md instead of ns-header-struct_name.md). These are historical naming errors. Do not rename existing files — doing so would break published links. When cross-referencing, also check for these variant filenames. For new APIs, always use the approved naming convention.

Execution Strategy

Write all PowerShell logic into a single self-contained .ps1 script file, then execute it in one terminal call. Do NOT run ADO REST calls or variable assignments as separate interactive terminal commands — PowerShell variables are lost between terminal invocations and long-running commands may time out and get moved to the background, breaking the workflow.

The pattern is:

1. Create a script file at {workingDir}\inventory.ps1 containing all the logic from the Procedure below.
2. Execute it in a single terminal call: powershell -ExecutionPolicy Bypass -File "{workingDir}\inventory.ps1"
3. Parse the script's console output to present results to the user.

The script should accept no parameters — hardcode the {header}, {csvPath}, and {workingDir} values directly into the generated script.

Procedure

Write a single inventory.ps1 script that performs all of the following steps, then execute it.

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

2. Resolve paths. The user provides a CSV path. Derive the working directory from it. The script should validate the CSV exists and read it:

   $ErrorActionPreference = "Stop"
   $header = "{header}"
   $csvPath = "{user-provided CSV path}"
   $workingDir = Split-Path $csvPath -Parent
   
   if (-not (Test-Path $csvPath)) {
       Write-Error "CSV not found at $csvPath."
       exit 1
   }
   

   Read the CSV:

   $csvData = Import-Csv $csvPath
   

   The CSV has a header row. Look for a column containing file paths (commonly FilePath or filename) with values like wdk-ddi-src/content/{header}/{filename}.md. Filter to rows with valid .md paths.

3. Obtain ADO auth token. Try Azure CLI first, then fail with a clear message (PAT prompting cannot work inside a non-interactive script):

   $token = (az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query accessToken -o tsv 2>$null)
   if (-not $token) {
       Write-Error "Failed to get ADO token. Run 'az login' first, or set `$env:ADO_PAT before running."
       exit 1
   }
   $h = @{ Authorization = "Bearer $token" }
   $adoBase = "https://dev.azure.com/cpubwin/drivers/_apis/git/repositories"
   

4. For each entry in the CSV, extract the target filename from the path (e.g. wdk-ddi-src/content/{header}/nf-soundwireclass-somefunc.md → nf-soundwireclass-somefunc.md).

5. List all files in the directory on each branch (one API call per branch, not per file). This detects legacy filename variants (see Legacy Filename Exceptions):

   # List files on main branch of wdk-ddi
   try {
       $r1 = Invoke-RestMethod -Uri "$adoBase/wdk-ddi/items?scopePath=wdk-ddi-src/content/{header}/&recursionLevel=OneLevel&versionDescriptor.version=main&versionDescriptor.versionType=branch&api-version=7.0" -Headers $h
       $mainFiles = @($r1.value | Where-Object { $_.path -like "*.md" } | ForEach-Object { Split-Path $_.path -Leaf })
   } catch { $mainFiles = @() }
   
   # List files on stubs branch of wdk-ddi
   try {
       $r2 = Invoke-RestMethod -Uri "$adoBase/wdk-ddi/items?scopePath=wdk-ddi-src/content/{header}/&recursionLevel=OneLevel&versionDescriptor.version=stubs/main&versionDescriptor.versionType=branch&api-version=7.0" -Headers $h
       $stubFiles = @($r2.value | Where-Object { $_.path -like "*.md" } | ForEach-Object { Split-Path $_.path -Leaf })
   } catch { $stubFiles = @() }
   
   # List files on live branch of wdk-ddi-build (published docs)
   try {
       $r3 = Invoke-RestMethod -Uri "$adoBase/wdk-ddi-build/items?scopePath=wdk-ddi-src/content/{header}/&recursionLevel=OneLevel&versionDescriptor.version=live&versionDescriptor.versionType=branch&api-version=7.0" -Headers $h
       $pubFiles = @($r3.value | Where-Object { $_.path -like "*.md" } | ForEach-Object { Split-Path $_.path -Leaf })
   } catch { $pubFiles = @() }
   
   Write-Host "Main: $($mainFiles.Count) files, Stubs: $($stubFiles.Count) files, Published: $($pubFiles.Count) files"
   

   Compare each expected filename against the directory listings. If a file exists with a minor variant (e.g. ns-header-_struct_name.md instead of ns-header-struct_name.md), treat it as a match — the doc exists under the legacy name. Use the legacy filename in the CSV (do not rename it).

   a. Check if the file exists on main of wdk-ddi (look for the filename in $mainFiles).

   b. Check if a stub exists on the stubs branch (look for the filename in $stubFiles).

   c. Check if the file exists on live of the published docs repo wdk-ddi-build (look for the filename in $pubFiles).

6. Classify each API into one of three categories:

   • new: Stub exists on stubs/main but no completed doc on main
   • update: File already exists on main — needs to be compared with the latest stub to identify changes
   • stub not found: No stub and no existing doc

7. Output grouped results to the console for the agent to parse and present:

   === New (ready to document) ===
   nf-soundwireclass-somefunc.md          (function)
   ns-soundwireclass-some_struct.md       (structure)
   
   === Update (existing doc, needs diff) ===
   nf-soundwireclass-otherfunc.md         (function)  [+2 params, -1 param, ~1 param]
   
   === Stub not found ===
   ne-soundwireclass-some_enum.md         (enumeration)
   

8. Diff existing docs against stubs. For each "update" entry, fetch the existing doc from main and the latest stub from stubs/main via the ADO REST API. Compare the parameter/field/value sections to identify:

   • Added parameters, fields, or enum values (present in stub but not in existing doc)
   • Removed parameters, fields, or enum values (present in existing doc but not in stub)
   • Modified parameters, fields, or enum values (present in both but with different types or descriptions)

   Output a per-file change summary (e.g. [+2 params, -1 param, ~1 param]) in the console results.

9. Write the updated CSV at the original CSV path. The format must be compatible with the ai-docs-generate skill:

   filename,status
   wdk-ddi-src/content/{header}/{filename1}.md,new
   wdk-ddi-src/content/{header}/{filename2}.md,update
   

   The script writes both "new" and "update" entries. "Stub not found" entries are excluded.

10. Output a summary to the console:

    • Number of APIs in the CSV by type
    • Number selected for documentation
    • Working directory: {workingDir}
    • CSV file location: {csvPath}

After the script finishes, the agent should:

11. Open the CSV in the editor:

    code $csvPath
    

12. Continue or stop. Ask the user:

    Inventory complete. Press y to continue to generate API docs, or type n to stop.

    • If the user types y: automatically invoke the ai-docs-generate skill, passing the same header name and CSV path. Behave as if the user typed /ai-docs-generate {header}.h {workingDir}.
    • If the user types n: stop and tell them they can run it later with: /ai-docs-generate {header}.h {workingDir}

    Tip: To run all three steps (inventory → generate → submit) with no interaction, use the ai-docs-autopilot skill instead.