007-reports-directory-for-generated-snapshots

Type: adr · Status: proposed · Tags: architecture

Status: proposed Date: 2026-03-24

Context

The KB currently has two primary homes for non-source content:

  • kb/notes/ — durable claims and insights. Value accumulates. Authored by humans or agents making knowledge claims.
  • kb/work/ — temporal work-in-flight. Value is consumed. Workshop artifacts have lifecycles and expiration.

A third category is emerging: generated analytical snapshots — computed from the current state of the KB, not authored as claims. Examples:

  • Promotion candidates report — text files with enough connection pressure to warrant /convert, seedlings with enough incoming links to warrant promotion to current.
  • Orphan report — notes with no incoming or outgoing links.
  • Stale link report — links pointing to moved or deleted files.
  • Coverage report — areas or tags with few notes, gaps in index coverage.

These don't fit either existing home:

  • They're not notes — they make no claim, carry no insight. They're derived from the graph, not from reasoning. Putting them in kb/notes/ pollutes search results and inflates the index with non-knowledge artifacts.
  • They're not workshop artifacts — they have no lifecycle or state machine. They're not work-in-flight that gets consumed. They're snapshots that get regenerated — the old version is simply replaced, not archived or completed.

Decision

Create kb/reports/ for generated, regenerable analytical snapshots.

Properties that distinguish reports from other artifact types:

Property Notes Workshop Reports
Value model Accumulates Consumed Replaced
Authorship Authored (claim) Authored (work) Generated (computed)
Lifecycle Permanent Temporal → archive/discard Regenerate in place
Staleness Bug Feature (urgency) Expected (regenerate)
Git tracking Yes Yes Optional — can be gitignored if regeneration is cheap

Reports are generated by scripts or skills that read KB state and produce a snapshot. The generation command should be documented in the report itself (or in a companion script) so any agent can regenerate it.

The existing reviews/ directory — individual review files, summaries, and ranked CSV tables produced by review sweeps — moves to kb/reports/reviews/. These are the prototypical report: generated by scripts, regenerable in place, no authored claims.

The next report will be a promotion candidates report covering: - Text files (no frontmatter) that have been mentioned in connection reports or linked from notes — candidates for /convert - Seedling notes with high incoming link counts or load-bearing relationships — candidates for promotion to current

Consequences

Easier: - Generated snapshots have a clear home. No more question about where an orphan report or coverage analysis goes. - kb/notes/ stays clean — search over notes returns knowledge, not diagnostics. - Reports can be gitignored without losing anything — they're regenerable. This keeps the repo focused on authored content. - The /connect skill's "Raw text" subsection feeds directly into the promotion report — connection reports accumulate evidence, the promotion report aggregates it.

Harder: - Another top-level directory under kb/. The routing table in CLAUDE.md needs updating. - Reports that reference notes by path are fragile to renames. But they're regenerable, so this is a minor inconvenience, not data loss. - The boundary between "report" and "workshop artifact" can blur — a report that triggers manual review starts to feel like a task. The distinction is: reports are stateless snapshots (regenerate replaces), workshop artifacts have state (in-progress, completed).

Relevant Notes: