Peer Learning with TIER: Move Practices, Not Scores

Coach the practice, not the person. Grade the work, not the worker.

TIER helps engineers choose the right model, give it the right context, and spend where it pays. A person's page is visible to their personal key, root and holders of node keys whose dated branch contains them. Other holders cannot read it. Card figures follow the reader's dated branch and names setting, and the developer can read the log of who viewed it, including administrators. Managers may coach from it; no one may ask for figures beyond it. TIER is not suitable for pay, promotion, appraisal, reviews, improvement plans, discipline or dismissal. The product cannot enforce that; only your policy or works agreement can. Anyone with host access can read the database; these limits apply at the API.

The one rule. A team gets better together by sharing what someone changed and what happened -- a practice -- not by comparing frozen individual numbers. Use name-free team or division cache shares on real data over closed months in v0.7.0. The holder-scoped coaching card ships in v0.7.0 with raw-data retention. The synthetic demo invents its own data in a private database and cannot load yours.

TIER coaches the practice, not the person (see the project README and docs/legal-and-privacy.md). This page shows a team lead how to run peer learning on that principle: agree one practice change, then measure honestly whether it helped. Name-free team cache shares and the v0.7.0 coaching card provide discussion prompts; the card ships with raw-data retention. The synthetic demo previews invented data.

Table of contents

• What this is
• The levers retro
• The before/after practice experiment
• Capture the practice
• Coaching, not appraisal
• What NOT to do

What this is

v0.7.0 availability: Coaching cards are available to holder/root/dated-branch node keys with audited reads and raw-data retention. Name-free comparisons retain the privacy floor. The separate real-data per-issue report remains future work. tierd demo shows invented views read-only in a private temporary database and cannot load yours.

Practice transfer, not number transfer. When one part of a team has learned to get more yield per $1,000 -- higher cache reuse, less premium-model spend on routine work, less spend that TIER could not link to an issue -- the thing worth spreading is the habit that produced it, described in words, not a leaderboard cell.

The method uses these three surfaces. The coaching card ships in v0.7.0 with raw-data retention:

Who sees what. Root, dated branch node keys and a person's personal key can open that person's audited coaching card. Declarations and static/shared credentials are retired. Name-free monthly comparisons retain the k floor. TIER is built for coaching, not for evaluating developers. Per-person figures are not accurate enough to judge an individual. The synthetic demo shows invented named rows beside the levers. See Coaching, not appraisal.

The levers retro

For a monthly team retro, read the published cache share in GET /api/v1/scores?period=YYYY-MM. In v0.7.0, open Developer card on the dashboard with the subject identifier and that subject's credential. A manager opens each permitted card separately; the developer sees the same card. All views, including administrator views, are logged before the builder runs.

Choose one practice from the four tiles: review model choice on routine work; use scoped sessions, stable prefixes and an instructions file; start from an issue with acceptance criteria; or follow the work-type playbook below. The routine-work tile says “data insufficient” until explicit docs/chore classification exists; the current taxonomy cannot identify those categories. It never infers a task's difficulty or says a cheaper model would have sufficed.

Read the developer's own trend within a work type. A typical range is the nominal 95% CI (with unvalidated coverage) of one pooled cost-per-outcome figure across at least k eligible contributors other than the subject. Each needs counted evidence at the monthly close, at least 50% attributed spend, at least three outcomes in that type and no low-token outcomes. Each must supply 1–50% of both pooled cost and outcomes. Outcomes, rather than per-person means, are pooled. No contributor points, identities or count are shown. The band uses the latest closed UTC month in month_person, with peers from the subject's frozen dated group paths. It ignores the card's date and repository filters. Without a monthly close there is no band; legacy seals and viewer credentials do not supply peer eligibility. The stricter of the close's and the current configured k applies. Its value is rounded to $10 and CI bounds outward to $10. Canonical value ordering keeps renaming peers from changing the bootstrap result. Later raw uploads, hierarchy edits, aliases and credential changes do not revise the frozen pool. Erasure and retention remove named peer evidence and can make a band unavailable. The own trend shows the card's last two complete 14-day windows. Each outcome belongs to its merge fortnight and carries its full-window joined cost and low-token flag. The tripwire counts verified tokens over the 14 days ending at the merge, including tokens before the card window. Separate cache/context and no-issue metrics are labelled as point readings without CIs and are not plotted on the cost axis. Failing any band guard means no band.

The attribution line measures the card's verified spend joined to outcomes, not capture fidelity. Spend on main stays uncovered. Below 50%, the card says “data insufficient” with an information icon and text. It withholds TIER and its CI, all work-type figures, premium-on-routine and the no-issue lever. Verified spend, outcomes, cache-read share and overall premium share remain. “Not on this card” is rounded to ten percentage points; excluded dollars are never published or exactly recoverable from that coarse share.

