wiki content export 2026-03-24

content/wiki/hub/reference/00-application-status-reference.md

@@ -0,0 +1,66 @@
+# Application Status Reference
+
+Every application moves through a defined set of statuses as it progresses from submission to final outcome. This page documents each status, what it means, and the valid transitions between them.
+
+## Status Definitions
+
+**`new`** -- Application recently submitted. This is the starting status for every application that comes in through the apply form.
+
+**`waiting_first_round`** -- Waiting to be scheduled for a first-round interview. The application has been advanced from its initial review stage into the first-round interview stage but does not yet have an interview booked.
+
+**`first_round_scheduled`** -- First-round interview has been scheduled. Set automatically when a Cal.com booking webhook matches the applicant's email, or when an admin manually changes the status.
+
+**`needs_first_decision`** -- First round complete, awaiting a decision. Set automatically when an admin locks the first-round stage (all completed reviews must be locked and the minimum reviewer threshold met).
+
+**`waiting_second_round`** -- Waiting to be scheduled for a second-round interview. The committee decided to advance the application past the first round into a second-round stage.
+
+**`second_round_scheduled`** -- Second-round interview has been scheduled. Same mechanism as first round -- triggered by a Cal.com webhook match or manual status change.
+
+**`needs_final_decision`** -- Second round complete, awaiting final decision. Set automatically when the final stage is locked.
+
+**`accepted`** -- Application accepted into the cohort. Terminal status.
+
+**`waitlist`** -- Application waitlisted. Can still transition to `accepted` or `declined`.
+
+**`declined`** -- Application declined. Terminal status.
+
+## Valid Transitions
+
+Each status can only move to specific next statuses. The system enforces these rules and rejects invalid transitions.
+
+- `new` → `waiting_first_round`, `first_round_scheduled`, `declined`
+- `waiting_first_round` → `first_round_scheduled`, `waiting_second_round`, `declined`
+- `first_round_scheduled` → `needs_first_decision`, `waiting_first_round`, `declined`
+- `needs_first_decision` → `waiting_second_round`, `accepted`, `waitlist`, `declined`
+- `waiting_second_round` → `second_round_scheduled`, `accepted`, `waitlist`, `declined`
+- `second_round_scheduled` → `needs_final_decision`, `waiting_second_round`, `declined`
+- `needs_final_decision` → `accepted`, `waitlist`, `declined`
+- `accepted` → (none -- terminal)
+- `waitlist` → `accepted`, `declined`
+- `declined` → (none -- terminal)
+
+## What Triggers Transitions
+
+**Automatic transitions:**
+
+- **Stage locking** sets `needs_first_decision` or `needs_final_decision` depending on whether the locked stage is the final stage or a first-round stage.
+- **Advancing to next stage** sets `waiting_first_round` or `waiting_second_round` based on the next stage's type. If an interview is already scheduled for that round, the status skips directly to `first_round_scheduled` or `second_round_scheduled`.
+- **Cal.com webhooks** move an application from `waiting_first_round` to `first_round_scheduled` (or the second-round equivalent) when a booking is created.
+
+**Manual transitions:**
+
+- Admins can change any application's status through the **Applications** tab, provided the transition is valid.
+- Bulk status changes are available for processing multiple applications at once.
+- The **Decisions** tab records accept, waitlist, or decline decisions and updates the status accordingly.
+
+:::info
+An application can be declined from almost any active status. The `waitlist` status is the only non-terminal outcome status -- waitlisted applications can still be accepted or declined later.
+:::
+
+## Status Groups
+
+The system groups statuses for filtering:
+
+- **Active:** `new`, `waiting_first_round`, `first_round_scheduled`, `needs_first_decision`, `waiting_second_round`, `second_round_scheduled`, `needs_final_decision`
+- **Decision pending:** `needs_first_decision`, `needs_final_decision`
+- **Terminal:** `accepted`, `waitlist`, `declined`

content/wiki/hub/reference/01-rubric-and-scoring-details.md

