corrections-audit

Corrections Audit Skill

Analyze corrections.md for trends, recurring patterns, and actionable insights.

When to Use

• Loop 2 (Incremental) cadence: after every 3+ corrections are logged
• When the same correction category appears 3+ times
• During /mycelium:diamond-assess if corrections gate has findings
• Before starting a new diamond at the same scale as a previously corrected one

Workflow

1. Load corrections AND warnings AND clusters: Read .claude/memory/corrections.md, .claude/memory/warnings-log.md, AND .claude/memory/cluster-instances.md (the cluster log graduated 2026-05-08 — canonical record of recurring-pattern instances and their graduation status; without it, "the cluster has graduated N times" has no auditable backing).
2. If corrections + warnings both empty AND no clusters logged: report "No corrections, warnings, or clusters to audit" and stop
3. Treat all three as inputs to the same pattern analysis. Corrections capture agent-introduced failures; warnings capture framework-state debt; cluster-instances capture cross-cluster pattern accumulation with explicit graduation criteria. Same recurring-pattern shape, different vantage points.

1. Categorize by frequency:
2. Group corrections by Category (bias, security, engineering, process, communication)
3. Group by Scope (discovery, delivery, orchestration, quality)
4. Count occurrences per group

1. Detect recurring patterns:
2. [ ] Same category appears 3+ times -> candidate for guardrail graduation
3. [ ] Same scope appears 3+ times -> candidate for domain-level CLAUDE.md update
4. [ ] Same mistake repeats after prevention was documented -> prevention strategy failed, needs escalation

1. Check origin distribution (APEX alignment):
2. Count corrections by Origin (ai-generated, human-written, ai-assisted)
3. If ai-generated corrections dominate (>60%): flag for prompt/context improvement, BUT see detection_origin cross-check below before acting on this interpretation
4. If human-written corrections dominate (>60%): flag for process/training improvement
5. If ai-assisted is high: check if the AI contribution or the human contribution caused the issue

4b. Cross-check with detection_origin (when field is present — see .claude/memory/README.md):

• Count corrections by Detection_origin if present (user / agent_self / hook / evaluator / eval_runner / external_review)
• Critical disambiguation: if Origin is heavily ai-generated AND detection_origin is heavily user, the apparent AI-quality signal is actually a HARNESS-DETECTION GAP. The AI is generating failures and the user is the only entity catching them. The right intervention is more harness checks (hooks, evaluators), NOT more AI context.
• If detection_origin is dominantly user (>70%): flag for harness-detection gap. Suggest where new hooks or evaluators could catch the failure modes earlier.
• If detection_origin is well-distributed across mechanisms: harness coverage is healthy; trust the Origin signal at face value.
• Surfaced 2026-05-03 (mycelium-roadmap dogfood): without this cross-check, the audit's "100% ai-generated → improve prompt context" framing would have driven the wrong intervention. Real signal was "AI generates, user catches" — fixed by shipping the framework-guard hook (harness-detection layer), not by improving prompts.

1. Root-cause recurring corrections (5 Whys):

For each correction that appears 3+ times, apply 5 Whys to find the systemic root:

• Why did this happen? -> Why did that happen? -> ... -> [systemic root cause]
• Stop when you reach something changeable: a guardrail, gate, process step, or prompt instruction
• Anti-pattern: stopping at "human error" or "agent didn't follow instructions" — ask why the system allowed it

Source: Toyoda/Ohno (5 Whys), adapted for agentic workflows.

1. Identify graduation candidates (across corrections, warnings, AND cluster-instances):
2. Correction logged 3+ times with same root cause -> propose new guardrail (draft G-XX entry) AND ensure a cluster-instances.md entry exists for the pattern
3. Warning class with Count: 3+ and Status: open in .claude/harness/warnings-log.md -> graduation candidate. Consult ${CLAUDE_PLUGIN_ROOT}/engine/warning-handbook.md for the canonical fix; if the canonical fix is "manifest-driven" or similar structural pattern that's already shipped, the recurrence indicates a regression, not a new pattern.
4. Correction reveals a failure mode not in ${CLAUDE_PLUGIN_ROOT}/harness/anti-patterns.md -> propose new anti-pattern entry
5. Correction reveals a successful mitigation -> propose new pattern in patterns.md
6. Cross-cluster patterns: when corrections + warnings together reveal the same shape (e.g., "documented rule diverges from enforcement" — fired both via validator gaps in warnings-log AND via agent-behavior corrections), graduate to a meta-pattern in patterns.md and consider whether one upstream mechanism could close both surfaces.

6b. Cluster-instance audit (graduated 2026-05-08): For each entry in cluster-instances.md:

• Update instance count: if any correction logged since the last audit fits an existing cluster's shape, increment that cluster's instance count and add a row to its instance log. If the shape is new and recurs (≥2 candidates), propose a new cluster section.
• Check graduation criterion: each cluster has a stated graduation criterion (e.g., "≥3 instances, ≥3 detection rules validated, <5% FP"). If a cluster has crossed its criterion without being graduated, flag it as a graduation-readiness signal.
• Cross-reference spec docs: if a cluster has a spec graduation status (e.g., "documented-rule-diverges-from-enforcement" → ${CLAUDE_PLUGIN_ROOT}/engine/consistency-check-spec.md), check whether new instances introduce subclass shapes the spec hasn't yet considered. New subclasses extend the spec; recurring known subclasses just increment the count.
• Surface mis-counted clusters: a recurring failure mode silently accumulating without a cluster entry IS the harness-context-debt the cluster log was created to scope. If you find correction patterns that should have been counted but weren't, propose backfill entries.
• Recursive check: a cluster's graduation criterion not being honored is itself an instance of the documented-rule-diverges-from-enforcement cluster. If you detect this, log it as a new instance of that cluster (with appropriate eyebrow-raising in the report).

6c. Scan docs/receipts/cases/ frontmatter for graduation signals (added 2026-05-08 with the docs restructure): For each case file in docs/receipts/cases/*.md:

• Parse YAML frontmatter (id, date, contributor, mechanism_or_status, commits, subclass).
• Cross-reference with cluster-instances.md: if the case's subclass field names a known cluster, ensure the cluster's instance count includes this case. If the case is the first instance of a recurring shape that has no cluster entry, propose a new cluster.
• Detect mechanism-or-status patterns: if multiple cases share a mechanism_or_status: in-progress and the underlying friction recurs, that is a graduation-readiness signal — the partial fix has not converged. If multiple cases share mechanism_or_status: one-off, check whether they actually share a root-cause shape that warrants graduation to a cluster.
• Report contributor distribution: which contributors produce the most receipts? Solo internal-dogfood receipts are valid but the framework's claim of community-shaped feedback weakens if external_human contributor cases are sparse. Flag if external receipts < internal receipts × 0.2 across the last 90 days.
• Identify candidate-graduation cases: a mechanism_or_status: spec that has been at spec ≥30 days without a promotion-bar update is a stalled-spec signal worth su