---
name: kb-review
description: Provides iterative knowledge base enhancement sessions with completeness scoring and prioritization.
activation: manual
---

# kb-review

Provides iterative knowledge base enhancement sessions. Calculates completeness scores per profile, identifies stale information, presents a prioritized review summary, and suggests areas for the next interview session and relationship additions for graph consistency.

## Activation

Activated by user request. Example triggers:
- "review my knowledge base"
- "what needs updating?"
- "run a KB review session"
- "check completeness of my profiles"
- "what's stale in my knowledge base?"

## Inputs

- **Person ID** (optional): Focus the review on a specific profile. If not provided, reviews all profiles.
- **Staleness threshold** (optional): Number of days since last modification to consider an entity stale. Defaults to 90 days.

## Workflow

### 1. Load all profiles and graph index

- Read all person profiles from `kb/profiles/`
- Read `kb/graph-index.yaml` to discover all entities and relationships
- Read entity files referenced by each profile (experiences, skills, organizations, projects, certifications, tandems)

### 2. Calculate completeness scores

- Use completeness scoring logic (`src/review/completeness-score.ts`) to compute a score per profile
- Score equals the ratio of filled attributes to total defined attributes, including relationship coverage
- A fully complete profile scores 1.0; an empty profile scores close to 0.0

### 3. Identify stale information

- Check the `modified` date on each entity file
- Flag entities where the time since last modification exceeds the staleness threshold
- Group stale entities by type and owning profile

### 4. Prioritize review areas

- Use prioritization logic (`src/review/prioritization.ts`) to rank entities
- Entities with lower completeness scores and older modification dates rank higher
- Required fields missing rank higher than optional fields missing

### 5. Present review summary

- Show per-profile completeness scores
- List stale entities grouped by profile
- Present the prioritized list of areas needing updates
- Highlight any broken references or graph inconsistencies found during loading

### 6. Suggest next interview topics

- Based on the prioritized list, recommend 1-3 topic areas for the next interview session
- Explain why each topic was selected (gap type, staleness, importance)

### 7. Recommend relationship additions

- Identify entities that exist but lack expected relationships in the graph index
- Suggest relationship additions that would improve graph consistency (e.g., a skill referenced in an experience but not linked to the person profile)
- Use valid relationship types: `has_skill`, `worked_at`, `collaborated_with`, `applied_for`, `partners_with`

## Output

- Review summary presented to the user (not written to a file)
- Prioritized list of areas needing updates
- Suggested interview topics for next session
- Recommended relationship additions

## Shared Modules

This skill depends on the following shared validation and utility modules:

- `src/schemas/validate.ts` — Entity validation (validate sources during review)
- `src/schemas/types.ts` — TypeScript type definitions for all entity types
- `src/io/yaml-utils.ts` — YAML serialization/deserialization
- `src/io/entity-files.ts` — Entity file read management
- `src/graph/index-manager.ts` — Graph index read and consistency checks

## Rules and Constraints

1. **Read-only** — this skill does not modify any entity files or the graph index; it only reads and reports
2. **No fabrication** — only report information derived from actual entity data
3. **Completeness formula** — score = filled attributes / total defined attributes (including relationship coverage)
4. **Staleness threshold** — default 90 days; configurable per invocation
5. **Prioritization** — lower completeness + older modification date = higher priority
6. **Valid relationship types only** — only suggest relationships from the defined set
7. **Schema-validated sources** — only read from validated entity files in `kb/`
8. **Actionable output** — every suggestion should be specific enough to act on in an interview session