# shoyann/rzk-the-hunter architecture

> Architecture diagram of the GitHub repository shoyann/rzk-the-hunter, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/shoyann/rzk-the-hunter
- Repository: https://github.com/shoyann/rzk-the-hunter

## Overview

The Hunter is an agent-native OSINT investigation skill: its operating instructions scope a question, guide evidence-changing research, and converge on a defensible report. The README documents adaptive strategy, domain playbooks, a tool catalog, and traceable evidence; sampled scripts implement catalog search/selection, evidence bookkeeping, visual case support, and trajectory auditing. Edges are limited to relationships shown in the README or excerpts; unsampled workflow details are represented without inferred call chains.

Main entry points: [`SKILL.md`](https://github.com/shoyann/rzk-the-hunter/blob/main/SKILL.md) (Agent instructions), [`scripts/select_tools.py`](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/select_tools.py) (Tool selection), [`scripts/search_catalog.py`](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/search_catalog.py) (Catalog search), [`references/adaptive-investigation-strategy.md`](https://github.com/shoyann/rzk-the-hunter/blob/main/references/adaptive-investigation-strategy.md) (Adaptive strategy)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_investigation["Investigation guidance"]
  node_entry["Agent instructions<br/>[SKILL.md]"]
  node_strategy["Adaptive strategy"]
  node_convergence["Hypothesis convergence"]
  node_safety["Safety policy<br/>[safety-policy.md]"]
  node_playbooks["Domain workflows"]
end

subgraph group_discovery["Tool discovery"]
  node_catalog[("OSINT catalog<br/>[catalog.json]")]
  node_cataloglib["Catalog logic<br/>[cataloglib.py]"]
  node_search["Catalog search<br/>[search_catalog.py]"]
  node_selection["Tool selection<br/>[select_tools.py]"]
end

subgraph group_evidence["Evidence handling"]
  node_ledger["Evidence ledger<br/>[evidence_ledger.py]"]
  node_visualcase["Visual case tools<br/>[visual_case.py]"]
  node_board["Visual evidence board<br/>[evidence_board.py]"]
end

subgraph group_outputs["Reporting and audit"]
  node_trajectory["Trajectory audit<br/>[trajectory_eval.py]"]
  node_templates["Report templates"]
end

node_analyst(("Researcher"))
node_publicsources(("Public sources"))
node_report["Investigation report"]

node_analyst -->|"invokes"| node_entry
node_entry -->|"routes to"| node_strategy
node_entry -->|"routes to"| node_playbooks
node_entry -->|"applies"| node_safety
node_entry -->|"tests hypotheses"| node_convergence
node_strategy -.->|"selects tools"| node_selection
node_search -->|"uses"| node_cataloglib
node_selection -->|"uses"| node_cataloglib
node_search -->|"reads"| node_catalog
node_selection -->|"reads"| node_catalog
node_playbooks -->|"guides research"| node_publicsources
node_entry -->|"records evidence"| node_ledger
node_entry -->|"supports geolocation"| node_visualcase
node_visualcase -->|"may illustrate"| node_board
node_entry -->|"audits actions"| node_trajectory
node_entry -->|"uses outputs"| node_templates
node_entry -->|"produces"| node_report

click node_entry "https://github.com/shoyann/rzk-the-hunter/blob/main/SKILL.md"
click node_strategy "https://github.com/shoyann/rzk-the-hunter/blob/main/references/adaptive-investigation-strategy.md"
click node_convergence "https://github.com/shoyann/rzk-the-hunter/blob/main/references/hypothesis-convergence.md"
click node_safety "https://github.com/shoyann/rzk-the-hunter/blob/main/references/safety-policy.md"
click node_playbooks "https://github.com/shoyann/rzk-the-hunter/tree/main/workflows"
click node_catalog "https://github.com/shoyann/rzk-the-hunter/blob/main/references/catalog.json"
click node_cataloglib "https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/cataloglib.py"
click node_search "https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/search_catalog.py"
click node_selection "https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/select_tools.py"
click node_ledger "https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/evidence_ledger.py"
click node_visualcase "https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/visual_case.py"
click node_board "https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/evidence_board.py"
click node_trajectory "https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/trajectory_eval.py"
click node_templates "https://github.com/shoyann/rzk-the-hunter/tree/main/templates"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_entry,node_strategy,node_convergence,node_safety,node_playbooks toneBlue
class node_catalog,node_cataloglib,node_search,node_selection toneAmber
class node_ledger,node_visualcase,node_board toneMint
class node_trajectory,node_templates toneRose
class node_analyst,node_publicsources,node_report toneIndigo
```

## Components

### Investigation guidance

- [Agent instructions](https://github.com/shoyann/rzk-the-hunter/blob/main/SKILL.md): `SKILL.md`
- [Adaptive strategy](https://github.com/shoyann/rzk-the-hunter/blob/main/references/adaptive-investigation-strategy.md): `references/adaptive-investigation-strategy.md`
- [Hypothesis convergence](https://github.com/shoyann/rzk-the-hunter/blob/main/references/hypothesis-convergence.md): `references/hypothesis-convergence.md`
- [Safety policy](https://github.com/shoyann/rzk-the-hunter/blob/main/references/safety-policy.md): `references/safety-policy.md`
- [Domain workflows](https://github.com/shoyann/rzk-the-hunter/tree/main/workflows): `workflows`

### Tool discovery

- [OSINT catalog](https://github.com/shoyann/rzk-the-hunter/blob/main/references/catalog.json): `references/catalog.json`
- [Catalog logic](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/cataloglib.py): `scripts/cataloglib.py`
- [Catalog search](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/search_catalog.py): `scripts/search_catalog.py`
- [Tool selection](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/select_tools.py): `scripts/select_tools.py`

### Evidence handling

- [Evidence ledger](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/evidence_ledger.py): `scripts/evidence_ledger.py`
- [Visual case tools](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/visual_case.py): `scripts/visual_case.py`
- [Visual evidence board](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/evidence_board.py): `scripts/evidence_board.py`

### Reporting and audit

- [Trajectory audit](https://github.com/shoyann/rzk-the-hunter/blob/main/scripts/trajectory_eval.py): `scripts/trajectory_eval.py`
- [Report templates](https://github.com/shoyann/rzk-the-hunter/tree/main/templates): `templates`

### Other components

- **Researcher**
- **Public sources**
- **Investigation report**

## Connections

- Researcher → Agent instructions: invokes (evidence: `README.md`)
- Agent instructions → Adaptive strategy: routes to (evidence: `README.md`)
- Agent instructions → Domain workflows: routes to (evidence: `README.md`)
- Agent instructions → Safety policy: applies (evidence: `README.md`)
- Agent instructions → Hypothesis convergence: tests hypotheses (evidence: `README.md`)
- Adaptive strategy → Tool selection: selects tools
- Catalog search → Catalog logic: uses (evidence: `scripts/search_catalog.py`)
- Tool selection → Catalog logic: uses (evidence: `scripts/select_tools.py`)
- Catalog search → OSINT catalog: reads (evidence: `scripts/search_catalog.py`)
- Tool selection → OSINT catalog: reads (evidence: `scripts/select_tools.py`)
- Domain workflows → Public sources: guides research (evidence: `README.md`)
- Agent instructions → Evidence ledger: records evidence (evidence: `README.md`)
- Agent instructions → Visual case tools: supports geolocation (evidence: `README.md`)
- Visual case tools → Visual evidence board: may illustrate (evidence: `README.md`)
- Agent instructions → Trajectory audit: audits actions (evidence: `README.md`)
- Agent instructions → Report templates: uses outputs (evidence: `README.md`)
- Agent instructions → Investigation report: produces (evidence: `README.md`)