Skip to content

gaia-research/gaia-skill-tree / .agents/skills/trust-methodology-consult

trust-methodology-consult

Verified

Consult this skill BEFORE proposing a fix to any CLI gap or schema gap that touches evidence, trust magnitude, evidence types, evidence grades, the TM formula, or star-level promotion gates. Also read it whenever an issue mentions citations, stars, commits, contributors, views, reviewers, percentile, arxiv, github-stars-own, repo-own, social-signal, benchmark-result, peer-review, self-attestation, fusion-recipe, verifier-attestation, or proxy-containment — those are the 10 canonical evidence types and the raw inputs that feed their formulas. Also read it when asked whether a skill qualifies for a given star level (0★–6★): the Star Bar and promotion gates live in `META.md`, not in the TM methodology page. Reading both prevents proposing a calibration that satisfies the TM grade threshold but violates a Star Bar installability or link requirement.

FileKindSize
SKILL.mdskill md11.1 KB
---
name: trust-methodology-consult
description: >
  Consult this skill BEFORE proposing a fix to any CLI gap or schema gap that
  touches evidence, trust magnitude, evidence types, evidence grades, the TM
  formula, or star-level promotion gates. Also read it whenever an issue
  mentions citations, stars, commits, contributors, views, reviewers,
  percentile, arxiv, github-stars-own, repo-own, social-signal,
  benchmark-result, peer-review, self-attestation, fusion-recipe,
  verifier-attestation, or proxy-containment — those are the 10 canonical
  evidence types and the raw inputs that feed their formulas. Also read it
  when asked whether a skill qualifies for a given star level (0★–6★): the
  Star Bar and promotion gates live in `META.md`, not in the TM methodology
  page. Reading both prevents proposing a calibration that satisfies the TM
  grade threshold but violates a Star Bar installability or link requirement.
---

# Consult the trust methodology before touching CLI/schema evidence surface

TM facts (weights, caps, dedup, inheritance, grade floors, star gates, persistence and
appraisal scope) come from one canonical map:
[`docs/agents/curation-authority-map.md`](../../../docs/agents/curation-authority-map.md).
`tests/test_curation_authority_map.py` checks that map against the live engine. Read it
before restating any number, and cite it instead of copying formulas into a fix or a skill.

The Gaia trust surface is a three-layer contract. Skipping any layer when
proposing a fix guarantees you either widen or narrow it incorrectly:

| Layer | Source of truth |
|---|---|
| **Concept** — what the numbers mean and why they exist | `docs/codex/trust-methodology.html` (also mirrored in `docs/meta/2026-06-trust-methodology.md` and the G7 supersession note at `docs/meta/2026-06-17-g7-trust-magnitude-supersession.md`) |
| **Compute** — how the numbers are actually produced | `src/gaia_cli/trustMagnitude.py` (backend); `docs/js/tm-config.js` (frontend SoT) |
| **Persistence** — what shape the CLI writes and the schema bounds | `src/gaia_cli/commands/dev/evidence.py` (writer) + `registry/schema/skill.schema.json` + `registry/schema/namedSkill.schema.json` (bounds) |
| **Star level gates** — what a skill must satisfy to hold 0★–6★ | `META.md` §2 (Star Bar, installability, blob-link requirement, 4★+ live evidence rule, Specialist Path rubric, Apex 6-predicate gate (Suite branch, §4.3) and the provisional Unique Impossible 5-predicate gate (Unique branch, §4.4)) |

When an issue lands as "CLI gap" or "schema gap" on this surface, ONE of those
layers is out of step with the other two. Your first job is to identify which.

## Star Bar — read META.md before calibrating any 3★+

The TM methodology page covers *how scores are computed*. It does **not** cover
*what a skill must have to hold a given star level*. Those gates live in
`META.md` §2 and must be checked independently:

| Level | Gate |
|---|---|
| 0★–2★ | No link requirement; `installable: false` permitted |
| 3★+ | `links.github` **must** be a verified blob URL (`.../blob/<branch>/...`). Bare repo root → hard-demote to 1★. |
| 4★ | Overall Trust Grade **A (TM ≥ 100)**, strictly. B caps a skill at 3★. |
| 4★+ | Live, verifiable usage evidence required. Seed/placeholder evidence is insufficient. |
| 5★ | Overall Trust Grade **S (TM ≥ 250)** and its independent-witness diversity gate. |
| 4★+ Specialist | Vendor-locked skills: Depth-of-Integration rubric (META.md §2.3) |
| 6★ Suite (Apex) | Grade S + 6-predicate Apex gate (META.md §4.3) |
| 6★ Unique (Unique Impossible) | Grade S + provisional 5-predicate gate (Apex set minus directNestedSuiteGte1, META.md §4.4; branch distinction ratified under Yggdrasil III, predicate set otherwise unchanged) |

When asked "should this skill be 4★?", run this check **before** computing TM:
1. Does `links.github` point to a concrete file via `/blob/`?
2. Is every scoring evidence row live and non-seed?
3. Is the computed Overall Trust Grade **A (TM ≥ 100)**? This gate is strict: META.md §1.1,
   `promotion._UNIQUE_GATE_BY_LEVEL`, and the grade-ceiling clamp in
   `scripts/generateNamedIndex.py` (B → max 3★). B does not hold 4★.

If any gate fails, the correct action is to fix the gate or demote — not to
add more evidence rows to compensate.

## The read pass — do this before writing code

1. **Read the methodology page.** Open `docs/codex/trust-methodology.html`.
   The "10 evidence types — base formula at a glance" table (search for
   `base formula`) lists every evidence type and the raw input fields its
   formula consumes. Confirm the field the issue names appears there.
2. **Confirm the CLI writes it.** Grep `src/gaia_cli/commands/dev/evidence.py`
   for the field name. If the flag exists and the writer stores it, the CLI
   already treats that field as persistable.
3. **Confirm the TM engine reads it.** Grep `src/gaia_cli/trustMagnitude.py`
   for the field name via `row.get("<field>", ...)`. If the engine reads it,
   the field is a first-class input, not a derived value.
4. **Confirm the schema declares it.** Open the relevant `evidenceEntry`
   definition and check the `properties` block. Because both schemas set
   `additionalProperties: false`, any field the CLI writes but the schema
   does not list will be rejected on the first `gaia dev validate` run —
   which is exactly what surfaces most of these gaps.
5. **Validate the failure locally, don't infer it.** Write a tiny probe file
   with the field, run `jsonschema.validate(instance, schema)`, and observe
   the exact rejection path. Do not trust an issue's diagnosis until the
   local repro matches.

## The design principle you must not violate

The founder ruling in `META.md` §2.1c and authority map §4 permits computed
Trust Magnitude and Overall Trust Grade on a named node as a **hash-signed cache**:
`trustMagnitude`, `overallTrustGrade`, and `trustMagnitudeInputHash` are written
only by `gaia dev calibrate-trust-magnitude`. `scripts/generateNamedIndex.py` trusts
the cache only while the input hash matches; otherwise it recomputes. Raw evidence
remains the source of truth. A named skill's effective TM includes eligible
generic-layer evidence at the engine's inheritance multipliers; an own-only
proposal total is not its final effective TM.

- **Raw inputs are the persisted state.** Fields like `citations`, `stars`,
  `commits`, `contributors`, `views`, `reviewers`, `percentile`, and
  `skillCountInRepo` are the evidence inventory. They MUST be storable on an
  evidence row so `gaia dev calibrate-evidence-grades` can re-derive grades
  from them at any future time.
- **Derived fields remain recomputable.** `trustMagnitude` and `overallTrustGrade`
  are computed. They may appear in reports, generated catalogs, and the permitted
  CLI-written cache, which never replaces the underlying evidence inventory.
- **Do not "collapse" raw inputs into `trustNumber` as a workaround.** Writing
  only a pre-computed `trustNumber` to sidestep a schema rejection erases the
  audit chain ("why did this row score 73?") and breaks the recompute path.
  It is a legitimate one-off remediation when a schema fix is blocked; it is
  never a design.

