# Investibook API Diagnostic Coverage Expansion Plan

## Current Design

- Jira is already the production intake source. `src/auto-analysis.ts` polls Jira,
  applies the deterministic Q&A gate, evaluates scenario-based auto coverage, enqueues
  jobs in `auto_oncall_jobs`, and the worker writes one internal Jira comment
  through the live analysis path.
- `src/auto-config.ts` owns the current rollout execution switch. Coverage is
  derived from `scenarioClass + resolutionMode` and records only `enabled` or
  `disabled`.
- `src/analysis-service.ts` creates the run workspace, runs the diagnostic risk
  preflight, then calls the Codex runner. The current preflight is a safety
  short-circuit for risky diagnostic language; it does not fetch diagnostic data.
- `src/run-workspace.ts` is the canonical prompt/input materialization layer.
  Live workspaces expose sanitized Jira ticket fields, reply-safe comments,
  image manifests, and prompts. The DB is the canonical job/run index; workspace
  files are per-run artifacts.
- Investibook is currently a design reference only. This subrepo must not import
  Investibook code, config, workspace state, deployment manifests, or runtime
  libraries.

## Risks

- Encoding rollout readiness as another business bucket would blur scenario,
  resolution mode, and execution eligibility semantics.
- Letting the model call an arbitrary Investibook endpoint would make evidence
  provenance and failure handling hard to test locally.
- Large or raw diagnostic payloads can bloat `result.json`, Jira internal
  comments, DB rows, and model context.
- A diagnostic API outage must not create duplicate jobs, advance the poll
  cursor incorrectly, or cause customer-visible writes.
- Jira comments, hidden support comments, prior auto-oncall notes, and
  Investibook evidence must stay in separate channels so the answer contract
  remains reviewable.
- Scenario classification must use the same replay-safe visible comments that
  are materialized into the run workspace. It must not scan the full Jira
  comment history, otherwise future confirmations, hidden support replies, or
  internal notes can change the scenario and gate result.
- Current staging uses scenario classification as the only auto-coverage input.
  Jira labels remain raw ticket metadata and must not decide coverage.
- The poll cursor advances over skipped tickets. Expanding gates later does not
  automatically revisit old skipped tickets unless Jira updates them, a narrow
  allowlist is used, or an explicit backfill/re-trigger mechanism is designed.

## Target Contract

- Jira remains the canonical intake and job state source. Investibook is only a
  read-only diagnostic evidence provider behind an explicit HTTP API client.
- Scenario, resolution, coverage eligibility, and diagnostic enrichment are
  separate:
  - Scenario class describes the problem type being solved. It must not encode
    temporary missing context.
  - Resolution mode describes how the current ticket state should be handled:
    direct answer, focused clarification, evidence-assisted draft, human review,
    or skip.
  - Q&A gate still decides whether a ticket is in scope for auto-oncall.
  - Auto-coverage records only whether the scenario/resolution combination is
    enabled for automation.
  - A new explicit eligibility config decides which combinations may be
    enqueued. Default enabled resolution remains `direct_answer` only.
- Scenario classification is a workspace-input decision. Dry-run classification
  uses customer-side context before the replay target; live classification uses
  current reply-safe visible context. API responses return that same
  materialized classification object.
- Coverage eligibility uses explicit scenario allowlists after the Q&A gate.
  Scenario classification is the canonical input for auto coverage.
- Investibook integration is service-owned and API-only:
  - no source imports from Investibook;
  - no dependency on parent repo workspace files;
  - no direct DB/cache/file reads from Investibook;
  - no production operations or writes through Investibook.
- Diagnostic evidence is materialized before the runner:
  - normalized summaries go under `input/diagnostics/`;
  - raw API payloads, if retained, go only under `trace/diagnostics/`;
  - `LiveAnalysisResult.evidenceLinks` stores small references, not raw payloads;
  - Jira internal comments may summarize evidence but must not embed large raw
    payloads or secrets.
- When an Investibook response is available and includes normalized summaries,
  `manifest.primaryEvidence=true`; the runner treats those summaries as the
  primary diagnostic evidence. Clinic and Wetech skills remain available only
  for targeted gap checks, narrow contradiction verification, or fields
  explicitly requested by the Investibook summary.
- Missing diagnostic metadata or failed Investibook calls produce a structured
  limitation and minimal `requestedContext`; they do not fabricate evidence.
- Dry-run and live use the same diagnostic input contract. Live may call the API
  only after Q&A, coverage eligibility, and L1 oncaller gates pass.

## Implementation Steps

1. Add a scenario classifier that emits:
   - `scenarioClass`: stable problem type such as `sql_performance_tuning`,
     `ddl_schema_change_advice`, `feature_usage_or_capability`,
     `cluster_runtime_issue`, `backup_restore_or_dr`,
     `ticdc_or_data_pipeline`, `security_or_access_control`,
     `billing_quota_or_plan`, `operation_request`,
     `product_bug_or_data_risk`, or `non_target_admin_or_noise`;
   - `resolutionMode`: `direct_answer`, `clarification_needed`,
     `evidence_assisted`, `human_required`, or `skip`;
   - `missingKeys`, `riskFlags`, and `evidenceProvider`.
   The classifier must receive replay-safe visible comments from
   `run-workspace.ts`; it must not read unfiltered `SupportCase.comments`.
