theory-fidelity

Theory Fidelity Audit

Most framework checks evaluate process (cycle health, gates) or artifact performance (evals, DORA). None of them ask the question this skill exists for: for every theory a project claims to represent, is the mapped mechanism actually faithful to what the theory says — or is it theatre? This is the audit of the theory→mechanism mapping itself.

The framework's own stated bar (docs/theories.md): "every theory is mechanism-mapped … citations without mechanism-mapping are theatre." This skill holds the project to that bar — including holding the theory doc to it.

When to Use

• Quarterly, alongside /mycelium:framework-health (process health) — this is the theory-fidelity half.
• After adding/citing a new theory, or after editing a theory's mechanism (skill/gate/schema).
• When a citation looks decorative, or when a doc claims a mechanism you suspect doesn't exist.

The Grading Rubric (three axes)

For each claimed theory, record:

1. Representation — Mechanized (a skill/gate/schema/canvas applies it) · Prose-only (cited + described, no mechanism) · Absent.
2. Fidelity (only if Mechanized):
   • Faithful — the mechanism matches the theory's real claims.
   • Justified-Adaptation — the mechanism deliberately diverges and the rationale is documented in-repo. Divergence with no documented rationale is Distorted, not Justified.
   • Partial — a faithful subset, with a named gap.
   • Distorted — diverges without rationale, or misrepresents the theory.
   • Over-claim — the theory doc claims more than the mechanism delivers (the project's own "theatre" failure mode).
   • Name-only — cited but not actually mechanized.
3. Evidence-basis — source-grounded (verified against the author's canonical work) · model-knowledge (from the agent's training — provisional / consistency-only).

Workflow

1. Rule on the PREVIOUS audit's findings — before producing any new ones. Per ${CLAUDE_PLUGIN_ROOT}/engine/canvas-guidance.yml#prior_findings_first.