@@ -0,0 +1,74 @@
+# Rubric & Scoring Details
+
+This page covers how scoring works end to end in Cohort-OS -- from how rubrics are structured, through per-criterion scoring by individual reviewers, to how consensus scores are calculated across the review panel.
+
+## Rubric Structure
+
+Rubrics are defined in Flywheel (the external assessment engine) and linked to each review stage. A rubric contains:
+
+- **Criteria** -- The individual dimensions being evaluated (e.g., "Mission Alignment", "Governance Readiness"). Each criterion has a name, description, and maximum point value.
+- **Thresholds** (or levels) -- Descriptive scoring bands within each criterion. Each threshold has a title, a description of what that performance level looks like, and a point range. Reviewers select the threshold that best matches the applicant.
+- **Max points** -- Each criterion defines its own maximum score (commonly 5 points). The rubric's total possible score is the sum of all criteria max points.
+
+Each review stage in a cohort is linked to a specific Flywheel rubric via the stage's configuration. Different stages can use different rubrics.
+
+## How Reviewers Score
+
+Reviewers use the **guided scoring interface** to evaluate applications criterion by criterion. For each criterion:
+
+1. Read the criterion description and the applicant's relevant answers (shown side by side).
+2. Select a threshold/level that matches the applicant's response. Selecting a threshold automatically assigns the corresponding point value.
+3. Optionally add notes specific to that criterion.
+4. All criteria must be scored before proceeding to the recommendation step.
+
+After scoring all criteria, the reviewer sees their total score (sum of all criterion scores) and percentage (total divided by maximum possible), then selects a recommendation and writes overall notes.
+
+:::info
+If a rubric does not have thresholds configured in Flywheel, reviewers see simple numeric score buttons (1 through the max points) instead of descriptive threshold options.
+:::
+
+## Individual Review Scores
+
+Each completed review stores:
+
+- **Per-criterion scores** -- The point value and max value for each criterion, plus optional notes.
+- **Total score** -- Sum of all criterion scores.
+- **Percentage** -- Total score divided by total max points, expressed as a percentage.
+- **Recommendation** -- One of `advance`, `reject`, `hold`, or `undecided`.
+- **Overall notes** -- Free-text assessment from the reviewer.
+
+A review starts as `draft` (editable, can be saved and returned to) and becomes `completed` when submitted. Submitting locks the scores and notes. The recommendation can still be changed after submission with a recorded reason.
+
+## Consensus Calculation
+
+When multiple reviewers have completed their reviews for the same application and stage, the consensus view aggregates their scores. The consensus endpoint calculates:
+
+- **Average score** -- Mean of all reviewers' total scores.
+- **Average percentage** -- Mean of all reviewers' percentage scores.
+- **Per-criterion averages** -- For each criterion, the mean score across all reviewers.
+- **Score spread** -- The difference between the highest and lowest score for each criterion. A criterion is **flagged** when the spread is 2 or more points, or 40% or more of the max points. Flagged criteria indicate significant disagreement between reviewers.
+- **Recommendation tally** -- Count of advance, hold, reject, and undecided recommendations.
+
+:::warning
+Only completed reviews with `review` permission are included in consensus calculations. View-only assignments and draft reviews are excluded.
+:::
+
+## Grade Bands
+
+Cohorts can define grade bands that map percentage ranges to letter grades:
+
+| Band | Range | Label |
+|------|-------|-------|
+| A | 90-100% | Exceptional |
+| B | 80-89% | Strong |
+| C | 70-79% | Good |
+| D | 60-69% | Acceptable |
+| F | 0-59% | Needs Work |
+
+Grade bands are configured per cohort in the Flywheel integration settings. They provide a quick way to categorize application strength during committee discussions.
+
+## Blind Review
+
+When **blind review** is enabled on a stage (the default), reviewer identities are hidden from other reviewers viewing the consensus. Reviewers appear as "Reviewer 1", "Reviewer 2", etc. Admins always see full reviewer names and emails regardless of the blind review setting.
+
+Blind review affects the consensus view only -- it does not change what reviewers see while scoring. Each reviewer always scores independently without seeing other reviewers' scores until their own review is submitted.

content/wiki/hub/reference/02-glossary.md

