AI-Assisted Analysis Harness by iRaindrop · Pull Request #386 · cncf/techdocs

iRaindrop · 2026-10-21T20:02:40Z

Provides the directory structure and guidance under .github in the project's doc website repo for conducting an AI-assisted analysis using Copilot GitHub Enterprise.

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

netlify · 2026-10-21T20:02:49Z

✅ Deploy Preview for cncf-techdocs ready!

Name	Link
🔨 Latest commit	`b194e54`
🔍 Latest deploy log	https://app.netlify.com/projects/cncf-techdocs/deploys/6ad98abf33fe9d8f237e8998
😎 Deploy Preview	https://deploy-preview-386--cncf-techdocs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

iRaindrop

Reviewed the harness against the KubeVirt .github folder it was copied from. The structure copied cleanly (all content diffs are Prettier line-wrapping). The comments below cover what is still KubeVirt-specific and what would make the harness complete end-to-end for the next project.

Suggestions not tied to a specific line:

Add a /rank-recommendations prompt that produces input/ai-ranked-recommendations.csv. For KubeVirt this ranking step was ad hoc; codifying it closes the only manual gap in the pipeline.
Reference (or add) the upload process. The issue prompts say "a process will upload" the files, but the harness does not say where that script or workflow lives.
Record the validated toolchain in ai-harness.md: Copilot CLI version, model, and that the prompt files rely on mode: agent and ${input:title}.
Add a pre-flight checklist: required labels exist in the target repo (help wanted, the three priority labels), the project's analysis.md is scaffolded from the techdocs template, and .github has no conflicting prompt files.
Consider an examples/kubevirt/ folder holding the KubeVirt "Current Repository" section and issue template, so the generic files stay generic but a worked example is still available.

iRaindrop · 2026-10-22T01:49:33Z

+title: AI Assisted Analysis Harness
+---
+
+## AI Assisted Analysis Overview


This file is currently only a title and an empty H2. It is the natural home for the end-to-end workflow, which today lives partly in copilot-instructions.md and partly in people's heads:

Copy _github/ to .github/ in the target project repo (note the rename; every prompt references .github/... paths).

Fill in the "Current Repository" section of copilot-instructions.md.

Run the sixteen /<area>-full prompts, then the three /<section>-comment prompts.

Rank the recommendations into input/ai-ranked-recommendations.csv.

Run /create-issues, review, then /create-umbrella-issues.

Upload the issue files and paste outputs into analysis.md per the mapping table.

Moving the process text here would also let copilot-instructions.md stay focused on instructions Copilot needs at run time.

Thank you iRaindrop, how thoughtful of you to think of all these things.

iRaindrop · 2026-10-22T01:49:33Z

+    issues/
+      create-issues.prompt.md           # Generates numbered issue files from ranked recommendations
+      create-umbrella-issues.prompt.md  # Groups issue files into umbrella issues
+  output/


This tree shows per-area outputs at .github/output/ root, but create-issues.prompt.md reads from .github/output/analysis/ and output/readme.md describes analysis/ and issues/ sub-folders. For KubeVirt the files were moved by hand. Suggest making output/analysis/ the canonical location, updating this diagram and the area/section engines to match, and adding .gitkeep (or a readme) in output/analysis/ and output/issues/ so the folders exist after clone.

iRaindrop · 2026-10-22T01:49:33Z

+message, for example
+`run /create-umbrella-issues — merge the analytics and site-ownership umbrellas`.
+
+## Current Repository


