Handbook
Capablio Adaptive Feedback Framework
Version: 0.1 (architecture pack landed 2026-07-16) Status: Product and domain architecture for production-scale Capablio — not fully implemented in code yet.
Updated
This folder is the canonical engineering wiki for the Adaptive Feedback Framework (AFF). The private handbook at handbook.capablio.com rebuilds from the same Markdown via capablio-website.
What Capablio does today vs this framework
| Today (shipped) | Framework target (mostly Unimplemented) |
|---|---|
| Fixed Thomas-compatible catalog (12 competencies / 54 statements) | Construct → Question Family → Question Variant model |
| Quarterly period surveys | Daily / weekly / monthly / quarterly / annual / event cadences |
| Full conversational survey per period | Constrained rotation, anchors, exposure cooldown |
| Subject PDP interview + encrypted storage | PDP-driven recurrence overrides and follow-up packs |
| Multi-tenant SaaS + encryption | Tenant overlays, pack governance, subject-seat entitlements |
| PDF / summary Thomas import path | Structured + confirmed PDF + manual Thomas import levels |
Implementation matrix: implementation-status.md (AFF-* IDs).
Shipped platform matrix: ../feature-status.md (IMP-* / PLN-*).
Critical decisions (do not reopen lightly)
- Stable identity is the question family, not the exact sentence.
- Exposure cooldown ≠ data retention (separate fields, services, policies).
- One shared exposure ledger across overlapping programs.
- Selection is deterministic and explainable (randomness only breaks ties).
- Reserve capacity for anchors and PDP force-next before rotation.
- Never promise 100% coverage without a feasibility simulation.
- Never silently drop mandatory questions when the quota is full.
- Imported Thomas data stays external evidence unless a measurement bridge is approved.
- Do not auto-create a PDP from one low score.
- Keep entitlements, tenant settings, and feature flags separate.
Review order
- 00-assumptions-and-decisions.md
- 03-question-architecture.md
- 05-cadence-and-cooldown.md
- 06-survey-assembly-engine.md
- 07-pdp-adaptive-loop.md
- 14-pricing-and-entitlements.md
- implementation-status.md
Pack map
| File | Purpose |
|---|---|
| 00-assumptions-and-decisions.md | Scope, principles, non-goals |
| 01-product-architecture.md | Personas and workflows |
| 02-domain-model.md | Entities and invariants |
| 03-question-architecture.md | Construct / family / variant |
| 04-pack-format.md | Markdown pack format |
| 05-cadence-and-cooldown.md | Skip periods and exposure ledger |
| 06-survey-assembly-engine.md | Selection, bundles, coverage |
| 07-pdp-adaptive-loop.md | PDP overrides and follow-up rotation |
| 08-tenant-customization-and-governance.md | Overlays and publishing |
| 09-thomas-compatibility.md | Import levels and evidence |
| 10-analytics-scoring-and-reporting.md | Trends and reporting |
| 11-privacy-security-and-data-retention.md | Anonymity and retention |
| 12-integrations-api-events.md | API, events, channels |
| 13-competitor-landscape.md | Research input (not product claims) |
| 14-pricing-and-entitlements.md | Subject-seat plans (proposed) |
| 15-mvp-roadmap.md | Phased delivery |
| 16-open-questions.md | Decisions still open |
| packs/ | Illustrative question packs |
| examples/ | Family and overlay examples |
| implementation-status.md | AFF-* status flags |
User-facing docs
| Audience | Doc |
|---|---|
| Subjects and raters | ../user-guide.md |
| Tenant / org admins | ../forge360/capablio-admin-guide.md |
| Studio facilitators | ../operator-guide.md |
Design warning
“Eventually achieve 100% question coverage” is only possible when available survey slots are sufficient for the eligible inventory. The platform must calculate feasibility and must not promise full coverage under an impossible quota.