Capablio

Handbook

Question Architecture

The capability, behavior, team condition, or outcome the framework intends to understand.

Updated

Three-layer model

1. Construct

The capability, behavior, team condition, or outcome the framework intends to understand.

2. Question Family

A stable measurement intent associated with one construct. It defines what is being asked, who can observe it, which evidence types are valid, and whether variants can be compared.

3. Question Variant

The exact wording and answer design for a specific cadence, relationship, role, observation horizon, and language.

This model is more robust than storing a flat list of question strings because it supports cadence-aware wording, respondent routing, translation, versioning, and longitudinal analysis.

Question-family metadata

Category Fields
Identity family_id, version, status, source, tenant_id, owner
Meaning construct_id, behavioral_indicator, evidence_type, definition
Applicability subject roles, respondent relationships, organizational contexts
Time allowed cadences, minimum observation window, preferred horizon
Exposure base skip periods, cooldown clock, absolute minimum days, max asks per rolling window
Selection anchor eligibility, priority, random weight, coverage group, incompatibilities
PDP PDP eligibility, follow-up family, default override, milestone mapping
Reporting trendability, aggregation level, minimum N, polarity, display rules
Quality validation status, bias review, readability, last review date
Lifecycle created by, approved by, valid from, valid to, supersedes

Question-variant metadata

Category Fields
Text prompt, context, help text, evidence prompt
Audience respondent relationship, subject role, locale
Window “today,” “this week,” “past month,” “past quarter,” “past year”
Scale scale ID, anchors, Not Observed, Not Applicable
Delivery mobile length, channel restrictions, required/optional
Comparability bridge group, exact-trend key, normalized-display permission

Evidence types

  • State — current feeling or condition; useful daily or weekly.
  • Behavior frequency — how often an observable behavior occurred.
  • Behavior quality — how effectively the behavior was demonstrated.
  • Climate — shared team experience, such as psychological safety.
  • Action completion — whether a planned PDP action happened.
  • Outcome — whether a user, customer, delivery, or people result improved.
  • Confidence — respondent confidence in an observation or decision.
  • Narrative evidence — a concrete situation, behavior, and impact.

Do not average different evidence types into one number without an explicit scoring model.

Supported answer scales

Frequency 5

  1. Never or almost never
  2. Rarely
  3. Sometimes
  4. Often
  5. Consistently

Best for recurring behavioral pulses.

Extent 7 / Thomas-compatible

  1. Not much / substantial development needed
  2. Meets expectations for the role
  3. A great deal / role-model behavior

Use for annual or quarterly 360 programs when compatibility is valuable. Include separate Not Observed and Not Applicable.

Agreement 5

Strongly disagree to strongly agree. Best for team climate and experience, not for judging a person’s capability.

Confidence 5

Very low to very high. Use to qualify decisions or observation certainty.

Action state

Not started, started, completed, blocked, no longer relevant.

Open evidence

Prompt for a specific situation and impact. Avoid generic “anything else” fields.

Writing rules

  1. Ask about one primary behavior.
  2. State the observation window.
  3. Use a respondent who can observe the behavior.
  4. Avoid words that imply a desired answer.
  5. Avoid “always,” “never,” and heroic-work norms unless they are literal scale anchors.
  6. Do not combine action and outcome in one item.
  7. Avoid questions that reward overwork, indispensability, or excessive availability.
  8. Separate “asks for feedback,” “receives it constructively,” and “closes the loop.”
  9. Make Not Observed distinct from Not Applicable.
  10. Use reverse-coded items only when there is a tested reason; they often increase confusion in short pulses.

Cadence-specific wording example

Question family: leadership.feedback.closes_loop

Cadence Direct-report variant
Daily Normally not eligible; insufficient observation window
Weekly “This week, my manager explained what changed after receiving feedback.”
Monthly “During the past month, my manager closed the loop after receiving feedback.”
Quarterly “During the past quarter, this leader consistently explained what changed—or why it did not—after feedback.”
Annual “Over the past year, this leader made their response to feedback visible through changes or clear explanations.”

Example family definition

schema: capablio.question-family/v1
family_id: leadership.feedback.closes_loop
version: 1.0.0
construct_id: leadership.feedback_receptivity
status: published
source: capablio-core
evidence_type: behavior_frequency
applicability:
  respondent_relationships: [self, manager, peer, direct_report]
  excluded_relationships: [customer]
exposure:
  base:
    cadence_unit: MONTH
    skip_periods: 1
    clock_start: presented_at
    absolute_min_days: 21
    max_asks_per_rolling_90_days: 3
selection:
  anchor_eligible: true
  coverage_group: feedback_loop
  random_weight: 1.0
pdp:
  eligible: true
  default_override:
    mode: replace_skip_periods
    skip_periods: 0
    max_consecutive_surveys: 2
reporting:
  exact_trend_key: leadership.feedback.closes_loop.monthly.freq5
  cross_scale_normalized_display: true
  cross_scale_aggregation: false

Versioning and comparability

  • Typographical changes that do not alter meaning may retain a family but create a new variant version.
  • Meaningful wording or scale changes create a new variant and may require a new exact-trend key.
  • Construct changes require a new family.
  • Translations are versioned and reviewed independently.
  • Historical responses never point to a mutable current text field.
  • Normalizing scores to 0–100 is useful for display, but it does not make unlike scales psychometrically equivalent.

Validation status

Every family and variant should carry one of:

  • draft
  • expert_reviewed
  • pilot
  • operationally_validated
  • psychometrically_validated
  • retired

The product should not label a tenant-authored or AI-generated item “validated” merely because it was published.