“One practice to try” selects the largest normalized deterioration among the available own trends: decreased cache-read share, increased no-issue share, or increased cost per outcome within a work type. Every measure uses symmetric relative change: twice the deterioration divided by the sum of the absolute before and after values (zero when both are zero). This dimensionless measure handles transitions from zero consistently. A tie follows the fixed tile order. It is withheld unless both windows clear the attribution floor and each has at least three outcomes. “Check again in 2 weeks” carries before/after n and nominal 95% CIs with unvalidated coverage; an observed change never establishes causation.

The team retro shares practices and name-free reports; teammates never see each other's cards. Agree one experiment from the written practice target, then check the next two-week observation. Evidence links contain only PR and session identifiers, never prompts, code, titles or session content.

1. Fetch the team's closed month and read its cache share: cache-read tokens divided by all input-side tokens.
2. Treat the lever as a prompt, not a verdict. Ask which workflows could reuse cached context.
3. Compare similar work over finished months. Discuss task mix and context; the pooled team figure is not a cross-type ranking.
4. Treat a cheaper model as a hypothesis. Compare similar work over finished periods, record task mix, acceptance criteria, pricing and capture, and inspect acceptance and repair evidence beside cost. A TIER change cannot establish causation; TIER does not credit merged work to a model or prove equal quality.

Honesty caveat. Yield reflects task mix and context, not raw talent. A senior on legacy work can show a lower lever than a junior on greenfield. Copy practices, never rank people. There is no absolute good/bad band (see docs/rubric.md).

In v0.7.0, monthly name-free comparisons publish only cache_read_share as a group lever, in group_levers[group_id]. Every shown group, including safe folds, needs k distinct counted people with spend and merged work. Any failing group withholds all levers over the population. The cache partition also needs k eligible positive-input contributors with cache reads and k without them. Bots, spend-only people, erased evidence, zero-input rows and multiple model rows cannot add seats. All population inputs remain in the pooled ratio. Mixed cached and uncached input belongs to the cache-read side. k is at least 3; withheld keys are absent. Premium-model and unattributed shares remain personal coaching-card levers. Archived raw windows and the synthetic live demo retain their original reports without group levers. v0.7.0 ships issued holder credentials and fail-closed view logging, plus the coaching card and raw-data retention; the separate per-issue report remains future work.

The before/after practice experiment

TIER serves closed UTC months on real servers: GET /api/v1/scores?period=YYYY-MM and GET /api/v1/scores/compare?period_a=YYYY-MM&period_b=YYYY-MM. Omit selectors for the latest close and, for comparison, its preceding calendar month. Other query parameters, including windows and work-type filters, return HTTP 400. Each month receives its own frozen census/complement decision, rather than an intersection population or a whole-response small-residual rule. Compare frozen price/rubric disclosures and work mix before interpreting a change.

Synthetic/offline raw-window comparisons retain deltas B − A and the unvalidated descriptive significant field. The following rolling-window example is for the synthetic demo only.

Worked example (synthetic demo only). Say the invented team adopted "cheaper model for routine refactors" on CHANGE_DATE. Point the command at the synthetic demo and compare the 8 days before against the 8 days after. The demo's merges sit 7 to 19 days before the day it started, so with that day as S, replace BEFORE_START with S minus 22 days, CHANGE_DATE with S minus 14 days and AFTER_END with S minus 6 days, all as UTC dates:

GET /api/v1/scores/compare?since_a=BEFORE_START&until_a=CHANGE_DATE\
&since_b=CHANGE_DATE&until_b=AFTER_END

# Synthetic demo only; TIER_HOST points at the running tierd demo.
curl -sS "$TIER_HOST/api/v1/scores/compare?since_a=BEFORE_START&until_a=CHANGE_DATE&since_b=CHANGE_DATE&until_b=AFTER_END"

Reading the result honestly is the whole point:

