maf-remediation-playbook
Skill14 starsChanged 3 months agoMITView on GitHub
The fix-everything playbook for the maf-remediate loop: per-rule canonical fix + how to tell a real finding from a false positive (by confidence tier). Use when driving a codebase to a clean MAF health grade — triage heuristic findings before changing code.
We split this skill into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 19
Every finding carries confidence:
≈ “Common” is an estimate: at least 1 in 5 of the 308,232 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
maf-remediation-playbook — fix real issues, skip false positives
Used by the
maf-remediateprompt. It drives the loop; this skill is the per-rule reference: what the canonical fix is, and — for the heuristic detectors — how to recognise a false positive before you touch code.
The loop (quick reference)
MafDoctor(repoPath, format: "plan")+MafDoctor(repoPath, format: "json", full: true)— the plan + every finding with aconfidence.MafAutoFixAll(repoPath, dryRun: false)— the deterministic, mechanical fixes (F-11:dryRunnow defaults totrue/preview-only; omitting it here would silently apply nothing).dotnet build(green).- For each remaining finding in plan order: triage by
confidence(below) → fix or skip →dotnet build→ confirm the finding actually cleared (re-scan), not just a green build. - Re-pull
MafDoctor(format: "json", full: true)(line numbers shift after edits) and keep working findings until the only ones left are explicitly skipped (false positive) or deferred to human judgment — NOT merely until the A/B/C/F letter stops moving (the grade has wide bands and won't shift for most single fixes). Report fixed vs skipped-as-false-positive.
Confidence tiers (the triage signal)
Every finding carries confidence:
certain— compiler ground-truth (CS0618). No false positives. Fix it.high— structural AST rule, low false-positive risk. Apply the canonical fix with a quick sanity check.heuristic— name-only / text / scope-limited. May be a false positive. CallMafExplainFinding(repoPath, file, line), read the surrounding code, and confirm it's a real problem before changing anything. When unsure after reading the code — in either mode — skip and flag for human review; never edit on a maybe.
Per-rule playbook
| Rule | Confidence | Canonical fix | If it's a FALSE POSITIVE (skip) |
| MAF001 (fan-out starvation) | high | Return ValueTask<T> — the value is auto-broadcast; required on an AddFanOutEdge source (SendMessageAsync does NOT broadcast on a fan-out edge). For a plain AddEdge target, await context.SendMessageAsync(...) is also valid. | Rarely a false positive. The source-level detector already treats any handler that emits via context.SendMessageAsync/YieldOutputAsync/AddEventAsync as OK, so a MAF001 finding means the handler returns nothing and emits nothing — a genuine dead-end. (The fan-out-EDGE nuance — a SendMessageAsync-only handler that happens to sit on an AddFanOutEdge source — is resolved cross-file by MafSimulateWorkflow, not by MAF001.) |
| MAF-AP-EXEC-001 (legacy executor) | high | Delete [StreamsMessage]/[YieldsMessage]; migrate ReflectingExecutor<> → sealed partial : Executor + [MessageHandler]. | An IMessageHandler<T> that is MediatR / NServiceBus / a hand-rolled bus (no Microsoft.Agents.AI.Workflows). |
| MAF-AP-DEVUI-001 (DevUI/Hosting) | high | Wrap the unsupported preview reference in #if DEVUI_ENABLED. | A supported Microsoft.Agents.AI.Hosting.A2A[.AspNetCore] using, or a project's own namespace DevUI;. |
| MAF-AP-SEC-001 (DefaultAzureCredential) | high | ManagedIdentityCredential in production. | Already inside an env.IsDevelopment() / #if DEBUG dev-only branch. |
| MAF-AP-SEC-003 (EnableSensitiveData) | high | Make it env-driven (= env.IsDevelopment()) or fence behind #if DEBUG. | Same-named bool on an unrelated (non-OTel) type. |
| MAF-AP-CONC-001 (provider field) | high | Move per-session state into a readonly ProviderSessionState<T>. | The field already IS ProviderSessionState<T>, or an injected readonly dependency. |
MAF-AP-CONC-002 (.Result/.Wait()) | high | Make the chain await-first; propagate async + a CancellationToken. | (await x).Result (AgentResponse<T> payload) or Match.Result(...) (Regex) — not a blocking Task. |
| MAF-AP-AGENT-001 (top-level Instructions) | high | Move Instructions into the nested ChatOptions (top-level was removed in 1.3.0). | A user type named ChatClientAgentOptions in your own namespace. |
| MAF-AP-WF-001 (sealed Executor) | high | Add sealed partial to the concrete Executor. | A non-MAF base type that happens to be named Executor. |
| COST-001 (uncapped agent call) | heuristic | Set MaxOutputTokens on the nearest ChatOptions. | app.RunAsync() (ASP.NET host), InProcessExecution.RunStreamingAsync/workflow.RunAsync (workflow runners) — not agent calls. |
| MAF-AP-SEC-002 (hard-coded key) | heuristic | Source the key from env/Key Vault; rotate the leaked one. | A non-secret string that merely starts with sk- (a SKU id, slug, or sk-xxxx placeholder). |
| MAF-AP-OBS-001 (no OpenTelemetry) | heuristic | Chain .AsBuilder().UseOpenTelemetry(...) on the client/agent. | The IChatClient is instrumented in another file and injected here. |
| MAF-AP-MID-001 (middleware) | heuristic | Provide both runFunc: and runStreamingFunc: (or the sharedFunc: overload). | A non-MAF builder whose Use(runFunc:) has no streaming concept. |
| PROMPT-001/002/003/004 (prompt lint) | heuristic | Non-empty prompt; split bloat; add refusal guidance; never interpolate untrusted input into Instructions. | An Instructions property on a non-agent type (recipe, build step, form field). |
Rules
- Make the minimal change that resolves a finding; don't refactor opportunistically.
dotnet buildgreen after every change; never mark a finding fixed on a red build.- Hard constraints at
maf://constraintsoverride everything here. - A skipped false positive is a SUCCESS, not a failure — record it with a one-line reason.
In this repository17 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- .github/copilot-instructions.mdCopilot instructions
- cs0618-hunterSkill
- dotnet-inspectSkill
- maf-anti-pattern-scannerSkill
- maf-doctor-self-evolutionSkill
- maf-fan-out-validatorSkill
- maf-from-semantic-kernelSkill
- maf-issue-reporterSkill
- maf-migration-guideSkill
- maf-migration-plan-creatorSkill
- maf-migration-retrospectiveSkill
- maf-obsolete-api-registrySkill
- maf-release-watcherSkill
- maf-workflow-smoke-testerSkill
- nuget-diff-analyzerSkill
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
Reviews can't be read right now.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.