From ea0ab9114ad5aee837a836dfb7280aea6bb450c2 Mon Sep 17 00:00:00 2001 From: Giuseppe Crescimanno Date: Sat, 27 Jun 2026 14:44:07 +0200 Subject: [PATCH] Add skill reasoning frameworks --- sysadmin-windows-startup-performance/SKILL.md | 14 +-- .../references/analysis-framework.md | 43 +++++++++ sysadmin-windows-startup-remediation/SKILL.md | 20 +++-- .../examples/remediation-cases.md | 87 +++++++++++++++++++ .../references/decision-framework.md | 53 +++++++++++ 5 files changed, 203 insertions(+), 14 deletions(-) create mode 100644 sysadmin-windows-startup-performance/references/analysis-framework.md create mode 100644 sysadmin-windows-startup-remediation/examples/remediation-cases.md create mode 100644 sysadmin-windows-startup-remediation/references/decision-framework.md diff --git a/sysadmin-windows-startup-performance/SKILL.md b/sysadmin-windows-startup-performance/SKILL.md index 430a74d..ee093bc 100644 --- a/sysadmin-windows-startup-performance/SKILL.md +++ b/sysadmin-windows-startup-performance/SKILL.md @@ -1,6 +1,6 @@ --- name: sysadmin-windows-startup-performance -description: Collect and analyze read-only Windows startup performance baselines. Use when an agent or automation harness is asked to investigate slow Windows boot, sign-in, login delay, startup apps, registry Run keys, Startup folder items, scheduled tasks, services, Diagnostics-Performance event IDs 100-110, boot warnings, resource pressure, or produce evidence-based recommendations without changing system configuration. +description: Collect and analyze read-only Windows startup performance baselines, producing sanitized JSON baselines and Markdown analysis reports. Use when an agent or automation harness is asked to investigate slow Windows boot, sign-in, login delay, startup apps, registry Run keys, Startup folder items, scheduled tasks, services, Diagnostics-Performance event IDs 100-110, boot warnings, resource pressure, or evidence-based recommendations without changing system configuration. --- # Sysadmin Windows Startup Performance @@ -13,6 +13,7 @@ Use this skill for read-only Windows startup diagnostics. It collects sanitized - `scripts/collect-startup-baseline.ps1`: elevated read-only collector for Diagnostics-Performance events, startup inventory, service/task signals, resources, and recent boot warnings. - `scripts/analyze-startup-baseline.ps1`: analyzer that ranks findings and writes a Markdown report. +- `references/analysis-framework.md`: reasoning principles, confidence levels, recommendation quality, and edge cases for interpreting baselines. - `references/data-model.md`: baseline and analysis schema notes. - `references/safety.md`: operating rules and remediation boundaries. - `examples/synthetic-baseline.json`: synthetic fixture for analyzer validation. @@ -22,11 +23,12 @@ Use this skill for read-only Windows startup diagnostics. It collects sanitized ## Workflow 1. Read `references/safety.md` before collecting data or recommending changes. -2. Create or use a local hub folder with `scripts/`, `state/`, `reports/`, and `logs/`. A template is available at `templates/local-performance/` when this repository is installed as a project. -3. Run the collector from an elevated PowerShell session. Do not fall back to non-admin collection because protected boot timing logs can be missed. -4. Run the analyzer on the latest or specified baseline. -5. Prefer at least three comparable post-reboot baselines before recommending startup changes. -6. If the user asks for remediation, produce a dry-run plan with rollback notes first. Do not mutate startup apps, registry entries, scheduled tasks, services, drivers, security tools, or Windows settings without explicit approval. +2. Read `references/analysis-framework.md` before interpreting findings or writing recommendations. +3. Create or use a local hub folder with `scripts/`, `state/`, `reports/`, and `logs/`. A template is available at `templates/local-performance/` when this repository is installed as a project. +4. Run the collector from an elevated PowerShell session. Do not fall back to non-admin collection because protected boot timing logs can be missed. +5. Run the analyzer on the latest or specified baseline. +6. Prefer at least three comparable post-reboot baselines before recommending startup changes. +7. If the user asks for remediation, produce a dry-run plan with rollback notes first. Do not mutate startup apps, registry entries, scheduled tasks, services, drivers, security tools, or Windows settings without explicit approval. ## Commands diff --git a/sysadmin-windows-startup-performance/references/analysis-framework.md b/sysadmin-windows-startup-performance/references/analysis-framework.md new file mode 100644 index 0000000..d87fcfb --- /dev/null +++ b/sysadmin-windows-startup-performance/references/analysis-framework.md @@ -0,0 +1,43 @@ +# Analysis Framework + +Use this reference when turning startup baseline data into findings or recommendations. + +## Reasoning Principles + +- Separate measurement from remediation. A finding can say what looks suspicious without saying it should be disabled. +- Prefer repeated evidence over a single observation. One boot can identify what to measure next; recurring patterns justify stronger recommendations. +- Rank by user-visible startup impact first, then by confidence, then by reversibility. +- Treat missing or partial data as a confidence limit, not as proof that no issue exists. +- Explain whether the evidence points to boot, sign-in, post-login startup, or general resource pressure. + +## Confidence Levels + +- `high`: repeated across comparable baselines, clear component identity, and direct timing or resource evidence. +- `medium`: plausible component identity and one strong signal, or repeated weak signals. +- `low`: weak, indirect, stale, or context-dependent evidence. +- `info`: useful measurement context, inventory, or next data to collect. + +## Recommendation Quality + +Good recommendations: + +- name the exact component or artifact +- cite the baseline signal that caused the finding +- state the confidence level +- distinguish investigation, measurement, and remediation +- avoid changing Microsoft, security, driver, backup, disk, sync-critical, or update components by default + +Avoid recommendations that: + +- infer causality from one baseline without saying so +- suggest disabling services or tasks without rollback context +- treat high process CPU after login as proof of boot delay +- mention command-line details that were not explicitly collected + +## Edge Cases + +- Thin baseline history: recommend collecting more baselines before persistent changes. +- Long uptime: note that current process/resource data may not represent startup. +- Disabled item still appears: report it as inventory, not an active startup cost. +- Update or installer activity: identify it as potentially transient unless repeated. +- Hardware/vendor utilities: treat performance cost and device-control value as separate considerations. diff --git a/sysadmin-windows-startup-remediation/SKILL.md b/sysadmin-windows-startup-remediation/SKILL.md index 8421694..a3b5cb8 100644 --- a/sysadmin-windows-startup-remediation/SKILL.md +++ b/sysadmin-windows-startup-remediation/SKILL.md @@ -1,6 +1,6 @@ --- name: sysadmin-windows-startup-remediation -description: Plan and apply approved, reversible Windows startup remediation from prior analysis. Use when an agent or automation harness is asked to act on startup findings, disable or reconfigure autostart entries, registry Run keys, Startup folder items, Task Scheduler logon or startup tasks, auto-start services, vendor launchers or updaters, prepare rollback, vet uninstall tools, write change records, or verify post-change startup behavior with explicit approval. +description: Plan and apply approved, reversible Windows startup remediation, producing dry-run remediation plans and change records from prior analysis. Use when an agent or automation harness is asked to act on startup findings, disable or reconfigure autostart entries, registry Run keys, Startup folder items, Task Scheduler logon or startup tasks, auto-start services, vendor launchers or updaters, prepare rollback, vet uninstall tools, or verify post-change startup behavior with explicit approval. --- # Sysadmin Windows Startup Remediation @@ -12,7 +12,9 @@ Use this skill after Windows startup performance analysis identifies candidates ## Files - `references/safety.md`: approval, rollback, and stop rules. +- `references/decision-framework.md`: target classification, action preference, approval quality, and stop conditions. - `references/target-types.md`: supported Windows startup target types and preferred actions. +- `examples/remediation-cases.md`: synthetic examples for safe candidates, stop-and-ask cases, unknown targets, uninstall guidance, and disabled residue. - `templates/remediation-plan.md`: dry-run plan template to prepare before changes. - `templates/change-record.md`: execution and verification record template. - `reports/`: generated remediation plans and human-readable records. @@ -23,13 +25,15 @@ Use this skill after Windows startup performance analysis identifies candidates 1. Start from evidence: use a startup analysis JSON or report, preferably from the [`sysadmin-windows-startup-performance`](https://github.com/KarmCraft/skills-library/tree/main/sysadmin-windows-startup-performance) skill. If no analysis exists, ask to collect/read one first. 2. Read `references/safety.md` before proposing or applying changes. -3. Read `references/target-types.md` for target-specific action and rollback patterns. -4. Produce a dry-run plan using `templates/remediation-plan.md`; include exact target identity, evidence, proposed action, risk, expected effect, elevation needs, and rollback. -5. Ask for explicit approval for each target or clearly named group of identical low-risk targets. Do not treat general optimization intent as approval. -6. Before applying a change, capture current state needed for rollback and write/update a local record under `state/` or `reports/`. -7. Apply the least invasive reversible action. Prefer supported product settings or Windows-supported enable/disable operations over deleting registry values or files. -8. Verify immediately where possible, then recommend a reboot and a fresh performance baseline to measure effect. -9. Write a change record using `templates/change-record.md` with what changed, commands or manual steps used, verification result, and rollback path. +3. Read `references/decision-framework.md` before classifying targets or asking for approval. +4. Read `references/target-types.md` for target-specific action and rollback patterns. +5. Use `examples/remediation-cases.md` when a target resembles a common safe, risky, unknown, uninstall, or residue case. +6. Produce a dry-run plan using `templates/remediation-plan.md`; include exact target identity, evidence, proposed action, risk, expected effect, elevation needs, and rollback. +7. Ask for explicit approval for each target or clearly named group of identical low-risk targets. Do not treat general optimization intent as approval. +8. Before applying a change, capture current state needed for rollback and write/update a local record under `state/` or `reports/`. +9. Apply the least invasive reversible action. Prefer supported product settings or Windows-supported enable/disable operations over deleting registry values or files. +10. Verify immediately where possible, then recommend a reboot and a fresh performance baseline to measure effect. +11. Write a change record using `templates/change-record.md` with what changed, commands or manual steps used, verification result, and rollback path. ## Operating Rules diff --git a/sysadmin-windows-startup-remediation/examples/remediation-cases.md b/sysadmin-windows-startup-remediation/examples/remediation-cases.md new file mode 100644 index 0000000..ffc7c71 --- /dev/null +++ b/sysadmin-windows-startup-remediation/examples/remediation-cases.md @@ -0,0 +1,87 @@ +# Remediation Cases + +Use these examples as patterns for evaluating startup findings. They are synthetic and intentionally vendor-neutral. + +## Clearly Nonessential Logon Task + +Input finding: + +- target: `\Vendor\PromoTray` +- type: scheduled logon task +- evidence: appears in multiple baselines, launches a tray promotion helper, no hardware/security role + +Reasoning: + +- classify as `nonessential` +- proposed action can be `Disable-ScheduledTask` +- capture task path, name, enabled state, triggers, actions, settings, and XML export +- ask approval for this exact task before changing it + +Output stance: safe candidate for an approved reversible disable. + +## Hardware Control Service + +Input finding: + +- target: `VendorDeviceControlService` +- type: auto-start service +- evidence: automatic service, controls keyboard lighting and fan profiles + +Reasoning: + +- classify as `workflow-dependent` +- device behavior may change if disabled +- prefer vendor startup settings or leave unchanged unless the user accepts the tradeoff +- do not disable based only on startup cost + +Output stance: stop and ask how the user uses the device utility. + +## Unknown Publisher Run Entry + +Input finding: + +- target: `Helper` +- type: registry Run entry +- evidence: command points to a user profile executable with unclear publisher + +Reasoning: + +- classify as `unknown` +- inspect signature, file location, publisher, install context, and user intent first +- do not delete the registry value +- if later approved, move to a rollback-safe holding key instead of removing + +Output stance: identity investigation before remediation. + +## Missing Uninstall Entry + +Input finding: + +- target: `LegacyVendorSuite` +- type: installed application remnants +- evidence: services and folders remain, but Apps and Features has no entry + +Reasoning: + +- uninstall is not the default startup remediation path +- first look for the vendor's official cleanup tool, installer maintenance mode, or support article +- third-party removers require strong trust rationale and explicit approval before download and execution +- record source URL, publisher, signature or hash when available, expected scope, and rollback limitations + +Output stance: provide vetted uninstall guidance only after source verification. + +## Disabled Item Still Present + +Input finding: + +- target: `VendorUpdaterLogon` +- type: scheduled logon task +- evidence: task appears in inventory but state is `Disabled` + +Reasoning: + +- disabled inventory is not active startup load +- do not claim disabling it will improve startup +- record it as residue only if cleanup is in scope + +Output stance: no performance action; optional cleanup discussion. diff --git a/sysadmin-windows-startup-remediation/references/decision-framework.md b/sysadmin-windows-startup-remediation/references/decision-framework.md new file mode 100644 index 0000000..8a41de5 --- /dev/null +++ b/sysadmin-windows-startup-remediation/references/decision-framework.md @@ -0,0 +1,53 @@ +# Decision Framework + +Use this reference when deciding whether a startup target is a safe remediation candidate. + +## Target Classification + +Classify each target before proposing action: + +- `nonessential`: tray UI, marketing launcher, telemetry, one-shot helper, stale updater, or leftover vendor task. +- `workflow-dependent`: development tool, sync client, VPN, remote access, device utility, licensing helper, backup tool, or app the user may rely on. +- `system-critical`: Microsoft, Windows, driver, firmware, security, identity, disk, backup, or update component. +- `unknown`: unclear publisher, missing executable, unclear purpose, or conflicting evidence. + +## Decision Rules + +- For `nonessential` targets, prefer the least invasive reversible disable or app setting. +- For `workflow-dependent` targets, ask how the user uses it before changing anything. +- For `system-critical` targets, stop unless there is an explicit, well-understood vendor-supported fix. +- For `unknown` targets, inspect identity first; do not guess. + +## Action Preference + +Choose actions in this order: + +1. Application or vendor-supported startup setting. +2. Windows-supported disable operation, such as Startup Apps, Task Manager, `Disable-ScheduledTask`, or service startup-type change. +3. Reversible quarantine or holding location with exact rollback notes. +4. Uninstall guidance only when the user asks or disabling startup does not address an unwanted application. + +Prefer delayed automatic or manual over disabled for services when the component may still be needed. + +## Approval Quality + +Ask for approval using target-specific language: + +- exact target identity +- proposed action +- expected startup effect +- risk and side effects +- elevation needs +- rollback path + +Do not treat broad optimization intent as approval for multiple unrelated targets. + +## Stop Conditions + +Stop and ask when: + +- evidence does not clearly connect the target to startup impact +- the target controls hardware, security, backup, sync, licensing, or remote access +- rollback cannot be described before the change +- a cleanup or uninstall tool would need to be downloaded +- the source or publisher cannot be verified