• Each row carries delta_tier, delta_weighted_points, delta_total_cost_usd, and a significant flag.
• significant is a legacy raw non-overlap result, retained for compatibility. It is true only for a developer present and above the floor in both windows with disjoint bounds and, in v0.6.1 (#1233), each row's own attributed-cost share at least 50%; false for withheld bounds. Neither value establishes an effect or a noise threshold. The API labels it unvalidated and the dashboard says “inference not established”, without interval-derived colours.
• In v0.6.1 (#1233), intervals are withheld below 50% of the row's own cost paired with resampled outcomes; exactly 50% passes. When shown they are labelled "excludes uncertainty from unattributed spend". Team and division rows carry none and reveal no floor status.
• Nominal 95% bounds. Coverage is unvalidated: in constructed tests where several outcomes share one issue, they covered the true value less often than 95%. They are descriptive resampling bounds and exclude uncertainty from unattributed spend, incorrect attribution and uncaptured usage.
• Treat a small difference as no evidence either way, and a large one as a prompt to investigate, not a measured effect.
• Watch the honest windowing skew too: a recent window B reads artificially low because cost books up front and outcomes land at merge time. See docs/interpreting-the-number.md before trusting a short after-window.

Real servers compare closed months:

GET /api/v1/scores/compare?period_a=2026-05&period_b=2026-06

Give both selectors or omit both to compare the latest close and its preceding UTC calendar month. Missing closes return 404; window parameters return 400. The response is {"compare":[...]} with A/B manifests. Inspect each manifest's published rows and comparison_withheld status; a missing group can reflect folding or withholding. No monthly significant verdict establishes an effect. See monthly score reads.

Capture the practice

TIER stores the numbers. Humans store the narrative. The learning does not live in the database -- it lives in the sentence a teammate can read next quarter and copy.

After the experiment, write the practice into the team's own shared doc or runbook -- not into TIER, which has no field for it. A good entry is four lines:

### Practice: cheaper model for routine refactors  (adopted 2026-06-01)
- Change: route bugfix/refactor sessions to the standard model; reserve the
  premium model for design and hard reasoning.
- Signal watched: the same subject’s own work-type trend on the coaching card;
  delta_total_cost_usd on /scores/compare (May vs June).
- Result: premium share fell and delta_tier was positive with significant:false
  after one month. This does not establish that the model change caused the
  difference or that the cheaper model did the work as well. Investigate task
  mix, acceptance, repair evidence, pricing and capture before interpreting it.
- Keep / drop: keep; revisit at the next levers retro.

That entry is what actually transfers between people. The TIER surfaces told you where to look and whether the move cleared noise; your runbook says what to do.

The playbook

For each work type, write down the task, the model/context practice tried, the acceptance criteria and the observation window. Start from an issue, keep the session scoped, reuse stable context, and check cost per outcome alongside n and its CI after two weeks. Keep security, incident, research and other work types separate. Copy the practice in a runbook, without another person's figure. This is the #420 practice playbook; it sets no individual goal or model-switch claim.

Coaching, not appraisal

TIER coaches the practice, not the person. The coaching card is built; release is gated on retention. A developer and authorized branch holders see the same card, with the same caveats. Today, coach from team rows, or preview the per-developer view in tierd demo.

• TIER is built for coaching, not for evaluating developers. Per-person figures are not accurate enough to judge an individual.
• Talk about the habit, not the number. A coaching conversation looks at the practice behind a number (cache reuse, which model for which job, spend with no issue attached), agrees one thing to try, and checks later whether it helped. The number is where the conversation starts, not a grade.
• Keep a developer's numbers between the developer and their manager (and a skip-level manager, if your organization uses one). The team retro uses only team numbers, which name nobody.
• Compare within a work type, never rank. Read a developer's numbers against their own trend within one work type, not against a teammate's.
• The honest caveat travels with every number. Yield reflects task mix and context, not raw talent.

TIER cannot enforce this. It shows numbers; it cannot stop someone from copying one into a review. Only your own written policy, or a works agreement where one applies, can. Write the purpose down before adopting named coaching with holder-key access.

v0.7.0 behavior. Real-data servers publish census-gated monthly groups and panels; named branch views and coaching cards follow holder scope. In the synthetic demo, any API or dashboard reader sees every invented developer's numbers in identifier order, never TIER order. The demo keeps its invented data.

Current access. Issued personal/upload keys bind ingestion to their holder. Root and dated branch node keys can read the holder’s figures; other holders cannot. Each named read logs before construction, and the person can inspect their own log. Cards need no declaration or positive-spend prerequisite. Writable servers run raw-data retention at startup and daily (90-day default, 60-day minimum, 365-day ceiling). See identity access for commands and restrictions. The monthly source stores per-person figures. Real writable servers run age-pruning independently of report presentation. Pruned named history cannot be restored by widening the window; a name-free roll-up remains. Raw webhook payloads have separate retention and are not rewritten by an erase (see privacy.md).

Deployments in co-determined jurisdictions have a legal reason for this too -- see docs/legal-and-privacy.md for works-council, DPIA, and GDPR Article 22 guidance. Name-free monthly comparisons retain a k-anonymity floor (default 5, minimum 3). Named reports remain available to authorized holders; there is no server-wide mode that disables them.

What NOT to do

Related

• docs/interpreting-the-number.md -- read the number honestly; the windowing skew.
• docs/legal-and-privacy.md -- the labor-law basis for keeping TIER out of appraisal.
• docs/api-compatibility.md -- the exact /scores and /scores/compare contract.
• docs/rubric.md -- why there is no absolute good/bad band.