---
name: timeback-results-alpha
description: Use when building apps, reports, QA probes, migration checks, or deliverables against the TimeBack platform3 Results Alpha surface. Covers settled outcomes, test-result hierarchy, AI grading audit, MAP scores, Learning Report sections, group Growth X, percentile/RIT and R90 reads, academic records/transcripts, report cards, gate passes, working grade, mastery-pure grades mastered YTD, explicitly non-grades-mastered MAP placement delta, four-state KC state, track state, next-task decisions, XP ledger, and content effectiveness by calling the live surface only. Do not use for generic MAP analysis, direct NWEA CDF processing, OneRoster/QTI/Events/Content/People/Curriculum jobs, direct database access, private grader-log scraping, or local norms, dedupe, growth math, mastery decay, task ranking, XP math, content counters, reconciliation, or transcript source-precedence logic.
---

# TimeBack Results Alpha

Use this skill when the user asks for a working app, report, integration proof, QA probe, migration reconciliation, or customer deliverable that uses the TimeBack platform3 Results Alpha surface.

Do not use it for generic MAP analysis, direct NWEA CDF processing, OneRoster gradebook work, QTI scoring, Events, Content, People & Orgs, Curriculum, or direct database access.

## Results In 60 Seconds

Results is the record plus the student's knowledge graph. It holds settled, durable statements about how one specific student is doing.

Core Results objects:

- `result_record`: settled outcome for one student on one work item or assessment.
- QTI-backed `result_record` rows preserve `qti_attempt_id` plus typed administration, delivery-session, QTI test/version, Content `test_spec`, and `test_kind` references. Use the exact `qtiAttemptId` read for AttemptReport/mastery-gate work.
- `test_result_component`: first-class test, section, part, and question_response rows for a stored test result. The client never parses `canonical_response` JSON to rebuild the hierarchy.
- `missed-item-kc-attribution`: result-scoped incorrect question responses joined at read time to Content-owned active `content_kc_tag` rows. Missing item links stay explicit; the client never substitutes the entire gate scope.
- `ai_grading_audit`: model, prompt hash, revision, status, and override audit rows for overall and question-level AI feedback. The client never scrapes private grader logs or result JSON for AI provenance.
- `student_kc_state`: per-student KC state with four separate fields: `initial_mastery`, `current_retention`, `durable_mastery`, and `fluency_state`. The client never blends them.
- `student_track_state`: one student's current track, track level, segment, placement evidence, status, and switch history. The client never copies Curriculum track definitions.
- `next_task`: the surface-selected typed task ref for what a student should do next. Apps render it; they never rank lessons, reviews, practice, or gate retries.
- `xp_ledger`: immutable awarded-XP history. Results computes awards, discounts, penalties, and reversals; apps display rows.
- `content_effectiveness`: Results-derived rollup for Content items with `validated_by_count`, `failed_by_count`, and `effectiveness_rate`. Apps never increment counters.
- `map_score`: current MAP test-of-record score keyed by TimeBack student id.
- `map_sitting`: ordinary reads return the selected sitting without source/deletion evidence; `sittingScope=all` requires ordinary read authority plus the exact `results:audit` scope and returns bounded audit fields. Roles and `results:*` do not substitute.
- `map_goal_strand`: clean per-strand MAP rows. The client never unpivots Goal1..Goal5 columns.
- `map_growth_window`: typed observed/projected growth row with surface-owned Growth X fields.
- `map_percentile_translation`: surface-owned percentile-to-RIT and RIT-to-percentile translations using the requested norms set.
- `map_r90_norm_point`: legacy Results MAP report fixture rows. These are not the GOALS RIT->grade source; for grade2RIT/R90 use the skill-seeded NWEAMAP master directly or through the Analytics mirror. The client never ships a local R90 table.
- `report_group_growth_x`: group Growth X report that averages each student's ratio on the surface. The client never divides total observed by total projected.
- `working_grade` and `advancement`: the grade-movement read model. For grades mastered, call `/grades-mastered` and read mastery-pure `grades_mastered_sytd`. `map_baseline_grade_delta_not_grades_mastered` is placement/reporting context only. `/advancement` and `advancement_value` are deprecated aliases to `grades_mastered_sytd` only.
- `academic_record_view`, `course_transcript_view`, `course_grade_view`, and `transcript_result_view`: read-only settled transcript facts. The client never parses Ed-Fi payload JSON or resolves source precedence.
- `report_card_entry` and `gate_pass`: durable report statements and mastery-gate decisions.
- `report_*` views: report-ready rows for MAP quadrants, retake audit, growth over time, norms isolation, growth breakdown, student-progress animation, closed-loop reconciliation, Learning Report proof rows, and answer keys.