@@ -0,0 +1,43 @@
+# Glossary
+
+Key terms used throughout Cohort-OS and this documentation.
+
+---
+
+**Blind review** -- A stage setting that hides reviewer identities from other reviewers when viewing consensus scores. Reviewers appear as "Reviewer 1", "Reviewer 2", etc. Admins always see full names regardless of this setting. Enabled by default on all stages.
+
+**Cohort** -- A group of applicants going through a selection process together. Each cohort has its own application form, review stages, reviewers, and decisions. Cohorts move through lifecycle statuses: `draft`, `review`, `decide`, `onboard`, `active`, `closed`.
+
+**Cohort admin** -- A user with the `cohortadmin` role. Can manage applications, assign reviewers, configure stages, make decisions, and send notifications for cohorts they have access to. Cannot manage organization-level settings or users.
+
+**Consensus** -- The aggregated view of all completed reviews for a single application within a stage. Shows average scores per criterion, overall averages, score spread, and a tally of reviewer recommendations. Used by admins and committees to inform decisions.
+
+**Criterion** -- A single dimension of evaluation within a rubric (e.g., "Mission Alignment", "Governance Readiness"). Each criterion has a name, description, maximum point value, and optional scoring thresholds that describe what each performance level looks like.
+
+**Decision** -- The final outcome recorded for an application: `accepted`, `waitlist`, or `declined`. Decisions include a rationale, rationale code, and optional committee notes. Recorded in the **Decisions** tab.
+
+**Flywheel** -- The external assessment engine that Cohort-OS integrates with. Flywheel provides rubrics (scoring criteria and thresholds), surveys (application form question sets), and reporting capabilities. Rubrics are authored in Flywheel and linked to review stages in Cohort-OS.
+
+**Ghostie** -- The avatar system in Cohort-OS. Each user chooses a ghostie -- a small ghost illustration defined by an expression (sweet, mild, exasperated, wtf, disbelieving, double-take) and a body color (from presets or a custom color picker). Ghosties appear on user profile circles throughout the app.
+
+**Guided scoring** -- The primary review interface where reviewers score applications criterion by criterion. In focused mode, one criterion is shown at a time with the applicant's answers alongside. In "show all" mode, every criterion is visible at once. After scoring all criteria, reviewers proceed to the recommendation step.
+
+**Org** -- Short for organization. The top-level entity that owns cohorts, users, and settings. Users can belong to multiple orgs via org memberships. All data is scoped to an org.
+
+**Orgadmin** -- A user with the `orgadmin` role for an organization. Full management access: can manage users, cohorts, settings, and view the activity feed. Can do everything a cohort admin can, plus organization-level administration.
+
+**Orphaned interview** -- A Cal.com booking that could not be automatically matched to an application. This happens when the email on the booking does not match any applicant's contact email in the cohort. Orphaned interviews appear in a modal accessible from the **Applications** tab, where an admin can manually match them to the correct application or dismiss them.
+
+**Permission (view/review)** -- The access level assigned to a reviewer for a specific application. `review` permission allows the reviewer to score the application and submit a review. `view` permission gives read-only access to the application data without the ability to score. View-only reviews are excluded from consensus calculations.
+
+**Rationale code** -- A short code attached to a decision that categorizes the reasoning (e.g., `manual_accept`). Used alongside the free-text rationale to provide structured data about why a decision was made.
+
+**Recommendation** -- A reviewer's suggested outcome for an application, selected after scoring. Four options: **advance** (move to the next stage), **reject** (decline the application), **hold** (flag for further committee discussion), **undecided** (no recommendation yet). Recommendations inform but do not determine the final decision. Reviewers can change their recommendation after submission by providing a reason.
+
+**Reviewer** -- A user assigned to evaluate applications. Reviewers are first added to a cohort's reviewer pool, then assigned to specific applications with either `view` or `review` permission. Reviewers access their assignments through the review dashboard and score applications using the guided scoring interface.
+
+**Rubric** -- A structured scoring framework defined in Flywheel and linked to a review stage. Contains multiple criteria, each with descriptive thresholds/levels. Rubrics standardize evaluation so all reviewers assess applications against the same dimensions.
+
+**Self-assessment** -- A survey sent to members of an applicant's team (e.g., studio members). Each team member receives a unique token-based link that does not require login. Admins can track completion status, resend emails, and view responses. Self-assessment data is available to second-round reviewers during scoring.
+
+**Stage** -- A phase within a cohort's review process. Common stage types are `application-reviews` (initial paper review), `first-round` (first interview round), and `second-round` (second interview round). Each stage has its own rubric, reviewer settings (minimum/maximum reviewers, blind review, self-review), and status. Stages are ordered sequentially and applications advance through them.