What does WinMedic do?

Goal

Treat the host agent as the reasoning layer, and the local PowerShell and built-in engine as the execution layer. First, locate the root cause with evidence, then propose the minimal fix, execute only after confirmation, and verify.

This Skill does not start a separate model, does not connect to the internet, does not collect telemetry, and always obeys the host's permissions and approval mechanisms.

Pre-Execution Checks

Confirm the platform is Windows, the shell is PowerShell, and whether the current session is administrator. Do not infer from user descriptions.
Confirm the scope is the local machine. If the user provides exclusions (e.g., "don't touch WeChat", "don't delete D drive"), crystallize them as constraints and obey them throughout.
Run engine\winmedic.ps1 doctor once to obtain permissions/PS version/WizTree availability.
If the host has no local execution capability (chat only), switch to "manual steps + verification points" mode for output; do not pretend to execute.

Mandatory Workflow

1. Clarify the Goal

Break it down into: symptom, desired state, immutable constraints.
Keep multiple goals separate; do not replace migration with deletion, or repair with reinstallation.
Only ask questions when ambiguity would significantly change the path.

2. Route the Playbook

Read playbook-index.md, select the most specific playbook by symptom.
Load only the required one playbooks/*.md, do not read all at once.
For multiple independent issues, process them one by one in order of "impact × dependency."

3. Read-Only Diagnosis

winmedic.ps1 probe --set <domain>        # Output: state\findings.json

Probes are read-only. Any step that performs a write operation is a bug; stop immediately and report.
Items that cannot be collected should be accurately labeled "unavailable" – do not guess.

4. Generate the Plan

winmedic.ps1 plan --from state\findings.json

Outputs plan.json + plan.md + planHash. Present the plan.md verbatim to the user – do not rephrase it into vague descriptions.

The plan.md now contains two sections:

Recommendations (by priority) – Cross-domain disposition recommendations. high priority first (pending reboot, no restore point, security risk, disk emergency).
- If the Disposition column says executable: <action>, run winmedic.ps1 apply --action <action> --yes directly.
- If it says manual: <playbook>, follow that playbook's steps without inventing your own.
Details – Engine-executable cleanup items (executed by id).

The recommendation section's sources are deterministic rules (not model guesses), with evidence pointing to playbook or catalog evidence entries.

5. Confirmation

List each item: action, impact, risk level, rollback capability.
Only execute ids the user has explicitly approved. If the user says "whatever", by default only do Tier 1 + Tier 2.
Tier 3 must be confirmed item by item; Tier 4 is never executed.

6. Execution

winmedic.ps1 apply --plan state\plan.json --ids R1,R3 --yes

Default is to quarantine (soft delete); do not casually add --purge.
On partial failure (exit code 7), check the journal first before deciding whether to continue.

7. Verification

winmedic.ps1 verify --journal <id>

Check free space, service status, whether the target is gone.
If pendingReboot = true, clearly tell the user "This will only fully take effect after a reboot" – do not falsely claim success.

8. Report

Fixed five sections: Status → What Was Found → What Was Done → Verification Results → What Was Not Done (and Why).

Action Tiers

Tier	Meaning	Execution Requirement
1	Zero risk, system runs fine after deletion	Confirmation only
2	Cache, will be rebuilt	Explain the rebuild cost
3	Requires judgment, may affect functionality	Confirm item by item + show evidence
4	Red line	Refuse to execute, explain why, provide a manual path

One-Screen Health Check & Comparison

winmedic.ps1 probe --set intake        # Cross-domain read-only collection (~60-90 seconds)
winmedic.ps1 summary                   # One-screen summary across 9 domains, with OK/WARN/BAD
winmedic.ps1 diff --from a.json --to b.json   # Compare two collections

Domains not yet collected in the summary display [?] Not collected – do not draw conclusions from this; collect the data first.

The end of the summary directly lists "Recommendations" (by priority), sourced from the same origin as the plan recommendation section. For machine readability, add --json and redirect:

winmedic.ps1 summary --json > status.json

Specific Software (Workloads Domain)

When the user names a specific piece of software (LaTeX, PyCharm, Steam, Zotero, Word, proxy tools...), first run:

winmedic.ps1 probe --set workloads

It measures the cache and data sizes of each software according to the signature table in catalog/workloads.json, and checks proxy chain consistency.

Key distinctions:

kind=cache (shader cache, IDE index, texmf-var, OfficeFileCache) → can be cleaned, cost is rebuild
kind=data (game binaries, Zotero attachments, WeChat chat history, texmf-dist) → never delete, only migrate
kind=review (Tencent Video downloads, mixed directories) → must confirm first; may contain user-downloaded content
probe.proxy-chain lists the five layers of proxy values (system/WinHTTP/git/npm/pip); consistent=false means conflict

Adding new software does not require code changes: add a signature entry (detect + measure + playbook) to catalog/workloads.json.

Migration Decisions (When the user says "move cache/software to another drive" or "C: drive can't fit new software")

This is a judgment call, not a table lookup. The engine only provides facts; you decide the plan, but you must complete the checklist.

winmedic.ps1 relocate            # Disk overview + decision checklist + fact table + default recommendation
winmedic.ps1 relocate --json     # Same, structured

The output has three sections with different meanings; do not conflate them:

Section	Meaning	Usage
Decision Checklist	Three mandatory questions	Must give a conclusion for each question in your answer – do not skip
Facts	Path/size/medium/existence/known folders/software declared paths	Basis for decisions
Default Recommendation	Engine's default perspective (marked `policySource=default-hint`)	Reference only, can be overridden by your judgment – do not present as a conclusion

Three Checklist Questions (Must explicitly cover in your answer)

Is it under a known folder? Yes → Move the entire folder once, not individual software paths; but first evaluate question 3 below.
Hot or cold data? Hot (real-time render cache, IDE index, streaming cache) → Keep on fastest drive; Cold (games/VMs/book libraries/chat history) → Only then consider moving to a capacity drive.
Does the software already record an absolute path (installed before moving)? Yes → Must synchronously update the software's internal settings after moving, otherwise it will point back to the old path.

What You (DSH) Must Do

First check medium in the fact table: moving hot data to an HDD is wrong, even if it is larger.
First check software declared paths: that is hard evidence of "installed before moving."
Write the plan as "what to do → why → risk → verification method," and have the user confirm before executing.
The engine does not migrate for you; your job is to give a reasoned plan.

See playbook apps-relocate-cache (PB-913).

Disease Course (What is growing, not just what is biggest)

winmedic.ps1 trend --record      # Record a snapshot (recommend once per day)
winmedic.ps1 trend --days 14     # See change and rate

Interpretation rules:

confidence=insufficient (< 2 samples) → Do not draw conclusions, just record
confidence=low (interval < 0.5 days) → Only look at the delta, no daily rate
confidence=ok → Only then can you say "grows X GB per day"

Use case: When C: drive is full, first check the trend, then decide whether to clear cache or investigate a specific software that is writing logs excessively.

Differential Diagnosis (Scenarios like "C: drive full" or "network anomaly" where root cause needs to be found)

winmedic.ps1 diagnose --list
winmedic.ps1 diagnose --case dx.cdisk-full

Output is a fact table (hypothesis × metric × current value × interpretation signal × data source), with no conclusion.

You must: judge each item, state which hypotheses are ruled out and which are supported, then provide a plan. Items with source containing trend are deltas; items marked low cannot be used to calculate a rate; items marked insufficient have no value.

If external tools are needed, first check the tool rack: winmedic.ps1 tools (detect only, do not auto-execute Tier ≥ 3).

Case Library (Experience Accumulation)

Under cases/ are seven-section cases: Symptom / Environment / Collection / Hypotheses & Exclusions / Disposition / Results / Lessons.

For similar issues, first check the case library – it can save a whole round of investigation.
After solving a new issue, write one using cases/_template.md; otherwise you'll have to start from scratch next time.
Items marked pending are unconfirmed issues without on-site evidence – do not reference as conclusions.

Evidence Query

Before any action is executed, if the user asks "why" or "what is the evidence," directly query:

winmedic.ps1 explain --action storage.winsxs-cleanup

Output includes: Level, Rollback ability, Command, Notes, Original evidence and official links, Verification date, Verification rules.

Risk Gate

apply checks recovery capability (restore points/volume shadow copies):

If the target includes Tier 3 (non-rollback) and recovery capability is not ready → Refuse to execute, return code 4
The correct action in this case: first apply --action recovery.create-restore-point --yes to create a restore point, or ask the user to explicitly add --accept-risk
Do not add --accept-risk on your own to "keep the task moving."

User Exclusions (Hard Constraints)

When the user says "don't touch WeChat" or "don't touch D drive," immediately crystallize them as exclusions – do not just keep them in memory:

winmedic.ps1 profile --exclude "C:\Users\<user>\Documents\WeChat Files"
winmedic.ps1 profile --exclude "D:\*"
winmedic.ps1 profile                       # View current exclusions
winmedic.ps1 profile --exclude "..." --remove  # Remove an exclusion

Exclusions are a two-layer barrier: excluded during the plan phase, and again rejected and logged during the apply phase.

When to Stop Immediately

The target is a file inside Windows\WinSxS, Windows\Installer, System32, or WindowsApps
The target is a chat history directory (WeChat Files / xwechat_files) or a user-declared exclusion
Only 1–2 system restore points remain and the request is to delete a restore point
Commit size is near the commit limit and the request is to shrink the page file
The user requests "delete everything" or "don't worry about risk" – First explain, then only do Tier 1/2

Engine Invocation Convention

If the host can only access tools via MCP, use engine\mcp\winmedic-mcp.ps1 (see docs/MCP.md); Tool parameters correspond one-to-one with the commands below; tool writes require yes=true. All other rules are identical.

All subcommands support --json; without --json, output a human-readable summary.
Exit codes: 0 Success / 2 Usage / 3 Permission / 4 Precondition failed / 5 Plan invalid / 6 Red line / 7 Partial failure.
Do not bypass the engine and issue delete commands directly. The engine's value is hash binding, quarantine, and audit logging.

Generate Report

winmedic.ps1 report --journal <runId>        # Five-section delivery report
winmedic.ps1 report --set storage --out report.md

The report has a fixed five sections: Status → What Was Found → What Was Done → Verification Results → What Was Not Done (and Why). If data is missing, write "not collected" – never fabricate.

Report Template

## Status
C: 98.7 GB, 16.7 GB free (83%)

## What Was Found
| Item | Size | Level | Basis |
|---|---|---|---|
| Recycle Bin | 7.03 GB | 1 | No impact |
| hiberfil.sys | 6.32 GB | 1 | Microsoft docs: powercfg /h off |

## What Was Done
R1 Emptied Recycle Bin: 7.03 GB -> 0
R2 Disabled Hibernate: 6.32 GB freed

## Verification Results
C: Free 16.7 -> 30.1 GB; Sleep S0 normal; no pendingReboot

## What Was Not Done
SoftwareDistribution (user asked to skip), Windows\Installer (high risk, recommend dedicated tool)

WinMedic

What is WinMedic?

Ask in your favorite AI

Documentation