From 4c351023c8b000a680b3568a4bd0e1056556d1e1 Mon Sep 17 00:00:00 2001 From: Trent Blackburn Date: Fri, 28 Aug 2026 18:12:56 -0400 Subject: [PATCH] docs: Fix the AI migration prompt against real consumer builds The migration guide's AI prompt had never been exercised. Running it verbatim against four real public consumer builds (three psake, one Invoke-Build, PowerShellBuild pins from 0.6.1 to 0.8.2) surfaced five defects. None produced a build file that would not parse, but two could silently change build behaviour. - Step 5 told the agent to change "the -Version on `task ... -FromModule PowerShellBuild -Version`". Most real consumers use -MinimumVersion; -Version is an alias for -RequiredVersion, so following the step literally converts a floor into an exact-version requirement. Every psake run flagged this as wrong and had to improvise. The step now says to keep whichever parameter the consumer already uses and change only its value. - Step 5 also drove agents to replace floating pins ('latest') with a hard pin on the unpublished 1.0.0, breaking the consumer's bootstrap immediately where 'latest' would have kept working. It now says to leave floating pins floating and report them. - The baseline step opened with "Before editing anything" but was numbered after the step that applies edits. It is now step 2. - The conventions section said $PSBPreference is "populated in build.ps1". It is set in the psake file's properties block or in .build.ps1; build.ps1 is only a bootstrap wrapper. The inputs section now points at the task file and allows for names like .mymodule.build.ps1. - The completeness self-check only verified the document's tail. One run computed a self-consistent but wrong entry count and still passed it. The check now pairs every Quick Start bullet with its heading, and step 8 uses that list as the reporting checklist. Also adds a non-interactive fallback for the prompt's three "ask me" branches, and corrects the claim about what the prompt was tested against. Re-running the revised prompt against the same consumer confirms each fix: the -MinimumVersion parameter is preserved, the floating pin is left floating with a review marker, and all 18 entries are paired and reported. Refs #159 Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_011GYJrhbrDzqufaeMqD9QjT --- docs/migration-v0.8-to-v1.0.md | 71 +++++++++++++++++++++++----------- 1 file changed, 48 insertions(+), 23 deletions(-) diff --git a/docs/migration-v0.8-to-v1.0.md b/docs/migration-v0.8-to-v1.0.md index af19ce3..56bd099 100644 --- a/docs/migration-v0.8-to-v1.0.md +++ b/docs/migration-v0.8-to-v1.0.md @@ -79,9 +79,13 @@ You are migrating a PowerShellBuild consumer's build configuration from Inputs: - The migration guide, at this exact URL: https://raw.githubusercontent.com/psake/PowerShellBuild/main/docs/migration-v0.8-to-v1.0.md -- My build file (default: ./build.ps1 for psake, or ./.build.ps1 for - Invoke-Build; ask if it lives elsewhere or has a different name). -- Any psake or Invoke-Build files my build file references. +- My build files. The one that matters most is the task file that sets + $PSBPreference: ./psakeFile.ps1 for psake, or ./.build.ps1 for + Invoke-Build -- often named after the module instead, such as + ./.mymodule.build.ps1. There is usually also a ./build.ps1 wrapper + that invokes it. Find the real names rather than assuming the + defaults; ask if you cannot. +- Any other psake or Invoke-Build files those reference. - Any dependency manifest or bootstrap my build file uses to install the toolchain -- requirements.psd1 for PSDepend, or an equivalent. This is where the psake, Pester, and PlatyPS floors are actionable. @@ -90,27 +94,39 @@ Read the guide before anything else: - Fetch the RAW file at the URL above. Do not work from a fetch tool that summarizes pages -- many do, silently, and a summary of this guide drops whole entries while still reading as complete. -- Verify you have the whole document: it ends with a section titled - "Related". If yours does not, you have a partial or summarized copy. - Get the raw text another way, or ask me to paste it. Do not proceed - on a summary. +- Verify you have the whole document two ways: it ends with a section + titled "Related", and every bullet in its "Quick Start" list near the + top has a matching ### heading in the "Migration entries" section. + Pair them up rather than counting them -- a summary can drop a bullet + and its heading together and still look self-consistent. If either + check fails, you have a partial or summarized copy. Get the raw text + another way, or ask me to paste it. Do not proceed on a summary. Task: 1. Read the guide's "Migration entries" section in full. -2. For each entry, decide whether it applies to my files. -3. Apply applicable entries' migration steps. Preserve every - customization not directly affected by the migration. -4. Before editing anything, check which PowerShellBuild version is +2. Before editing anything, check which PowerShellBuild version is installed here, and run my test suite once to get a baseline. After - step 5 the suite may not run at all. + step 5 the suite may not run at all. If it is already failing, say so + and keep going -- record the failure as the baseline. +3. For each entry, decide whether it applies to my files. +4. Apply applicable entries' migration steps. Preserve every + customization not directly affected by the migration. 5. Update the PowerShellBuild version itself. This is the upgrade, and no individual entry covers it: change the pin in my dependency - manifest, and for psake consumers the -Version on - `task -FromModule PowerShellBuild -Version ''`. + manifest, and for psake consumers the version on my + `Task -FromModule PowerShellBuild ...` lines. Keep whichever + version parameter I already use and change only its value. + -MinimumVersion sets a floor; -Version and -RequiredVersion demand an + exact match. They are not interchangeable, so do not swap one for + another -- that changes how psake resolves the module. + If my pin is a floating value such as 'latest', leave it floating and + tell me, rather than converting it to a hard pin on a release that + may not exist yet. Ask me which version to pin if you are unsure what is current. - Make this change even if that version is not published or installed - yet -- a half-migrated pin is worse than one I have to wait on. Add - a review marker saying so rather than leaving the old version. + Otherwise make this change even if that version is not published or + installed yet -- a half-migrated pin is worse than one I have to wait + on. Add a review marker saying so rather than leaving the old + version. 6. Where you cannot safely make a change, leave the original code in place and add a `# MIGRATION-REVIEW: ` comment on the relevant line. Use this when you are unsure how to apply an entry, @@ -125,16 +141,24 @@ Task: to expect on my first 1.0.0 build. MOST entries are this kind -- for a typical consumer only a handful produce a diff. Do not omit them because they produced none, and do not treat a long checklist - as padding. + as padding. Work from the guide's Quick Start list and account for + every bullet on it, including the ones that do not apply to me. - anything you noticed that is not a migration item but changes what I should expect from an entry -- a task that will not run, a setting that has never taken effect. +If you cannot ask me a question because you are running +non-interactively, take the most conservative reading, proceed, and list +every question you would have asked in your output. + PowerShellBuild conventions worth knowing: - The module is imported with `Import-Module PowerShellBuild`. -- Configuration goes through `$PSBPreference`, a hashtable populated in - build.ps1 before tasks are invoked. It is a plain hashtable, so an - unrecognized setting name is silently ignored rather than rejected. +- Configuration goes through `$PSBPreference`. psake consumers set it in + the `properties { }` block of their psake file; Invoke-Build consumers + set it in their .build.ps1 after dot-sourcing the alias. It is rarely + set in build.ps1, which is usually only a bootstrap wrapper. It is a + plain hashtable, so an unrecognized setting name is silently ignored + rather than rejected. - Invoke-Build users dot-source the alias after import: `. PowerShellBuild.IB.Tasks`. - psake users invoke via `-FromModule PowerShellBuild`. @@ -162,8 +186,9 @@ PowerShellBuild conventions worth knowing: build will do differently. An agent that reports only its edits has told you less than half the story. -This prompt has been exercised against sample psake and Invoke-Build -consumers before release. It is not guaranteed to be complete for your +This prompt has been exercised before release against four real public +consumer builds — three psake, one Invoke-Build — spanning PowerShellBuild +pins from 0.6.1 to 0.8.2. It is not guaranteed to be complete for your build file, and the review step is not optional. ## Migration entries