# Analysis Readiness Optimization Plan

Date: 2026-03-28

## Goal

Improve the current KB so it can support cross-module logical analysis with:

- lower lookup cost
- clearer trust boundaries
- explicit freshness
- less string-based guessing during joins

This plan follows the findings recorded in:

- `construction/important-repos-analysis-audit-report.md`
- `construction/analysis-readiness-follow-up-findings.md`

## Scope

This plan does **not** redefine the ongoing work that is already moving deployment/config analysis into the KB.

Instead, it focuses on the complementary foundation that is still missing even after deployment/config data becomes available:

1. freshness and drift control
2. source-of-truth and confidence tracking
3. stable entity identity and join scaffolding

## Constraints

- Process docs, plans, schemas, and methodology notes must stay under `construction/`.
- Only true analysis artifacts should go into `knowledge/`.
- Do not overwrite or reorganize the current KB layout in one large refactor.
- Prefer incremental slices that can be applied to one repo first, then generalized.
- Avoid touching files that are already being modified by another active session unless necessary.

## Optimization Principles

### 1. Add trust metadata before adding more conclusions

If the KB cannot say whether a fact is fresh or authoritative, increasing coverage alone will not improve analysis quality.

### 2. Prefer layered adoption

Apply new fields and artifacts to one repo first, verify usefulness, then expand.

### 3. Separate method/process from analysis data

- process, schema, workflow -> `construction/`
- analysis output -> `knowledge/`

### 4. Keep joins explicit

Cross-repo reasoning should depend on tracked IDs and evidence, not on naming coincidence.

## Phases

## Phase 0. Rule Alignment

Objective:

- make directory-boundary rules explicit for future work

Deliverables:

- update project `AGENTS.md`

Status:

- `completed` in this execution

## Phase 1. Freshness Metadata Baseline

Objective:

- make KB artifacts auditable against source state

Deliverables:

- define common freshness fields
- apply them to one runtime repo first

Required fields:

- `source_repo`
- `source_commit`
- `scanned_at`
- `freshness_status`
- `freshness_checked_at`

Recommended values for `freshness_status`:

- `fresh`
- `stale`
- `unknown`
- `blocked`

Success criteria:

- one KB artifact can be traced back to an exact source commit
- one freshness judgment can be made without manual memory

Status:

- `in progress` in this execution

## Phase 2. Source-of-Truth and Confidence Baseline

Objective:

- make important conclusions reviewable and conflict-aware

Deliverables:

- define per-domain authority metadata
- apply it to the same runtime sample repo

Required fields:

- `truth_domain`
- `authoritative_source`
- `supporting_sources`
- `confidence`
- `conflict_status`

Recommended values:

- `confidence`: `high`, `medium`, `low`
- `conflict_status`: `none`, `suspected`, `confirmed`

Success criteria:

- one answer can clearly state who is authoritative and how trustworthy the conclusion is

Status:

- `in progress` in this execution

## Phase 3. Repo-Local Analysis Readiness Samples

Objective:

- create repo-local tracked artifacts that summarize whether a repo is analysis-ready for its current scope

Deliverables:

- one sample artifact under `knowledge/repos/{repo}/`

Recommended sample target:

- `knowledge/repos/tidb-management-service/analysis-readiness.json`

Why this repo first:

- local source repo is clean
- runtime scan data is already present
- no conflict with the ongoing deployment/config session

Success criteria:

- sample file can summarize readiness, freshness, truth-domain confidence, and key entities for one repo

Status:

- `in progress` in this execution

## Phase 4. Reverse Index Pilot

Objective:

- support at least one reverse lookup path without opening raw source trees

First pilot:

- `by-service`

Minimum content:

- service ID
- producer repo
- primary evidence files
- consumers or known join points
- freshness metadata

Dependency:

- Phase 1 must exist first

Status:

- `planned`

## Phase 5. Canonical Entity and Alias Mapping Pilot

Objective:

- reduce string-guessing joins

Initial entity set:

- `repo`
- `binary`
- `runtime_service`
- `deployment_unit`
- `config_group`
- `cluster`
- `namespace`
- `external_resource`

Initial relationship types:

- `same_as`
- `deployed_as`
- `runs_in`
- `configured_by`
- `depends_on`

Dependency:

- Phase 1 and Phase 2 must exist first

Status:

- `planned`

## Execution Slice for This Turn

This turn will complete these concrete actions:

1. update `AGENTS.md` with the `construction/` vs `knowledge/` rule
2. record this optimization plan under `construction/`
3. create one runtime repo sample analysis artifact for `tidb-management-service`

This slice is intentionally narrow so it does not collide with the separate session that is already working on deployment/config knowledge ingestion.

## Expansion Order After This Turn

Recommended next rollout order:

1. expand the same sample artifact pattern to `config-service` or another already-scanned runtime repo
2. add reverse-index pilot for `tidb-management-service`
3. align deployment/config outputs from the other session to the same freshness and confidence fields
4. add canonical IDs and alias mappings across runtime and deployment artifacts

## Risks

- If each session invents its own metadata fields, the KB will fragment further.
- If freshness metadata is skipped, later answers will be hard to trust.
- If canonical IDs are introduced before truth-domain boundaries are clear, joins may become prematurely rigid and wrong.

## Exit Criteria

This optimization plan is considered meaningfully underway when:

- the directory-boundary rule is documented
- the plan is written under `construction/`
- at least one sample tracked analysis artifact exists in `knowledge/`