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.

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:

LayerSource of truth
Concept — what the numbers mean and why they existdocs/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 producedsrc/gaia_cli/trustMagnitude.py (backend); docs/js/tm-config.js (frontend SoT)
Persistence — what shape the CLI writes and the schema boundssrc/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:

LevelGate
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★+ SpecialistVendor-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?

SymptomMost likely gapFix direction
CLI writes field X; TM engine reads field X; schema rejects XSchema gap — schemas lag documented realityAdd 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 silentCLI over-writes — the field is dead weightRemove the write in evidence.py; document why
CLI has no flag for X; TM engine reads X; schema silentCLI gap — TM depends on data no operator can addAdd the flag + writer, then verify schema accepts it (add if needed)
Methodology page mentions a metric not in the CLI or TM engineDoc drift — treat as spec, not lawOpen 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: 471kUpdated 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