evidence-handling

name	evidence-handling
description	Handle imported and extracted material correctly. Use when placing content in Evidence/, importing web pages or docs, recording captures, or deciding what is and isn't canonical.

Evidence Handling

Evidence is not memory. This skill covers every Evidence/ area, what goes where, what rules apply, and how to keep evidence from polluting curated memory.

---

Evidence areas and their rules

agent-knowledge/
  Evidence/
    raw/          <- unprocessed extracted material (git log, file dumps, scan output)
    imports/      <- cleaned or processed imported content (docs, web pages)
    captures/     <- automatic event stream (sync, update, ship events)
  Outputs/        <- generated views (indexes, HTML export, dashboards)
                     treated like evidence: non-canonical, regeneratable

All evidence is non-canonical. None of it is ever auto-promoted into Memory/. Outputs are also non-canonical.

---

Evidence/raw/

Use for:

• Raw git log extracts
• Unprocessed file dumps
• Raw command output
• Unfiltered scan results

Rules:

• Keep files small; trim or paginate large outputs
• Add a YAML frontmatter block with note_type: evidence, source, and extracted timestamp
• Do not edit raw evidence after creation; create a new file instead
• Filename convention: <topic>-<YYYY-MM-DD>.md or the auto-generated git-recent.md

Template:

---
note_type: evidence
source: git-log
extracted: 2025-01-15T14:00:00Z
---

# Raw: Git Log (2025-01-15)

(content)

---

Evidence/imports/

Use for:

• Web pages imported via bedrock clean-import
• Documentation imported from external sources
• Third-party reference material
• Cleaned-up versions of raw evidence

Rules:

• Always mark with note_type: evidence and canonical: false
• Include source: and imported: in frontmatter
• Prefer cleaned markdown over raw HTML
• Do not include entire large docs -- trim to the relevant sections
• Use bedrock clean-import <url> to create well-structured imports

Template:

---
note_type: evidence
source: https://docs.example.com/api-reference
imported: 2025-01-15T14:00:00Z
canonical: false
---

# Imported: API Reference (2025-01-15)

(cleaned content)

---

Evidence/captures/

Auto-written by bedrock sync, update, ship, and hook events.

Rules:

• Do NOT manually create capture files; let the CLI write them
• Do NOT edit capture files
• Do NOT promote captures to Memory/ -- they are historical record, not curated fact
• Captures prune to 30 most recent on bedrock compact
• Each capture has: timestamp, source_tool, event_type, project_slug, changed_paths, touched_branches, summary, confidence

---

Outputs/ (non-canonical)

Generated by bedrock sync, index, export-html, export-canvas.

Rules:

• Never treat Outputs/ content as source of truth
• Do not write decisions or stable facts into Outputs/
• Outputs are regeneratable; agents should not depend on their exact content
• knowledge-index.json and .md are layer-1 retrieval aids, not ground truth

---

What belongs where: quick reference

Content	Location
Raw git log	Evidence/raw/git-recent.md
Imported web page	Evidence/imports/<slug>.md
Sync/update events	Evidence/captures/<timestamp>-<event>.yaml
Generated index	Outputs/knowledge-index.json
HTML viewer	Outputs/knowledge-export.html
Canvas view	Outputs/knowledge-export.canvas
Stable, verified project facts	Memory/<branch>.md
Active architectural decisions	Memory/decisions/<date>-<slug>.md

---

Promoting evidence to memory

Do NOT auto-promote. The agent must manually verify and distill:

1. Read the evidence item
2. Identify stable, verified facts (not speculations or outdated state)
3. Write only the facts to the relevant Memory/ branch note under Current State
4. Add a Recent Changes entry noting the source
5. Do NOT copy the whole evidence item -- distill it

Example:

Evidence/imports/api-reference-2025-01-15.md
  contains: "Rate limit is 1000 requests/hour per API key"
  -> verified against current API response headers

Memory/integrations.md
  Current State:
  - API rate limit: 1000 requests/hour per key. Confirmed 2025-01-15.

---

Ignoring noisy paths

Use .agentknowledgeignore to exclude paths from evidence imports:

node_modules/
dist/
.git/
*.lock
coverage/

Paths listed here are skipped during bedrock import and bedrock update.

---

Evidence freshness

Evidence goes stale. Check dates before relying on imports:

• If imported: is older than 30 days, treat with caution
• Re-import or verify against live source if the fact matters
• Raw evidence (git log) is refreshed on each sync; check extracted: timestamp