/theory-fidelity

name: theory-fidelity
description: "Audit whether the theories/methodologies a project claims to implement are faithfully operationalized — or name-dropped, partially built, distorted, or over-claimed. Source-grounds the load-bearing theories; tags the rest provisional. Run periodically alongside /framework-health."
metadata:
  instruction_budget: "55"
  framework_dependency: "mycelium"
  framework_dependency_note: "Designed to run within Mycelium (https://github.com/haabe/mycelium), where docs/theories.md provides the claimed-theory inventory. On a non-Mycelium project it audits whatever theory/methodology doc the project maintains; with no such doc it reports the absence. Install: /plugin install mycelium@haabe-mycelium."

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 (five 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**). *This axis is about how YOU know. Axes 4 and 5 are about the theory itself; do not collapse them.* 4. **Currency** — `current` (the version cited is the newest authoritative one) · `behind` (a newer edition, report or revision exists and the difference is material) · `book-date` (cited at the founding work, which is correct for a stable theory) · `unmarked` (no version signal anywhere on the surface). Record **what version is cited**, **what is current**, and whether the theory is **LIVING** (annual reports, new editions, an author still revising) or **STABLE** (unchanged since the founding work). *A LIVING theory graded `unmarked` is the finding; a STABLE one graded `book-date` is fine.* 5. **Evidence class of the theory itself** — `research` (empirical study with a stated method) · `synthesis` (practitioner work that cites research) · `judgement` (practitioner authority and case narrative, no cited study). Plus, where the theory makes population claims, **the population the evidence came from**. *This is not a quality ranking. A `judgement` theory can be excellent and a `research` one can be over-read; the point is that the reader knows which they are holding.*

Why axes 4 and 5 exist (dogfood 2026-09-20)

**Axis 4.** A theory can score `Mechanized` + `Faithful` + `source-grounded` and still be faithful to a superseded edition — the first three axes cannot see it. Measured in the dogfood repo: currency was tracked well on roughly half the theory-bearing skills and **absent from seven of them** (`service-check`, `jtbd-map`, `ost-builder`, `wardley-map`, `user-needs-map`, `gist-plan`, `user-interview` carried no year marker at all). **The best-tracked skill was still one cycle behind**: `/dora-check` correctly carried the 2021 and 2023 DORA changes and the Elite tier, while dora.dev had moved to **five metrics** (deployment rework rate added 2024) and **35 capabilities** against the book's 24, and dropped the Elite/High/Medium/Low vocabulary from its current metrics guide. **Tracking once is not tracking** — which is why this is an axis with a trigger rather than a documentation pass.

**Axis 5.** A framework that grades its USERS' evidence on the Gilad ladder while citing its own theories ungraded holds a double standard. Three primary-source reads bracket the range: one cited book contains no study, dataset or citation at all; another cites named researchers and flags its own thin spots (*"the research is limited and conflicting"*); a third rests on >23,000 survey responses **and self-locates below causal** — *"The analyses presented in this book fall into the first three categories"* of Leek's six. **Citing the third as proof that a practice CAUSES an outcome over-reads it by one tier**, and the over-read is licensed by its chapter titles rather than by its methods appendix.

**The model to copy, from the same sweep:** `/team-shape` already does axis 4 without being asked — it carries the 2nd-edition platform-grouping correction *and* notes that *"the live site renders the third interaction mode 'Facilitation' while the book says 'facilitating' — which is why that enum is deliberately unpinned."* Someone checked the source against the live site and left the reasoning in place. **That is what a `current` grade looks like.**

Workflow

0. **Rule on the PREVIOUS audit's findings — before producing