2. Add coverage eligibility switches in `src/auto-config.ts`:
   `AUTO_ONCALL_AUTO_COVERAGE_ENABLED_SCENARIOS` and
   `AUTO_ONCALL_AUTO_COVERAGE_ENABLED_RESOLUTIONS`.
3. Derive coverage from the `scenarioClass + resolutionMode` combination and
   record only `enabled` or `disabled`.
4. Update `src/auto-analysis.ts` to run only enabled coverage combinations,
   while still recording scenario and resolution details separately.
5. Keep Jira labels out of coverage decisions so rollout evidence comes from
   scenario and coverage buckets only.
6. Define a small diagnostic provider boundary, e.g. `src/diagnostic-context.ts`,
   with a stable input from `SupportCase` and a stable output:
   `status`, `provider`, `summaryMarkdown`, `requestedContext`, `evidenceLinks`,
   and optional raw artifact path.
7. Implement `src/investibook-client.ts` as a read-only HTTP client configured
   by env vars such as base URL, token secret, timeout, and feature enablement.
   The first version should support one narrow lookup path derived from Jira
   metadata already present in `SupportCase`.
8. Insert diagnostic enrichment in `analysis-service.ts` after workspace
   creation and before diagnostic risk preflight / runner execution.
9. Extend `run-workspace.ts` prompts to tell Codex to read
   `input/diagnostics/manifest.json` when present, use summaries as read-only
   evidence, and record failures as limitations.
10. Keep the current risk preflight, but rename or separate it conceptually from
   diagnostic enrichment so `diagnostic preflight` does not mean two different
   things.
11. Add a narrow re-trigger/backfill decision before testing old skipped tickets:
   either use explicit issue allowlists, wait for Jira updates, or bump
   `triggerVersion` only with a reviewed migration/duplication plan.
12. Add deployment template env wiring under `deploy/app-delivery/` only after
   the local contract tests pass. Secrets should be referenced by name/key only;
   no real token values go into the repo.
13. Roll out in stages:
   - staging: enable provider for reviewed scenario/resolution combinations;
   - staging: keep human-required and skip resolutions disabled from automation;
   - prod: keep automation disabled unless explicitly cut over;
   - prod expansion: enable additional decisions only after DB/log/Jira evidence
     proves stable staging behavior.

## Verification Checklist

- Unit tests cover scenario classification and prove missing context is reported
  through `missingKeys` / `resolutionMode`, not by changing `scenarioClass`.
- Unit tests cover coverage decision allowlisting, including evidence-assisted
  scenarios counted but not enqueued by default.
- Unit tests cover Investibook client timeout, 401/403, 404/no evidence, large
  payload truncation, and secret redaction.
- Workspace tests prove normalized diagnostic summaries are written under
  `input/diagnostics/`, raw payloads stay out of `result.json`, and dry-run/live
  share the same manifest contract.
- Runner or fake-runner tests prove `evidenceLinks` carries references without
  expanding raw payloads into Jira comments.
- Worker tests prove diagnostic fetch happens only after Q&A, coverage
  eligibility, and L1 oncaller gates pass.
- Local `npm run typecheck` and `npm test` pass before any deployment sync.
- Staging rollout verifies rendered pod env, logs, DB job/run rows, diagnostic
  artifact paths, and the exact Jira internal comment idempotency key.

## Current Implementation Status

- Done: scenario classification, replay-safe visible-comment input, APID-29014
  direct-answer handling, scenario-based coverage allowlists, and staging gate
  template updates.
- Done: service-owned Investibook HTTP client boundary with configurable base
  URL, endpoint path, bearer token, timeout, summary truncation, and normalized
  response contract.
- Done: diagnostic materialization writes normalized summaries under
  `input/diagnostics/` and redacted raw API payloads under
  `trace/diagnostics/`.
- Done: diagnostic manifests mark normalized Investibook summaries as primary
  evidence, and dry-run/live prompts require the agent to read them before
  falling back to Clinic or Wetech OP read-only queries.
- Done: dry-run and live analysis call diagnostic materialization before the
  runner; live result evidence links are merged from the diagnostic manifest.
- Pending rollout: fill the real Investibook base URL/path/token, enable the
  provider in staging, sync app-delivery, and verify live pod env plus artifact
  output.

## Non-Goals

- No Investibook code import, package dependency, deployment dependency, or
  workspace coupling.
- No customer-visible Jira comments, issue transitions, closes, or production
  operations.
- No broad arbitrary Jira backfill or user-provided JQL.
- No fallback that treats Investibook UI, local files, source code, or parent
  repo state as diagnostic source of truth.
- No promotion of all diagnostic tickets without an explicit scenario,
  eligibility config, and rollout evidence.