Capablio

Handbook

Data contract

Two JSON artifacts are produced by the pipeline. Both use "schema_version": 1.

Updated

data.json (parse stage)

Written by feedback360.parse_360.parse(). Top-level object:

Field Type Description
schema_version int Always 1.
subject string Feedback recipient name from the Thomas PDF cover.
sources object thomas_pdf path string; snapshot_pdf path or omitted when no snapshot was passed; packaged always false; note explains PDFs are external inputs not bundled in generated packages.
scale object min, max (1 and 7), labels map for anchor text on the frequency scale.
respondents object Keys: Self, Manager, Peer, Team, Customer. Each value has minimum (required invite count) and completed (actual responses).
importance array One object per competency, sorted by ascending avg_rank as printed in the report.
competencies array Twelve competencies in fixed Thomas order (see COMPETENCY_ORDER in parse_360.py).
qualitative array Three question objects with verbatim comments (15 each for current PDFs).
snapshot_highlights array {page, text, status, correction?} bullets from optional snapshot deck; empty when --snapshot omitted.
overrides_applied array Deterministic pipeline correction tags (snapshot_p*_…_reclassified_as_overclaim, plus fixed pipeline tags) and optional JSON paths merged from overrides.json.
warnings array Optional. Parser notes when distribution geometry could not be validated.

importance[] entry

Field Type Description
competency string Full competency name.
ranks object Integer ranks for Self, Manager, Peer, Team, Customer.
avg_rank float Report-printed average rank (one decimal); not recomputed.
rating float Demonstration rating from importance table (one decimal).

competencies[] entry

Field Type Description
name string Competency title.
code int Thomas competency number (1–12).
definition string Competency definition paragraph from PDF.
overall_rating object excluding_self and including_self floats from PDF.
statements array Behavioral statements for this competency.

competencies[].statements[] entry

Field Type Description
text string Statement wording.
averages object Mean score per rater group present (Self … Customer). Keys omitted when group has no rating.
ranges object Optional per-group [min, max] when PDF prints “X to Y” for multi-rater groups.
distributions object or null Per-group score histograms; null if geometric parse failed (see warnings).
avg_excluding_self float Mean of non-self group averages (computed, 2 decimals).
avg_including_self float Mean including self when present (computed, 2 decimals).

distributions[group]

Field Type Description
scores object Map score string "1"…"7" to integer count; zero counts omitted.
not_observed int Count of “not observed” responses for that group.

qualitative[] entry

Field Type Description
question string Survey question text.
comments array Verbatim anonymized comments.

snapshot_highlights[] entry

Field Type Description
page int 1-based page number in snapshot PDF.
text string Highlight bullet text (verbatim deck quote).
status string verified, overclaim, or context — audit vs Thomas data.
correction string Optional data-grounded correction when status is overclaim.

metrics.json (analyze stage)

Written by feedback360.analyze.analyze().

Field Type Description
schema_version int Always 1.
weights object Default w_importance, w_performance, w_blindspot, and exec_relevance map per competency.
competency_metrics array One derived record per competency (same order as data.competencies).
statement_metrics array One record per statement (54 total).
inversions array Competencies with |rank_gap| ≥ 4.
cta array Prioritized development action cards.
qual_themes array Keyword-grouped qualitative excerpts.
sentiment object Per-comment lexicon scores, plus by_question and by_theme aggregates.
swot object strengths, weaknesses, opportunities, threats arrays of rule-extracted items.
section_summaries object Executive summary strings for each tab (summary, matrix, gaps, …) plus themes map.
kpis object Summary-tab KPI snapshot derived from current params (see below).
headline_findings array 5–8 expandable executive findings with comment-backed detail (see below).
priority_matrix array Cohort priority heatmap rows ordered by ascending avg_rank (see below).
priority_matrix_summary object Per-rater-group one-sentence summaries of flagged cohort gaps.
johari object Johari 2×2 perception partition with quadrant items and findings (see below).

priority_matrix[] entry

