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.
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.
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:
- Does
links.githubpoint to a concrete file via/blob/? - Is every scoring evidence row live and non-seed?
- 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 inscripts/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
- Read the methodology page. Open
docs/codex/trust-methodology.html. The "10 evidence types — base formula at a glance" table (search forbase formula) lists every evidence type and the raw input fields its formula consumes. Confirm the field the issue names appears there. - Confirm the CLI writes it. Grep
src/gaia_cli/commands/dev/evidence.pyfor the field name. If the flag exists and the writer stores it, the CLI already treats that field as persistable. - Confirm the TM engine reads it. Grep
src/gaia_cli/trustMagnitude.pyfor the field name viarow.get("<field>", ...). If the engine reads it, the field is a first-class input, not a derived value. - Confirm the schema declares it. Open the relevant
evidenceEntrydefinition and check thepropertiesblock. Because both schemas setadditionalProperties: false, any field the CLI writes but the schema does not list will be rejected on the firstgaia dev validaterun — which is exactly what surfaces most of these gaps. - 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, andskillCountInRepoare the evidence inventory. They MUST be storable on an evidence row sogaia dev calibrate-evidence-gradescan re-derive grades from them at any future time. - Derived fields remain recomputable.
trustMagnitudeandoverallTrustGradeare 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
trustNumberas a workaround. Writing only a pre-computedtrustNumberto 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:
docs/js/tm-config.js— frontend SoT for the formulasrc/gaia_cli/trustMagnitude.py— backend implementationdocs/codex/trust-methodology.html— the doc itselfregistry/schema/meta.json—perRowGradeThresholdsandgradeCeilingtests/test_row_grading.py+tests/test_calibrate_evidence_grades.pypython scripts/build_docs.py— regenerate everythinggaia 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
trustNumberin 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 thangaia dev calibrate-trust-magnitude. - Enforce #2473 social vs proxy eligibility and freshness boundaries from
docs/agents/curation-authority-map.md:social-signaladmits 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-containmentstrictly requires an external, non-first-party repository (externalStars >= 10000); and syntheticself-attestationis 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, anddocs/agents/curation-authority-map.mdsupersede historical draft clauses infounder/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: 471k | 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 |