Boundary rule: Events records moments, Content holds blank instruments, Curriculum holds the shared graph, and Results holds settled outcomes plus the per-student mastery overlay. Mastery is never a field on the student record.

`grading_stage` is a row-level field, not a distinct-value summary. When reporting an AI grading revision history, preserve one entry per returned audit row and keep repeated stage values: an original overall row and its human-override revision are two separate `overall` entries. Use `ai_grading_audit_id`, `grading_status`, `revision_number`, and `supersedes_ai_grading_audit_id` to prove the chain; never deduplicate audit rows by stage.

## First Actions

1. Open the canonical docs before making claims:
   - Customer website: https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/customer_website
   - Data dictionary: https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/data_dictionary
   - Architecture decisions: https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/architecture
   - Implementation API: https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/implementation/api
   - Surface QC: https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/surface_qc
   - Integration proof: https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/integration
2. Use `RESULTS_BASE_URL` if credentials supply it. Otherwise use:
   `https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/implementation/api`
3. Choose the credential path:
   - Demo: call `POST $RESULTS_BASE_URL/dev/mint?tenantId=demo`, then use the returned bearer token.
   - Real or reviewer tenant: use the operator-supplied bearer token such as `RESULTS_REVIEWER_JWT`. Never print or commit tokens.
4. Read the descriptor by calling the base URL exactly as configured: `curl "$RESULTS_BASE_URL"`. Do not add a trailing slash to the base implementation URL.
5. For freshness, use `modifiedSince` plus returned cursors with the cadence in `references/canonical-surface.md#poll-cadence-and-backoff`. Results Alpha has no webhook, SSE, push, or notifications subscription surface today.
6. For the per-student Learning Report (placement and progress, course completion, MAP results, grade levels mastered, XP goals, time commitment, and accuracy), MAP Quadrants, retakes, growth-over-time, norms-isolation, growth-breakdown, group Growth X, percentile/RIT translation, legacy R90 norm-point fixtures, student-progress-animation, closed-loop reports, XP goal/progress evidence, four-state KC state, track state, next task, XP ledger, or content effectiveness, read `references/report-recipes.md` and call the report-ready endpoints. For GOALS RIT->grade, use the skill-seeded NWEAMAP R90 surface or Analytics mirror, not Results fixtures. Do not compute report cells, goal projections, time totals, XP awards, MAP translations, or student state.
7. To prove the pack is asking the platform correctly, run `node checks/verify-skill-pack.mjs` or read `references/runnable-check.md` and run the answer-key comparison.
8. Before final output, read `references/leak-check.md` and confirm the binary leak check passes.

## Happy Path: Regenerate MAP Reports

```sh
export RESULTS_BASE_URL="${RESULTS_BASE_URL:-https://platform3-andymontgomery-9773s-projects.vercel.app/results/alpha/implementation/api}"
export RESULTS_TOKEN="${RESULTS_TOKEN:-$(curl -fsS -X POST "$RESULTS_BASE_URL/dev/mint?tenantId=demo" | jq -r '.token')}"
export COMMON="subject=math&canonicalTermId=term_2025_26_spring&growthWindow=fall_to_spring&normsSet=2025"

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/map-quadrants?$COMMON" \
  -H "Authorization: Bearer $RESULTS_TOKEN" | jq '{count,hash:.meta.resultHash,data:.data}'

curl -fsS "$RESULTS_BASE_URL/alpha/results/v1/reports/answer-key?normsSet=2025" \
  -H "Authorization: Bearer $RESULTS_TOKEN" | jq '.data[] | select(.example_id=="map_quadrants_2025_math_demo")'
```

To rerun under 2020 norms, change only `normsSet=2020`. Do not switch columns, parse terms, or load a norms table.

## API Perimeter

The root descriptor is the configured base URL with no extra path, for example `curl "$RESULTS_BASE_URL"`. The live descriptor currently advertises 53 endpoint entries, verified from `descriptor.body.endpoints.length`:

```text
POST /dev/mint?tenantId=demo
GET  /alpha/results/v1/result-records
GET  /alpha/results/v1/result-records/{resultRecordId}
GET  /alpha/results/v1/test-result-components
GET  /alpha/results/v1/missed-item-kc-attribution?resultRecordId={resultRecordId}
GET  /alpha/results/v1/ai-grading-audit
GET  /alpha/results/v1/students/{studentId}/results
GET  /alpha/results/v1/students/{studentId}/test-result-components
GET  /alpha/results/v1/students/{studentId}/ai-grading-audit
GET  /alpha/results/v1/assessment-finalizations
GET  /alpha/results/v1/students/{studentId}/assessment-finalizations
GET  /alpha/results/v1/students/{studentId}/kc-state
GET  /alpha/results/v1/students/{studentId}/track-state
GET  /alpha/results/v1/next-task
GET  /alpha/results/v1/students/{studentId}/xp-ledger
GET  /alpha/results/v1/content-effectiveness
GET  /alpha/results/v1/item-calibrations
GET  /alpha/results/v1/source-adapters
GET  /alpha/results/v1/policy-config
GET  /alpha/results/v1/academic-records
GET  /alpha/results/v1/course-transcripts
GET  /alpha/results/v1/course-grades
GET  /alpha/results/v1/transcript-results
GET  /alpha/results/v1/students/{studentId}/map-scores
GET  /alpha/results/v1/students/{studentId}/map-sittings
GET  /alpha/results/v1/students/{studentId}/current-map
GET  /alpha/results/v1/students/{studentId}/map-goal-strands
GET  /alpha/results/v1/students/{studentId}/growth-windows
GET  /alpha/results/v1/map-percentile-translations
GET  /alpha/results/v1/map-r90-norm-points
GET  /alpha/results/v1/students/{studentId}/highest-mastered-grade
GET  /alpha/results/v1/students/{studentId}/working-grade
GET  /alpha/results/v1/students/{studentId}/grades-mastered
GET  /alpha/results/v1/students/{studentId}/advancement
GET  /alpha/results/v1/students/{studentId}/course-progress
GET  /alpha/results/v1/students/{studentId}/grade-level-progress
GET  /alpha/results/v1/students/{studentId}/report-card
GET  /alpha/results/v1/students/{studentId}/gate-passes
POST /alpha/results/v1/assessment-finalizations/finalize
POST /alpha/results/v1/component-xp-awards
POST /alpha/results/v1/imports
GET  /alpha/results/v1/imports/{importId}
POST /alpha/results/v1/result-records
PATCH /alpha/results/v1/result-records/{resultRecordId}
GET  /alpha/results/v1/reports/map-quadrants
GET  /alpha/results/v1/reports/retake-audit
GET  /alpha/results/v1/reports/growth-over-time
GET  /alpha/results/v1/reports/norms-isolation
GET  /alpha/results/v1/reports/growth-breakdown
GET  /alpha/results/v1/reports/group-growth-x
GET  /alpha/results/v1/reports/student-progress-animation
GET  /alpha/results/v1/reports/closed-loop-reconciliation
GET  /alpha/results/v1/reports/answer-key
```

Use `Authorization: Bearer <token>` on every non-mint call. Use `Idempotency-Key` on writes. Use the ETag from the prior detail read in `If-Match` for PATCH corrections.

Write vocabulary: `POST /alpha/results/v1/result-records` accepts only `self_paced`, `external_assessment`, `learning_app_outcome`, `legacy_assessment`, and `question_result`. Adapter-owned kinds `map`, `mastery_gate`, `mastery_visibility`, and `gradebook` are written only through `POST /alpha/results/v1/imports` with source-shaped rows; placement/test-out attempts finalize through `POST /alpha/results/v1/assessment-finalizations/finalize`; do not invent local `result_kind` values or compute pass/fail locally.

## Non-Negotiables

Treat these as binary rules:

- Do not bundle a norms table.
- Do not choose a MAP test of record locally. Use `sittingScope=test_of_record` or report-ready views.
- Do not unpivot NWEA Goal1..Goal5 columns locally. Use `map-goal-strands`.
- Do not switch over growth-window column names. Use typed `growthWindow` and returned `growth_window`.
- Do not parse term strings, student emails, assessment names, URLs, or free text to recover typed fields.
- Do not parse `canonical_response` JSON to reconstruct a test result. Use `test-result-components` for test, section, part, and question_response rows.
- Do not infer a missed question's KCs from the gate scope, form title, question order, or raw QTI. Use `missed-item-kc-attribution?resultRecordId=...` and require `attribution_ready=true` before per-KC routing.
- Do not scan result records, treat `producer_result_id` as a QTI attempt key, or keep a shadow correlation table. Call `GET /alpha/results/v1/result-records?qtiAttemptId=...` and require `results.qti_attempt_result.v1`.
- Do not scrape private AI grader logs or result JSON to answer which model/prompt produced feedback. Use `ai-grading-audit`.
- Do not compute Growth X, group Growth X, projected growth, percentile-to-RIT, RIT-to-percentile, RIT50/RIT90, effective grade, working grade, either named grade-movement metric, 99-levels, or intervention flags.
- Do not parse Ed-Fi payload JSON or decide academic-record/transcript source precedence locally. Use ordinary transcript fields; request bounded `source_evidence` only with `includeSourceEvidence=true`, ordinary read authority, and the exact `results:audit` scope.
- Do not blend `initial_mastery`, `current_retention`, `durable_mastery`, and `fluency_state`; read all four fields separately from `student_kc_state`.
- Do not compute mastery state, confidence, evidence counts, decay, or report-card rollups.
- Do not choose a student's next task locally. Use `GET /alpha/results/v1/next-task`.
- Do not adjudicate placement/test-out attempts locally. Submit the full active attempt set to `POST /alpha/results/v1/assessment-finalizations/finalize` and read the returned finalization.
- Do not compute XP awards, repeat-attempt discounts, effort bonuses, passive-activity verification, penalties, or reversals. Use `xp-ledger`.
- Do not compute XP-goal remaining work, hours-to-target, target dates, or goal-projection fields locally. Use returned `growth-windows`, `growth-breakdown`, `working-grade`, `grades-mastered`, and `xp-ledger` fields; if a combined GOALS projection field is missing, report a surface gap.
- Do not increment or recompute content effectiveness counters. Use `content-effectiveness`.
- Do not copy Curriculum track, track level, segment, course, or component definitions into Results apps. Use `track-state` for the student's state and Curriculum for definitions.
- Do not reconstruct closed-loop reconciliation, minutes, RIT, Growth X, group Growth X, or mastery comparisons in client code.
- Do not read `nweamap.*`, `oneroster.*`, Supabase, Postgres, implementation source, or private logs for a user-facing workflow.
- Do not store bearer tokens, student app credentials, source secrets, or raw producer payloads in app data.
- Do not create local persistence for Results domain data. Browser UI preferences are acceptable; surface-shaped data belongs in the surface.

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 or report.
4. Pass typed filters: `studentId`, `courseId`, `subject`, `canonicalTermId`, `growthWindow`, `normsSet`, `gradeLevel`, `termSeason`, `translationDirection`, `inputPercentile`, `inputRit`, `groupDimension`, `asOfDate`, `sittingScope`, `includeSourceEvidence`, `trackId`, `taskType`, `contentId`, `kcId`, `xpAwardReason`, or `modifiedSince`.
5. Render only fields returned by the surface.
6. For writes, use `Idempotency-Key`; for corrections, read detail first and send that ETag as `If-Match`.
7. Verify report examples with `/reports/answer-key` rather than embedded hashes.
8. Run the leak check before final output.

## Reference Files

- Read `references/canonical-surface.md` for endpoint, credential, filter, header, scope, and boundary details.
- Read `references/report-recipes.md` for report-ready calls that regenerate the per-student Learning Report (placement and progress, course completion, MAP results, grade levels mastered, XP goals, time commitment, and accuracy), MAP Quadrants, retake audit, growth over time, norms isolation, growth breakdown, group Growth X, percentile/RIT translation, legacy R90 norm-point fixtures, student-progress animation, XP goal/progress evidence, and closed-loop views. Use NWEAMAP/Analytics for GOALS grade2RIT/R90.
- Read `references/worked-example.md` for a runnable demo workflow that verifies surface-owned answer keys.
- Read `references/runnable-check.md` when you need the shortest copy-paste proof that the pack reproduces platform-owned answers.
- Run `node checks/verify-skill-pack.mjs` for the packaged verifier. It only performs HTTP calls and compares surface-returned facts to surface-owned answer keys.
- Read `references/leak-check.md` before shipping an app, report, QA probe, migration check, or deliverable.

## Expected Output Quality

Every output should make platform3 more useful than a generic agent:

- It should run against the live Results Alpha API, not a mock.
- It should include exact API calls or response evidence.
- It should name which canonical docs it used.
- It should preserve Problem JSON when calls fail.
- It should disclose any missing surface primitive instead of hiding it.