## Decision matrix — what kind of gap is it?

| Symptom | Most likely gap | Fix direction |
|---|---|---|
| CLI writes field `X`; TM engine reads field `X`; schema rejects `X` | **Schema gap** — schemas lag documented reality | Add `X` to `evidenceEntry.properties` in both `skill.schema.json` and `namedSkill.schema.json`; keep the two schemas symmetric |
| CLI writes field `X`; TM engine ignores `X`; schema silent | **CLI over-writes** — the field is dead weight | Remove the write in `evidence.py`; document why |
| CLI has no flag for `X`; TM engine reads `X`; schema silent | **CLI gap** — TM depends on data no operator can add | Add the flag + writer, then verify schema accepts it (add if needed) |
| Methodology page mentions a metric not in the CLI or TM engine | **Doc drift** — treat as spec, not law | Open a discussion issue before touching any of the three layers |

## The write pass — order matters

The methodology page's own "if you change a formula" checklist applies, in
this exact order. Do not skip a step or reorder them:

1. `docs/js/tm-config.js` — frontend SoT for the formula
2. `src/gaia_cli/trustMagnitude.py` — backend implementation
3. `docs/codex/trust-methodology.html` — the doc itself
4. `registry/schema/meta.json` — `perRowGradeThresholds` and `gradeCeiling`
5. `tests/test_row_grading.py` + `tests/test_calibrate_evidence_grades.py`
6. `python scripts/build_docs.py` — regenerate everything
7. `gaia dev calibrate-evidence-grades --yes` — refresh stored grades

If the gap is schema-only (as in Issue #941 — the field is already read and
written, only the schema disagrees), most of that list does not apply —
only steps 4-ish (extend the schema), 6 (regen docs), and 7 (rerun the
calibration if any stored grade shifted) matter. Small schema changes still
belong on a `schema/*` branch per the branch-scope rules.

## A stale stored TM is refreshed through the CLI, not a helper

When a consumer shows a stale cached TM, refresh it with the CLI write verb, not a
vendored script or a hand edit. The verb is Verifier-gated, so run it on a `review/meta/`
branch, dry-run first, then run `gaia dev docs`:

    gaia dev calibrate-trust-magnitude --skill <owner/skill-id> --dry-run
    gaia dev calibrate-trust-magnitude --skill <owner/skill-id>
    gaia dev docs

Do not add or recommend a separate write-back helper. The earlier vendored
`recompute_one_tm.py` was retired because it bypassed this verb.

## What NOT to do

- Do not "just remove the field" from the CLI when the TM engine still reads
  it — you'll silently zero out every skill's citations-based magnitude.
- Do not add the field to only one of the two schemas. Named and generic
  evidence entries share the same shape; asymmetric schemas guarantee the
  next reviewer will re-file the same issue.
- Do not persist a pre-computed `trustNumber` in place of the raw input as a
  "design" — see "The design principle you must not violate" above.
- Do not hand-write `trustMagnitude` / `overallTrustGrade`, or recommend any write-back
  path other than `gaia dev calibrate-trust-magnitude`.
- Enforce #2473 social vs proxy eligibility and freshness boundaries from `docs/agents/curation-authority-map.md`: `social-signal` admits both first-party and third-party demonstrations of the target skill (`sameAsAuthor = 1.0`, `publishCooldownDays = 0` — no 30-day publication hold, 1,000-view floor, relevance/provenance required, `(type, url)` dedup, 3-row plateau, 80 TM cap); `proxy-containment` strictly requires an external, non-first-party repository (`externalStars >= 10000`); and synthetic `self-attestation` is never used to push a suite component past the 49.9 TM shared-repository cap.
- Do not re-derive the answer from memory. Active rules in `META.md`, `registry/schema/meta.json`, and `docs/agents/curation-authority-map.md` supersede historical draft clauses in `founder/handovers/done/G7_TRUST_TAXONOMY_RFC.md`. Always re-read the authority map and methodology page before acting.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall