Markdown Question-Pack Format

Why Markdown

Markdown is useful for collaborative analysis because it is readable in Git, supports comments and review, and can embed YAML metadata and tables. Production should compile the Markdown into a validated machine-readable representation.

Recommended workflow:

Markdown pack -> parser -> schema validation -> linting -> simulation -> signed published artifact

File-level front matter

---
schema: capablio.pack/v1
pack_id: core.weekly.execution
version: 1.0.0
status: pilot
source: capablio-core
name: Weekly Execution Core
description: Lightweight weekly signal for priority clarity, flow, support, and sustainable delivery.
applicable_subject_roles: [employee, manager, engineering_leader]
respondent_relationships: [self, direct_report]
default_schedule:
  cadence_unit: WEEK
  interval: 1
  timezone: tenant
survey_quota:
  min: 3
  target: 4
  soft_max: 5
  hard_max: 7
mix:
  anchors: 1
  rotating: 2
  pdp_reserved: 1
  open_text_max: 1
coverage:
  strategy: weighted_deficit_round_robin
  completion_target_periods: 8
  reset: on_complete
anonymity:
  aggregate_minimum: 3
---

Pack sections

Each pack should contain:

1. Purpose and intended use.
2. Population and respondent routing.
3. Cadence and observation-window rules.
4. Survey quota and reserved capacity.
5. Anchor items.
6. Rotating pools.
7. Bundles and atomicity.
8. PDP and event-trigger behavior.
9. Coverage feasibility assumptions.
10. Reporting and anonymity rules.
11. Known limitations.
12. Change log.

Pack item syntax

A human-readable table is acceptable for analysis:

For production compilation, each item should also have an embedded YAML block:

pack_item:
  id: weekly.execution.priority_clarity
  family_id: team.priority.clarity
  inclusion_mode: anchor
  respondent_relationships: [self]
  eligible_cadences: [WEEK]
  cooldown_override:
    skip_periods: 0
  selection:
    priority: 100
    coverage_unit: question_family

Bundle syntax

bundle:
  bundle_id: engineering.incident_learning
  mode: atomic
  items:
    - engineering.reliability.operational_readiness
    - engineering.reliability.blame_free_learning
    - engineering.reliability.corrective_actions_closed
  quota_cost: 3
  min_observation_window_days: 30

A splittable bundle may define min_pick, max_pick, and internal weights.

Tenant overlay format

Tenant customization should be expressed as an overlay, not an edit to the source file:

---
schema: capablio.pack-overlay/v1
overlay_id: acme.weekly.execution
base_pack_id: core.weekly.execution
base_version: 1.0.0
tenant_id: acme
version: 1.0.0
---

disable:
  - team.recognition.visible

add:
  - family_id: acme.values.customer_ownership
    inclusion_mode: rotating
    weight: 1.5

override:
  survey_quota:
    target: 5

Lint rules

A pack cannot publish when:

• The hard maximum is lower than mandatory capacity.
• A question has no variant for an assigned cadence and relationship.
• A daily pack includes an item whose minimum observation window exceeds the survey window.
• A customer relationship receives an internal-only question.
• A rotating pool has no feasible route to full coverage.
• An atomic bundle is larger than the hard maximum and no split policy exists.
• A question lacks a cooldown or absolute fatigue cap.
• A reportable rater group has an anonymity threshold below tenant policy.
• A retired or draft question is referenced.
• A tenant overlay changes meaning without creating a tenant-specific family or version.

Simulation output

Before publication, the compiler should provide:

• Expected survey size distribution.
• Earliest and latest full-coverage period.
• Questions likely to starve under current weights.
• Mandatory-overflow scenarios.
• Average exposure by respondent over 30, 90, and 365 days.
• Percentage of items with incompatible observation horizons.
• Expected anonymity suppression by team size.