---
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

```text
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:
```markdown
---
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 `agent-knowledge 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 `agent-knowledge clean-import <url>` to create well-structured imports

Template:
```markdown
---
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 `agent-knowledge 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 `agent-knowledge compact`
- Each capture has: `timestamp`, `source_tool`, `event_type`, `project_slug`, `changed_paths`, `touched_branches`, `summary`, `confidence`

---

## Outputs/ (non-canonical)

Generated by `agent-knowledge 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 `agent-knowledge import` and `agent-knowledge 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
