Knowledge Items
How Pulse AI stores durable evidence, research, decisions, and task deliverables.
The promise
Knowledge Items keep important work from disappearing into chat, temporary files, or one-off terminal output. They are the durable evidence package a reviewer can reopen later.
A KI can hold research, a task closeout, a deck, a Markdown summary, screenshots, validation output, audio narration, or source maps. The point is not archival neatness. The point is reviewability.
What belongs in a Knowledge Item
| File or field | Purpose | Reviewer question it answers |
|---|---|---|
metadata.json | Title, summary, review flags, references, tags, artifact list. | What is this package and does it need review? |
timestamps.json | Created, modified, and accessed timing. | When was this evidence generated? |
overview.md | Human-readable summary of what changed and what passed. | What should I understand before opening artifacts? |
artifacts/ | Decks, Markdown summaries, screenshots, logs, WAV narration, or data files. | Where is the actual proof? |
needsReview | Review queue signal for the Knowledge surface. | Should a human look at this? |
reviewed | Current review state for the KI. | Has someone already accepted or dismissed it? |
For task deliverables, use scripts/finalize-deliverable.js so the KI and the board item stay linked. The script creates the KI structure, records artifacts, sets needsReview, and writes the deliverables entry back to the task.
How reviewers use one
Reviewers should treat a KI as a package of claims and evidence:
- Read
overview.mdfor the claim and scope boundary. - Open the deck or Markdown artifact for the structured explanation.
- Check screenshots or logs against the current product/source when the task is visual or runtime-sensitive.
- Confirm narration matches the closeout when voice is part of the deliverable.
- Compare references to the task and source files before approving.
A KI is not true because it exists. Old KIs can be stale. The review question is whether the package still matches the live source and the current task.
Example: evidence package anatomy
The web-fix-reset-password-memory-leak KI shows the expected anatomy:
| Package part | Example evidence |
|---|---|
| Task reference | web-fix-reset-password-memory-leak in metadata.json references. |
| Overview | Explains that the closeout verified the auth listener cleanup and did not claim a sibling recovery-mode fix. |
| Presentation | artifacts/web-fix-reset-password-memory-leak.html gives the reviewable deck. |
| Narration | artifacts/web-fix-reset-password-memory-leak-narration.wav matches the deck. |
| Review flag | needsReview: true and reviewed: false keep the package visible for human review. |
This example is useful because it separates artifact existence from proof quality. The reviewer still checks whether the listener claim matches the source and validation output.
Media needs
Knowledge Items are the right place for proof media:
| Media type | Use it when |
|---|---|
| Product screenshot | The task changed a visible surface, such as the Review Queue or Knowledge Items page. |
| Deck screenshot | The reviewer needs a fast visual preview before opening the full HTML. |
| Validation log | The core proof is a passing command or package validation run. |
| Audio file | Voice preferences require narration or the deliverable is meant to be heard. |
Store media under artifacts/ and describe it in metadata.json. Do not leave proof only in /tmp, chat, or an unlinked local file.