diff --git a/.github/skills/tiny-ps-chapter-test-loop/SKILL.md b/.github/skills/tiny-ps-chapter-test-loop/SKILL.md new file mode 100644 index 0000000..dbe0c41 --- /dev/null +++ b/.github/skills/tiny-ps-chapter-test-loop/SKILL.md @@ -0,0 +1,20 @@ +--- +name: tiny-ps-chapter-test-loop +description: Use when changing a single Tiny PowerShell Projects chapter and you need the expected chapter-first, repo-second validation flow. +--- + +# Tiny PowerShell Chapter Test Loop + +## When to use +- You are editing one numbered chapter directory. +- You need to validate a `solution*.ps1`, chapter script, or test change without losing the repo-wide regression context. + +## Workflow +1. Work inside the target chapter directory and keep the expected script name and `solution*.ps1` pattern intact. +2. Run that chapter's `./AllTest.ps1` first so Pester exercises the local `solution*.ps1` loop exactly the way the repo expects. +3. After the chapter-level checks pass, run `pwsh -NoLogo -NoProfile -File ./RunAllTests.ps1` from the repository root to look for regressions outside the chapter. +4. Treat pre-existing failures separately from the change you are making; only fix them when they are directly caused by your edit. + +## Output +- The changed chapter passes its local `AllTest.ps1` run. +- The root regression run shows no new failures caused by the change. diff --git a/.github/skills/tiny-ps-deterministic-random/SKILL.md b/.github/skills/tiny-ps-deterministic-random/SKILL.md new file mode 100644 index 0000000..a2fdca7 --- /dev/null +++ b/.github/skills/tiny-ps-deterministic-random/SKILL.md @@ -0,0 +1,20 @@ +--- +name: tiny-ps-deterministic-random +description: Use when a Tiny PowerShell Projects chapter depends on randomness and tests or examples need stable seeded output. +--- + +# Tiny PowerShell Deterministic Random + +## When to use +- The script calls `Get-Random` or `[Random]::new(...)`. +- README examples or Pester tests need the same output for the same seed. + +## Workflow +1. Add or preserve a seed parameter that matches the chapter's existing command-line contract. +2. Initialize randomness once near the start of execution with `Get-Random -SetSeed` or a single `[Random]` instance. +3. Keep the order and number of random calls stable so seeded runs stay reproducible. +4. Add or update tests that assert exact output for representative seed values and option combinations. + +## Output +- Re-running the script with the same seed produces the same result. +- Pester assertions can lock down the seeded behavior without flakiness. diff --git a/.github/skills/tiny-ps-input-normalization/SKILL.md b/.github/skills/tiny-ps-input-normalization/SKILL.md new file mode 100644 index 0000000..9be9401 --- /dev/null +++ b/.github/skills/tiny-ps-input-normalization/SKILL.md @@ -0,0 +1,20 @@ +--- +name: tiny-ps-input-normalization +description: Use when a Tiny PowerShell Projects script accepts either literal text or a file path and must normalize input consistently. +--- + +# Tiny PowerShell Input Normalization + +## When to use +- A parameter may be literal text, a path to a file, or a list of files. +- Tests exercise both direct input and file-backed input paths. + +## Workflow +1. Decide the chapter's intended input contract before changing parameter names or types. +2. Detect file-backed input with `Test-Path` only where the chapter expects that behavior. +3. Read file content in the narrowest way that preserves expected output, such as `Get-Content -Raw` when newline structure matters. +4. Keep literal text input working unchanged, and add or update tests for both literal and file-based cases. + +## Output +- The script handles direct text and file input consistently with the chapter tests. +- Input normalization changes do not alter unrelated output formatting. diff --git a/.github/skills/tiny-ps-regex-text-transform/SKILL.md b/.github/skills/tiny-ps-regex-text-transform/SKILL.md new file mode 100644 index 0000000..53d9884 --- /dev/null +++ b/.github/skills/tiny-ps-regex-text-transform/SKILL.md @@ -0,0 +1,20 @@ +--- +name: tiny-ps-regex-text-transform +description: Use when implementing or changing the repo's recurring regex-based text transformation chapters. +--- + +# Tiny PowerShell Regex Text Transform + +## When to use +- The chapter modifies words or characters using pattern matching. +- Output must preserve punctuation, word boundaries, or character case. + +## Workflow +1. Start from the smallest regex that matches only the text you intend to transform. +2. Preserve surrounding punctuation and spacing by splitting or replacing only the matched spans. +3. Use a scriptblock evaluator when replacement logic depends on the matched text, such as preserving uppercase vowels. +4. Add or update tests that cover representative words, punctuation, case handling, and any file-input path the chapter already supports. + +## Output +- The transform changes only the intended matches. +- Existing punctuation, spacing, and case-sensitive expectations remain covered by tests. diff --git a/AI_WORKFLOW_SHORTLIST.md b/AI_WORKFLOW_SHORTLIST.md new file mode 100644 index 0000000..16c8fac --- /dev/null +++ b/AI_WORKFLOW_SHORTLIST.md @@ -0,0 +1,19 @@ +# AI Workflow Packaging Shortlist + +| Repeated workflow | Supporting evidence from the repo | Frequency / confidence | Recommended form | Why create or skip | +| --- | --- | --- | --- | --- | +| Iterate on one chapter, then run broader regression | `AllTest.ps1` exists in every numbered chapter; `RunAllTests.ps1` loops all numbered chapters; `README.md` explains both flows and recommends rerunning tests after every change | 22 chapters / High | Skill/playbook | Worth packaging because the chapter-first, repo-second validation order is stable, repeated, and easy to follow incorrectly without a checklist | +| Add deterministic random behavior that Pester can lock down | Seeded randomness appears in `09_abuse/abuse.ps1`, `10_telephone/telephone.ps1`, `12_ransom/ransom.ps1`, `16_scrambler/scrambler.ps1`, `19_wod/solution1.ps1`, and `20_password/password.ps1` | 6+ chapters / High | Skill/playbook | Worth packaging because reproducible randomness is repeated, test-sensitive, and error-prone when the seed is set in the wrong place | +| Normalize arguments that can be either literal text or a file path | File-or-text handling appears in `05_howler/howler.ps1`, `08_apples_and_bananas/apples.ps1`, `10_telephone/telephone.ps1`, `12_ransom/ransom.ps1`, and `15_kentucky_friar/friar.ps1` | 5+ chapters / High | Skill/playbook | Worth packaging because the input contract recurs and benefits from a consistent sequence of checks and validations | +| Build text transforms with regex while preserving punctuation and case | Regex-driven transforms appear in `08_apples_and_bananas/apples.ps1`, `14_rhymer/rhymer.ps1`, `15_kentucky_friar/friar.ps1`, `16_scrambler/scrambler.ps1`, and `17_mad_libs/mad.ps1` | 5+ chapters / High | Skill/playbook | Worth packaging because the same design pattern recurs across multiple chapters with stable inputs and outputs | +| Add release or changelog automation | No release workflow, changelog process, or release docs were found in the repo structure, issues, or discussions | Low / Low | Skip | Not enough maintainer evidence to justify adding publishing automation | +| Scaffold the same AI skill across multiple harness formats | Recent issues `#12`, `#14`, `#16`, `#18`, and `#20` plus related open PRs show repeated interest in AI skill authoring, but this branch has no established `.agents` or `.claude` layout yet | Recent activity / Medium | Skip for now | Likely useful, but overlapping solutions are already being explored in other open PRs, so duplicating that work here would be speculative | + +## Created on this branch + +- `.github/skills/tiny-ps-chapter-test-loop/SKILL.md` +- `.github/skills/tiny-ps-deterministic-random/SKILL.md` +- `.github/skills/tiny-ps-input-normalization/SKILL.md` +- `.github/skills/tiny-ps-regex-text-transform/SKILL.md` + +These are the highest-confidence missing items because they are repo-specific, repeated across many chapters, and narrow enough to validate by inspection against the current chapter structure, tests, and README guidance.