Field Type Description
competency string Full competency name.
short string Abbreviated label for UI chips.
avg_rank float Report average importance rank.
ranks object Self, Manager, Peer, Team, Customer importance ranks from data.importance.
ratings object self (self_score), others (current rating_excluding_self, weight-aware), plus per-group rater_scores.
cohort_gaps object Per non-self group: rank, rating, median (of that group's 12 competency ratings), gap (= median − rating, 2 decimals), flag (true when rank ≤ 4 and rating ≤ median − 0.25), borderline (true when rank ≤ 4 and median − 0.25 < rating < median).

priority_matrix_summary object

Keys: Manager, Peer, Team, Customer. Each value is a one-sentence template naming full-gap and borderline competencies (within 0.25 of the group median), with ranks, ratings, and medians (or stating none).

johari object

Field Type Description
thresholds object gap (0.25) and divergence (2.0) cutoffs.
quadrants object Keys: arena, blind_spot, hidden_strength, contested.

Partition rules (first match wins): divergence ≥ threshold → contested; self_gap ≥ gap → blind_spot; self_gap ≤ −gap → hidden_strength; else arena. Arena items include kind: strength when rating_excluding_self ≥ median of 12, else development.

Each quadrant object:

Field Type Description
label string Human-readable sector title.
items array {competency, short, self, others, self_gap, kind?} — every competency appears in exactly one quadrant.
finding string 2–4 sentence executive paragraph (≥120 chars, ≥2 numbers); empty quadrants use a one-sentence placeholder.
sources array Optional {question_index, comment_index, excerpt} when a qualitative quote is embedded in finding.

section_summaries.perception

Executive summary for the Perception tab: cohort-gap count, Johari quadrant counts, and how to use both views together (≥120 chars, includes numbers).

kpis object

Field Type Description
overall_avg float Mean of the 12 rating_excluding_self values (2 decimals); uses weighted ratings when rater weights are non-uniform.
develop_count int Count of competencies in the develop quadrant under current params.
lowest_statement object {text, score, competency} for the lowest avg_excluding_self in statement_metrics.
widest_inversion object {competency, self_rank, others_rank_mean, gap} for the largest |self_rank − others_rank_mean|.
max_divergence object {competency, value, high_group, high, low_group, low} for peak rater spread.

explainers map

Element-specific flyout copy generated inside compute_metrics (recomputed with every /api/metrics POST). Keys are stable ids; values are objects:

Field Type Description
title string Short heading for the flyout.
body string 2–4 sentences (≥120 chars) citing the element's current value(s).
computation string Formula or extraction source (≥30 chars).
interpretation string Executive-development meaning of the current value (≥40 chars).
sources array Non-empty list of JSON paths and/or PDF references.

Id naming (slug = competency lowercased, non-alphanumerics → hyphens):

Pattern Count Explains
kpi.overall_avg, kpi.develop_count, kpi.lowest_statement, kpi.widest_inversion, kpi.max_divergence 5 Summary KPI cards
competency.<slug> 12 Competency scores, gap, quadrant, importance
stmt.<idx>.avg, stmt.<idx>.spread 108 Statement averages and spread (idx 0–53)
heatmap.<group>.<slug> 48 group ∈ manager/peer/team/customer
quadrant.develop, quadrant.leverage, quadrant.maintain, quadrant.monitor 4 Quadrant definition + current members
flag.lowest_overall, flag.low_score, flag.high_disagreement, flag.manager_low, flag.self_overrated 5 Flag rules + current counts
sentiment.positive, sentiment.mixed, sentiment.neutral, sentiment.negative 4 Sentiment rules + comment counts
johari.arena, johari.blind_spot, johari.hidden_strength, johari.contested 4 Johari quadrants + members
section.summary, section.matrix, … section.cta 8 Tab summaries
cta.<rank> one per CTA Priority score composition for that action

headline_findings[] entry

Field Type Description
id string Stable slug (e.g. vision-inversion).
tab string Related view: matrix, gaps, divergence, statements, voices, or cta.
text string One-line headline with numeric citations from current metrics.
detail string 2–5 sentence executive paragraph (≥200 chars) blending numbers with a verbatim qualitative excerpt.
sources array {question_index, comment_index, excerpt} references into data.qualitative.
confidence string high, moderate, directional, or audience-split — epistemic strength of the finding.

Findings are recomputed inside compute_metrics for every params POST so KPI cards, headline blocks, and CTA evidence stay aligned with rater weights, importance lens, and exec relevance.

significance object

Margin-of-error layer for small-sample interpretation.

Field Type Description
method string Always group-mean t-interval.
note string Canonical margin-of-error guidance paragraph.
statements array One entry per statement (54 total).
competencies array One entry per competency (12 total).

Each significance.statements[] entry: text, competency, n_groups, group_moe95 (float or null), self_gap, verdict (robust, directional, or insufficient), score_signal (high-confidence strength, solid, development signal, or low-confidence).

Each significance.competencies[] entry: name, group_moe95, self_gap, verdict, score_signal.

score_signal rules (statement mean = avg_excluding_self; competency mean = others_score): high-confidence strength when mean ≥ 6.2 and group_moe95 ≤ 1.0; solid when mean ≥ 5.5 and group_moe95 ≤ 1.5; development signal when mean < 5.2; otherwise low-confidence. verdict retains self-gap semantics (robust when |self_gap| ≥ MOE).

cta[] confidence

Each CTA card includes confidence (high, moderate, or directional): high when the importance weight term dominates the priority formula; directional when both self gap < 0.5 and rank gap < 3; otherwise moderate.

competency_metrics[] entry

Field Type Description
name string Competency name.
self_score float Mean of statement averages.Self (2 decimals).
others_score float overall_rating.excluding_self from data.
self_gap float self_score - others_score (2 decimals).
rater_scores object Mean statement average per Manager, Peer, Team, Customer.
divergence float max(rater_scores) − min(rater_scores) (2 decimals).
importance object self_rank, others_rank_mean, avg_rank, rank_gap.
rating_excluding_self float Copy of competency overall excluding self.
quadrant string develop, leverage, maintain, or monitor.
importance_norm float (13 - avg_rank) / 12.
performance_need float clamp((7 - rating_excluding_self) / 2, 0, 1).
blindspot float clamp(self_gap, 0, 1).
priority_score float Weighted formula × exec_relevance (3 decimals).

statement_metrics[] entry

Field Type Description
competency string Parent competency name.
text string Statement text (matches data).
avg_excluding_self float From data statement.
self_gap float Self average minus avg_excluding_self when self present.
spread int Max group range width; 0 if no ranges.
flags array Subset of: lowest_overall, low_score, high_disagreement, manager_low, self_overrated.

inversions[] entry

Field Type Description
competency string Competency name.
self_rank int Self importance rank.
others_rank_mean float Mean of Manager/Peer/Team/Customer ranks.
direction string underweighted_by_self or overweighted_by_self.
note string Human-readable summary.

cta[] entry

Field Type Description
rank int 1-based priority order after sort by priority_score desc.
title string Short action headline.
competency string Linked competency.
priority_score float Score used for ordering.
evidence array Data-grounded bullet strings.
actions array 2–4 concrete development steps.

qual_themes[] entry

Field Type Description
theme string Theme label from keyword map.
competencies array Related competency names.
comments array {question_index, comment_index, excerpt} references into qualitative data.

sentiment object

Field Type Description
comments array One entry per qualitative comment: question_index, comment_index, score (−1..1), label, evidence_terms.
by_question array Per-question avg_score and label counts.
by_theme array Per qual-theme avg_score and label counts.

swot object

Each category (strengths, weaknesses, opportunities, threats) is an array of items:

Field Type Description
statement string One-sentence synthesized summary.
competencies array Related competency names.
sources array {question_index, comment_index, excerpt} references.
corroboration string Quantitative tie-in with numeric citations.

section_summaries object

Field Type Description
summary … cta string 2–4 sentence tab executive summaries (≥120 chars, include numbers).
perception string Perception tab summary (cohort matrix + Johari counts).
themes object Map theme name → 1–2 sentence summary with sentiment counts.

See pipeline.md for how these files are produced and README.md for CLI usage.