Kb Status
Productivitykb-statusKb 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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/linq2db/linq2db/blob/HEAD/.agents/skills/kb-status/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/kb-status, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
/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-refreshis needed. - Before starting fresh work on a feature/bug — to confirm the KB's most recent verified SHA.
- After
/kb-buildfinishes — to confirm all steps aredone.
Steps
1. Pull state summary
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.mdfiles.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.mdfiles.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):
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; distinctsession_idwith a consultkind(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.