---
name: setup-build-kb
description: Build or update the resume knowledge base from structured extractions. Use to normalize employment evidence, maintain the canonical claims registry, add achievements with ownership and metric status, update evidence-tiered skills and role bundles, propagate corrections, and validate the full resume system.
---

# Build or Update the Knowledge Base

## Authority Model

The pipeline is:

`source documents -> extractions -> canonical claims -> experience records/bundles -> generated applications`

Generated applications never flow backward into the KB.

Read `resume_builder/canonical/claims.json`, `config.md`, and all relevant extractions before changing normalized sources. Preserve raw source documents. A verified correction must update canonical claims first and then every dependent normalized file.

## Canonical Claim Record

For each employment item or achievement, record:

- stable ID;
- employer, title, dates and location;
- factual scope;
- individual vs shared ownership;
- allowed verbs;
- forbidden overstatements;
- metric/result and verification status;
- evidence source;
- last verified date.

When ownership is ambiguous, use contributing/shared scope and ask the user. Do not default to full ownership.

## Experience Files

Experience files explain facts and context. They may contain example phrasings, but those examples cannot override canonical scope and should not be optimized to fixed line counts.

Every achievement section must include canonical ID, source, ownership scope, status, verified result/metric state, relevant skills and role relevance.

## Skills Taxonomy

Use only these evidence levels:

- Production — current.
- Production — historical.
- Hands-on — current.
- Project / proof of concept.
- Certification / coursework.
- Unverified / never used.

Do not assign Expert/Proficient/Familiar labels. Add a skill to canonical claims before it can appear in a generated document.

## Role Bundles

Each bundle must contain:

1. Defensible positioning.
2. Good-fit roles and hard-gate cautions.
3. Achievement priorities.
4. Safe reframing rules.
5. Evidence-backed skills guidance.
6. Conditional cover-letter guidance.

Bundles may rank evidence; they may not broaden it. Title-defining gaps must be stated explicitly.

## Significance Context

Keep company/industry context separate from candidate impact. Mark external claims for re-verification at application time. Never attach generic scale, economics, customers or market trends to the candidate.

## Correction Propagation

After any correction, search canonical claims, config, extractions, experience files, bundles, support files, templates and active drafts. Historical submitted outputs remain unchanged but update `historical_outputs.json` when they become unsafe for reuse.

## Validation

Run:

```powershell
python resume_builder/helpers/validate_resume_system.py
```

Then review the diff for dates, titles, ownership, metrics and skill evidence. Present the changed claim records and affected downstream files to the user for confirmation.