This section is still the KubeVirt text verbatim (MkDocs, .nav.yml, yaspeller, kubevirt-doc-issue.md, the label mapping, #343). Since this is the one place the engines read project context from, suggest replacing it with a fill-in template with  placeholders for:

Project name and display name

Main and secondary repositories

Published docs site URL

Issues repository URL (used for repo: in issue front matter)

Issue template file name under issue_template/

CNCF project page URL

Assistance-request issue (cncf/techdocs#NNN)

Priority label mapping (urgent/high/backlog to the repo's actual labels)

Build system and content conventions

The issue prompts can then read these fields instead of hardcoding KubeVirt values (see comments on those files). The KubeVirt version could move to an examples/ folder as a worked example.

iRaindrop · 2026-10-22T01:49:33Z

+Copilot shall output Markdown files from the AI-assisted analysis to the
+`.github/output` directory in the current directory.
+
+### What This Repo Is


Minor: the "Analysis responses style" section earlier in this file says readers are "Kubernetes subject-matter experts" and to "Follow Kubernetes documentation conventions". That is right for KubeVirt but not for every CNCF project; consider parameterizing it from "Current Repository" or softening to "the project's ecosystem".

iRaindrop · 2026-10-22T01:49:33Z

+- `.github/input/ai-ranked-recommendations.csv` — the ranked recommendations.
+  Columns: `Section`, `Area`, `Recommendation`, `Suggested Priority`
+  (`1 - Urgent`, `2 - High`, `3 - Backlog`).
+- `.github/output/analysis/kubevirt-*-recommendations.md` — the per-area


Hardcoded kubevirt- slug. The area engines derive <project-slug> from "Current Repository"; this prompt should do the same, for example .github/output/analysis/<project-slug>-*-recommendations.md.

iRaindrop · 2026-10-22T01:49:34Z

+  work them if it matters. End with this sentence, adapted as needed: "This
+  umbrella issue tracks recommended changes resulting from an analysis of the
+  KubeVirt documentation commissioned by
+  [CNCF](https://www.cncf.io/projects/kubevirt/). The assistance request is


Same as create-issues: the CNCF project URL and the assistance-request issue are KubeVirt-specific and should come from "Current Repository". The title on line 9 ("from the KubeVirt documentation issues") also needs genericizing.

iRaindrop · 2026-10-22T01:49:34Z

+---
+title: { title } #{Issue number}
+labels: [high, help wanted]
+repo: https://github.com/kubevirt/user-guide/issues


Hardcoded KubeVirt repo URL in a template that is meant to be reused. Suggest a placeholder such as {issues repo URL} and have the prompt fill it from "Current Repository".

Separately: once _github is renamed to .github, issue_template/ sits next to GitHub's own ISSUE_TEMPLATE/ convention. On case-insensitive filesystems (macOS default) the two names collide, and on Linux they are easy to confuse. Consider renaming this folder to templates/.

iRaindrop · 2026-10-22T01:49:34Z

+  - Otherwise name it `<project-slug>-<stem>-answers.md`.
+  - If a file exists by the same name, overwrite it.
+
+Output the file to the `.github/output` directory.


Suggest .github/output/analysis here (and in comment, recommendations, and section-comment) so the per-area outputs land where create-issues expects them without a manual move. See the comment on the tree diagram in copilot-instructions.md.

iRaindrop · 2026-10-22T01:49:34Z

@@ -0,0 +1,6 @@
+# About this folder
+
+Use this folder contain two sub-folders for Copilot to place output:


Typo: "Use this folder contain two sub-folders" → "This folder contains two sub-folders". Also, Git does not track empty directories, so analysis/ and issues/ will not exist after clone; add a .gitkeep or a short readme in each.

iRaindrop · 2026-10-22T01:49:34Z

@@ -0,0 +1,4 @@
+# About this folder
+
+Use this folder to place temporary prompt files, spreadsheets, or anything else


Worth documenting the one required input here: ai-ranked-recommendations.csv with columns Section, Area, Recommendation, Suggested Priority (1 - Urgent, 2 - High, 3 - Backlog), since /create-issues depends on it. If a /rank-recommendations prompt is added, note that it produces this file.

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

created basic harness layout

bc3ab22

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

iRaindrop added 3 commits October 21, 2026 13:26

ran prettier

c4d692b

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

added missing H1s

5e33820

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

format edits

785c922

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

iRaindrop commented Oct 22, 2026

View reviewed changes

format fixes

adf6eb7

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

iRaindrop requested a review from nate-double-u October 22, 2026 02:31

trigger build

b194e54

Signed-off-by: Bruce Hamilton <scarlettbernique@gmail.com>

Navigation Menu

Repository navigation

AI-Assisted Analysis Harness - #386

AI-Assisted Analysis Harness#386
iRaindrop wants to merge 6 commits into
cncf:mainfrom
iRaindrop:ai-harness

iRaindrop commented Oct 21, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Oct 21, 2026 •

edited

Loading

Uh oh!

iRaindrop left a comment

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

iRaindrop Oct 22, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

		@@ -0,0 +1,6 @@
		# About this folder

		Use this folder contain two sub-folders for Copilot to place output:

		@@ -0,0 +1,4 @@
		# About this folder

		Use this folder to place temporary prompt files, spreadsheets, or anything else

Conversation

iRaindrop commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify Bot commented Oct 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for cncf-techdocs ready!

Uh oh!

iRaindrop left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

iRaindrop commented Oct 21, 2026 •

edited

Loading

netlify Bot commented Oct 21, 2026 •

edited

Loading