gaia-research/gaia-skill-tree / .agents/skills/trust-methodology-consult
trust-methodology-consult
VerifiedConsult 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 11.1 KB |
SKILL.md
View on GitHub---
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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| 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 available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |