# Kb Status

> Kb Status is an Agent Skill for productivity published in the linq2db/linq2db repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Read-only status report for the knowledge base — phase progress, source freshness (per-source cursor age), counts (areas, decisions, detected-issues by severity, GH index sizes), staleness summary (files with last_verified older than 90 days), consultation/usage stats (how often the KB is actually read during sessions), and the last few entries from audit-log.md.

- Skill name: `kb-status`
- Category: [Productivity](https://www.openparable.com/skill/productivity/1)
- Source: https://github.com/linq2db/linq2db/blob/HEAD/.agents/skills/kb-status/SKILL.md
- Repository: linq2db/linq2db (3,302 GitHub stars when collected)

## SKILL.md

# /kb-status

Prints a compact dashboard of the KB's current state. Read-only — never modifies anything.

## When to run

- Any time the user wants to know whether `/kb-refresh` is needed.
- Before starting fresh work on a feature/bug — to confirm the KB's most recent verified SHA.
- After `/kb-build` finishes — to confirm all steps are `done`.

## Steps

### 1. Pull state summary

```bash
pwsh -NoProfile -File .agents/scripts/kb-state.ps1 <<'EOF'
{"op": "summary"}
EOF
```

Returns `{progress, cursors, audit_tail}`.

### 2. Compute counts from disk

In parallel `Bash` calls (or `Glob` + `Read`):

- `architecture/`: count `.md` files.
- `conventions/`: count.
- `history/by-year/`: list filenames; the count = year span.
- `history/decisions/`: count.
- `areas/`: list directories; per area, check whether all four sub-files exist (`INDEX.md`, `issues.md`, `decisions.md`, `tech-debt.md`, `patterns.md`).
- `github/issues-index.json`, `prs-index.json`, `discussions-index.json`: read; report length.
- `github/milestones.json`: read; report `{open: N, closed: N}`.
- `github/wiki/`: count `.md` files.
- `detected-issues/index.json`: read; count by severity (`high`, `med`, `low`) and by status (`open`, `triaged`, `accepted`, etc.).

### 3. Compute staleness

For every `.md` file under `architecture/`, `conventions/`, `history/decisions/`, `areas/<area>/`:

- Read frontmatter `last_verified`.
- If older than today by > 90 days: count as `stale`.
- Bucket by area for the report.

`Grep` shortcut: `Grep` for `last_verified:` across the KB, parse the date, compare. The skill can shell out to `pwsh` if needed but this is a fast in-process check.

### 3.5 Compute usage / consultation stats

The KB is only worth its build cost if it gets *consulted*. The authoritative,
retroactive view comes from the transcript scanner (parses real tool-call
records, immune to the injected prose that mentions the KB in every session):

```bash
pwsh -NoProfile -File .agents/scripts/kb-usage-audit.ps1 -Json
```

Returns `{totalSessions, maintenance, nonMaintenance, consulted, consultedPctOfNonMaint, mechanism:{askSkill,research,search,directRead}, lastConsult, topAreas[], byMonth[]}`. A session is *consulted* if it ran `/kb-ask`/`/kb-issues`, spawned `kb-research`, ran `kb-search`, or (in a non-maintenance session) read a KB file.

For the cheap "since hooks installed" view, read the live hook logs if present (gitignored, written by `track-kb-usage.js` / `track-session-start.js`):

- `.build/.agents/kb-sessions.jsonl` — one record per session start (denominator).
- `.build/.agents/kb-usage.jsonl` — one record per consultation event; distinct `session_id` with a consult `kind` (`read`/`search`/`ask-skill`/`research`) = numerator.

If neither log exists yet, report "live tracking: no data yet (hooks newly installed)" and rely on the scanner.

### 4. Print the dashboard

Compose a markdown report and print it directly. Sections, in order:

```
# KB status

## Build progress
| Step | Status | Started | Finished |
|---|---|---|---|
| 0 — bootstrap | done | ... | ... |
| ... |
| 7 — github-indexes | partial | ... |  |
| ... |

## Source freshness
| Source       | Cursor                | Age      |
|--------------|----------------------|----------|
| code         | <sha (short)>         | 3 days   |
| commits      | <sha>                 | 3 days   |
| issues       | 2026-04-22T...        | 5 days   |
| prs          | 2026-04-23T...        | 4 days   |
| discussions  | 2026-04-20T...        | 7 days   |
| wiki         | <sha>                 | 12 days  |

## Counts
- Architecture docs: 8
- Conventions: 5
- History years: 12 (2014–2026)
- History decisions: 23
- Areas with full sub-files: 18 / 22
- GH indexes: issues 4823, prs 1247, discussions 89
- Wiki articles: 34
- Detected issues: open 142 (high 18, med 81, low 43); triaged 12; accepted 7; fixed 31

## Staleness
- KB files with last_verified > 90 days: 14
  - areas/PROV-ORACLE/: 3
  - areas/PROV-FIREBIRD/: 5
  - history/decisions/: 6

## Usage
- Consulted in 10 / 228 non-maintenance sessions (4.4%); last consult 2026-06-27.
- Mechanism: /kb-ask|/kb-issues 1, kb-research 0, kb-search 1, direct read 9.
- Top consulted areas: FSHARP (5), INTERNAL-API (1), PROV-POSTGRES (1).
- Since hooks installed: 3 / 41 sessions consulted the KB.

## Recent activity
<last 10 lines from state/audit-log.md>

## Suggestions
- 14 files are >90 days old — consider /kb-refresh.
- step 7 (github-indexes) is partial: <gate failures>. Re-run /kb-build to resume.
- 4 areas missing one or more sub-files: PROV-ACCESS, PROV-INFORMIX, ASPNET, TOOLS.
- KB consulted in only 4.4% of sessions — the build cost isn't paying off; consider the discoverability improvements in agent-rules → *Consult the knowledge base*.
```

The "Suggestions" section is omitted if everything is healthy. The usage suggestion fires when `consultedPctOfNonMaint` is low (rough threshold: < 25%).

### 5. Stop

The skill prints the dashboard and exits. No follow-up actions, no questions.

## Do not

- Modify any file. Read-only.
- Spawn agents. The skill is a thin reporter; everything is in `state/` or computed from disk.
- Decide whether to refresh on the user's behalf — only suggest.
- Print the *full* `audit-log.md`; the tail of 10–20 lines is enough.

---

Source: https://www.openparable.com/skill/productivity/kb-status (OpenParable). Cite the canonical URL above.
