--- name: timeback-analytics-alpha description: Use when building apps, reports, migration checks, QA probes, or deliverables against the TimeBack platform3 Analytics Alpha surface. The skill teaches agents to read report-ready derived facts: active/inactive/waste seconds, time windows, minutes per enrolled school day, XP totals, accuracy rollups, attempt counts, response latency, hint usage, mastery deltas, MAP RIT/Growth X, norms and R90 grade-position translations, actual course/grade-level progress, school-days remaining, and source-shaped TimeBack processed_facts imports by calling the live surface only. Do not compute minutes, school-day denominators, XP, accuracy, attempts, response latency, hint usage, mastery, MAP growth, Growth X, progress, dedupe, term parsing, norms/R90 lookup, calendar logic, or database joins locally. --- # TimeBack Analytics Alpha Use this skill when the user asks for a working app, Learning Report panel, closed-loop metric check, migration reconciliation, QA probe, or customer deliverable that needs report-ready derived learning facts from TimeBack platform3 Analytics Alpha. Do not use it for raw activity streams, durable Results state, Curriculum policy authoring, People and Orgs roster work, third-party app identity, or direct database access. ## Analytics In 60 Seconds Analytics is the derived-facts layer. Events records the moment. Results records durable outcomes and student state. Analytics writes typed derived facts when those sources close, then reports read those facts. Core Analytics objects: - event_time_fact: signed active_seconds, inactive_seconds, and waste_seconds contributions from closed Events. - time_window: active, inactive, waste, and display minutes by student, subject, and day/week/term/school-year/custom window. - school_day_minutes: active minutes divided by enrolled school days, with calendar and enrollment refs already applied. - xp_rollup: positive, negative, and net XP totals from the XP ledger under a named policy. - accuracy_rollup: correct, incorrect, total, and accuracy percent by day/week/term/window. - attempt_rollup: governed attempt_count and max_attempt_ordinal by day/week/term/window. - response_latency_rollup: governed response latency in milliseconds, including count, total, average, min, and max. - hint_usage_rollup: governed hint request, view, and used counts. - mastery_delta: changes in Results mastery state, keyed by student, KC, state dimension, and effective time. - map_growth_rollup: RIT, start RIT, observed growth, projected growth, Growth X, canonical conditional growth percentile, target, retake counts, and MAP source refs. `growth_percentile` is a compatibility alias for `conditional_growth_percentile`. - completion_rollup: actual course and grade-level progress; course rows use app-reported Caliper percent first, then XP remaining fallback, and grade-level rows average main courses only. - norms/R90 resources: versioned readable surface-owned NWEA norms and Alpha R90 tables plus percentile/RIT and RIT/grade translations. - school_days_remaining: forward instructional-day and effort projection read for GOALS-style target-date panels. - source_import: audit row for source-shaped TimeBack processed_facts import batches. Boundary rule: a derived rollup is not an event, not the gradebook, and not the current mastery state. Apps read Analytics. They do not rebuild Analytics. ## First Actions 1. Open the canonical docs before making claims: - Customer website: https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/customer_website - Data dictionary: https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/data_dictionary - Architecture decisions: https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/architecture - Approved integration gate: https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/integration 2. Use ANALYTICS_BASE_URL if credentials supply it. Otherwise use: https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/implementation/api 3. Choose the credential path: - Demo: call POST $ANALYTICS_BASE_URL/dev/mint?tenantId=demo, then use the returned bearer token. - Real or reviewer tenant: use the operator-supplied bearer token such as ANALYTICS_REVIEWER_JWT or ANALYTICS_TOKEN. Never print or commit tokens. 4. For a first read, call school-day-minutes for the demo student shown below and keep the canonical customer website endpoint list next to you. 5. For Learning Report panels or closed-loop metric checks, read references/report-recipes.md and call the smallest Analytics endpoint that already returns the requested fact. 6. To prove the pack is asking the platform correctly, run node checks/verify-skill-pack.mjs or read references/runnable-check.md. 7. Before final output, read references/leak-check.md and confirm the binary leak check passes. ## Happy Path: Build One Student's Analytics Report export ANALYTICS_BASE_URL="https://platform3-andymontgomery-9773s-projects.vercel.app/analytics/alpha/implementation/api" TOKEN_JSON=$(curl -fsS -X POST "$ANALYTICS_BASE_URL/dev/mint?tenantId=demo") ANALYTICS_TOKEN=$(printf '%s' "$TOKEN_JSON" | node -e 'let s="";process.stdin.on("data",d=>s+=d);process.stdin.on("end",()=>process.stdout.write(JSON.parse(s).token))') curl -fsS "$ANALYTICS_BASE_URL/alpha/analytics/v1/school-day-minutes?studentId=student_01HT7G3YZV7QB5N4YKQ1K0Z9A9&subjectId=math&startDate=2026-05-01&endDate=2026-06-01" \ -H "Authorization: Bearer $ANALYTICS_TOKEN" \ -H "X-Timeback-Tenant: demo" Then call XP, accuracy, attempt, response-latency, hint-usage, mastery-delta, MAP-growth, and completion rollups with the recipes in references/report-recipes.md. Render the returned fields. Do not recompute them. To prove current demo values, run the verifier; it fetches the approved integration convergence answer key live and compares live API rows to those platform-owned answers. ## API Perimeter Public Analytics Alpha endpoints: POST /dev/mint GET /alpha/analytics/v1/event-time-facts GET /alpha/analytics/v1/time-windows GET /alpha/analytics/v1/school-day-minutes GET /alpha/analytics/v1/xp-rollups GET /alpha/analytics/v1/accuracy-rollups GET /alpha/analytics/v1/attempt-rollups GET /alpha/analytics/v1/response-latency-rollups GET /alpha/analytics/v1/hint-usage-rollups GET /alpha/analytics/v1/mastery-deltas GET /alpha/analytics/v1/map-growth-rollups GET /alpha/analytics/v1/completion-rollups GET /alpha/analytics/v1/source-imports GET /alpha/analytics/v1/norms GET /alpha/analytics/v1/norms/table GET /alpha/analytics/v1/norms/rit GET /alpha/analytics/v1/norms/percentile GET /alpha/analytics/v1/r90 GET /alpha/analytics/v1/r90/table GET /alpha/analytics/v1/rit-to-grade GET /alpha/analytics/v1/rit-to-grade/table GET /alpha/analytics/v1/school-days-remaining GET /alpha/analytics/v1/grade-level-status POST /alpha/analytics/v1/source-imports/timeback-xp-time-accuracy POST /alpha/analytics/v1/source-imports/timeback-map POST /alpha/analytics/v1/source-imports/timeback-grade-mastery POST /alpha/analytics/v1/source-imports/timeback-completion POST /alpha/analytics/v1/source-imports/migration-reconcile Use Authorization: Bearer on every non-mint call. Use X-Timeback-Tenant when credentials or examples name a tenant. Use Idempotency-Key on source imports. ## Non-Negotiables Treat these as binary rules: - Do not parse raw Caliper Events or TimeBack processed_facts to classify time. Use event_time_fact or time_window. - Do not intersect activity with school calendars or enrollment windows. Use school_day_minutes. - Do not compute active minutes per enrolled school day. Read minutes_per_enrolled_school_day. - Do not treat school_day_minutes audit/repair rows as report answers. Default reads return only canonical report-subject rows with null_reason=none and non-null minutes_per_enrolled_school_day; use includeUnavailable=true only for source_missing, policy_pending, subject_id=null, or impossible minutes/day repair inspection. - Do not compute XP awards, penalties, repeat discounts, or reversals. Use xp_rollup or Results XP ledger when ledger history is the requested fact. - Do not compute mastery, decay, confidence, or state transitions. Use mastery_delta for changes and Results for current state. - Do not compute accuracy from raw question rows. Use accuracy_rollup. - Do not choose a MAP test of record, unpivot goals, ship private norms tables, switch over growth-window columns, parse term strings, or compute Growth X. Use map_growth_rollup. - Do not maintain a local norms or R90 table. Call norms/rit, norms/percentile, r90, or read the surface's versioned norms/table and r90/table resources by table_version. R90 percent fields are MAP-inferred grade-band position, not actual progress. - Do not count remaining school days or convert XP-to-time effort locally. Use school_days_remaining. - Do not derive actual progress from MAP/RIT/R90, walk Curriculum trees, or count Results rows. Use completion_rollup. - Do not parse student ids, subjects, app names, terms, or policy refs from free text. Use typed filters and returned fields. - Do not read Supabase, Postgres, implementation source, Events raw payloads, Results raw records, private logs, or JWT contents for a user-facing workflow. - Do not store bearer tokens, student credentials, raw producer payloads, or derived Analytics rows in local app data. Browser UI preferences are acceptable. - Do not create a second cache of Analytics facts. The surface is the store. If the user job needs one of those missing primitives, stop and report a surface gap. Do not work around the gap with private code. ## Common Build Pattern 1. Mint or accept credentials. 2. Read the descriptor and canonical docs. 3. Pick the smallest endpoint that already returns the requested fact. 4. Pass typed filters such as studentId, subjectId, startDate, endDate, asOf, windowKind, factKind, stateDimension, termId, growthWindow, normsSet, role, grade, season, percentile, rit, completionScope, scopeId, modifiedSince, limit, and cursor. 5. Render only fields returned by the surface. 6. Preserve Problem JSON when calls fail. 7. For imports, send source-shaped rows to the matching source-import adapter with Idempotency-Key, then verify materialized rows by reading Analytics endpoints. Use source-imports/timeback-xp-time-accuracy for TimeBack processed_facts rows that carry time, XP, and accuracy facts. 8. Run the leak check before final output. ## Reference Files - references/canonical-surface.md: endpoint, credential, filter, object, and boundary details. - references/report-recipes.md: Learning Report and metric-check calls. - references/worked-example.md: copy-paste demo workflow. - references/source-shaped-import.md: source-shaped processed_facts import workflow. - references/runnable-check.md: shortest proof command. - references/leak-check.md: binary no-platform-work checklist. - references/response-samples.md: representative surface responses. - checks/expected.json: verifier config with selectors, row ids, endpoint perimeter, source-import proof config, and the live convergence answer-key URL. It is not a local answer table for the Learning Report panels. - checks/verify-skill-pack.mjs: HTTP-only verifier that fetches the approved integration convergence key live, calls Analytics, and compares surface responses to the platform-owned answers. ## Expected Output Quality Every output should make platform3 more useful than a generic agent: - It should run against the live Analytics Alpha API, not a mock. - It should cite the canonical docs it used. - It should include exact API calls or response evidence. - It should preserve typed Problem JSON when calls fail. - It should disclose any missing surface primitive instead of hiding it.