# Engineering Capacity OS Answer Card Schema

Version: 3.0

The answer card turns each CTO research question into a private, evidence-bound diagnostic object. The public site supplies the question, doctrine answer, evidence requirements, confidence rubric, and report shape. The customer answer is generated inside the organization's own MCP environment or from a redacted manual evidence pack.

## Public Answer Boundary

The public answer is doctrine guidance. It explains what a valid answer must prove. It does not guess the customer's internal state.

Real answers require private Jira, Linear, GitHub, GitLab, CI/CD, incident, architecture, review, telemetry, policy, and access data. That data should stay inside the organization boundary.

## Schema Fields

- question_id
  - type: string
  - required: true
  - definition: Stable identifier from the question bank.
- domain
  - type: string
  - required: true
  - definition: Research domain that owns the question.
- question
  - type: string
  - required: true
  - definition: Atomic CTO question being answered.
- doctrine_answer
  - type: string
  - required: true
  - definition: Public baseline answer from the Engineering Capacity OS model.
- evidence_summary
  - type: string
  - required: true
  - definition: Aggregate, redacted summary of what the internal evidence shows.
- observed_state
  - type: enum
  - required: true
  - definition: observed, modeled, directional, or unknown.
- confidence
  - type: enum
  - required: true
  - definition: high, medium, directional, or unknown.
- source_classes
  - type: array
  - required: true
  - definition: Approved source categories used, never raw sensitive records.
- missing_evidence
  - type: array
  - required: true
  - definition: Evidence needed before the answer can be treated as reliable.
- risk_flags
  - type: array
  - required: true
  - definition: System risks surfaced by the answer.
- recommended_report_section
  - type: string
  - required: true
  - definition: Report section where the answer belongs.
- next_safe_action
  - type: string
  - required: true
  - definition: One reversible action or measurement step.
- do_not_collect
  - type: array
  - required: true
  - definition: Sensitive data classes that should not be exported.

## Confidence Levels

- high: 90 or more days of source-system evidence across the included teams, services, and delivery paths.
- medium: 30 to 90 days of evidence with partial but useful source-system coverage.
- directional: Limited sample, incomplete source coverage, or qualitative evidence that points to a hypothesis.
- unknown: No reliable evidence is available. The correct output is instrumentation guidance, not a forced answer.

## Workflow

- Select question: Choose one operating decision and one question. Do not run the whole bank when the leader needs a specific decision.
- Constrain evidence: Define source systems, time window, aggregation level, redaction rules, and data classes that must not leave the organization.
- Retrieve aggregate signals: Use MCP or exports to retrieve counts, distributions, metadata, examples, and summaries rather than raw source code, secrets, logs, or employee records.
- Map to doctrine answer: Compare the evidence to the Engineering Capacity OS doctrine answer and identify whether the question is observed, modeled, directional, or unknown.
- Write answer card: Produce one answer card with confidence, risk flags, missing evidence, report section, and one next safe action.
- Validate with the owner: A human system owner checks the source classes, assumptions, confidence tier, missing evidence, and action boundary before the answer is used.

## Example Card

```json
{
  "question_id": "topology-005",
  "domain": "distributed_capacity_topology",
  "question": "What review capacity must exist before adding distributed contributors?",
  "doctrine_answer": "Additional contributors increase throughput only when review capacity, architecture authority, and approval paths can absorb the added work. If review is the constraint, more contributors create more queue time.",
  "evidence_summary": "Synthetic example: PR review queue age is above 36 hours for platform services, correction rate is rising, and reviewer availability is concentrated in two senior engineers.",
  "observed_state": "directional",
  "confidence": "medium",
  "source_classes": [
    "pull request metadata",
    "review queue age",
    "service ownership map",
    "deployment metadata"
  ],
  "missing_evidence": [
    "reviewer calendar load",
    "architecture decision latency",
    "post-merge defect trend"
  ],
  "risk_flags": [
    "review_bottleneck",
    "architecture_authority_constraint"
  ],
  "recommended_report_section": "Capacity Topology Readiness Report",
  "next_safe_action": "Measure reviewer availability, PR correction rate, approval latency, and service ownership coverage for 30 days before adding distributed contributors.",
  "do_not_collect": [
    "source code",
    "secrets",
    "customer data",
    "raw private messages",
    "individual employee performance records"
  ]
}
```