analyst

Files (24)

• plugin.json · .claude-plugin/
• .python-version
• .standalone-db
• SKILL.md
• analyst.py
• consensus-matrix.tsx · dashboard/components/
• findings-table.tsx · dashboard/components/
• gate-panel.tsx · dashboard/components/
• missions-board.tsx · dashboard/components/
• lib.ts · dashboard/
• page.tsx · dashboard/pages/analyst/mission/[id]/
• page.tsx · dashboard/pages/analyst/
• route.ts · dashboard/routes/findings/
• route.ts · dashboard/routes/gate/
• route.ts · dashboard/routes/mission/[id]/
• route.ts · dashboard/routes/missions/
• hub.yaml · dashboard/views/
• mission.yaml · dashboard/views/
• engines.yaml
• hooks.json · hooks/
• pyproject.toml
• quality-checks.yaml
• schema.tql
• skill.yaml

SKILL.md (first lines)

# Analyst — the research analyst you always wanted

Use this skill to run research the way an executive briefs an analyst, not the way
people query a search engine. Every mission is framed by a **decision**, constrained
by time horizon / source policy / exclusions, and executed by **commissioning the
research engines** declared in [`engines.yaml`](engines.yaml): the analyst frames
the questions, dispatches them to an engine, reads the reports back in the
decision's context, aggregates consensus, **verifies in a fresh thread**, and
passes everything through the **three-question gate** before it touches a decision.

**Division of labour (explicit, configured):** the analyst does NOT discover or
ingest — the engines do. `engines.yaml` is the analyst→engine contract; the
`dispatch` command validates against it, and its output echoes the engine's
invoke/ingest instructions. The analyst owns what no engine does: decision
framing, question setting, claim-level consensus and verification bookkeeping,
and the operator's sign-off gate — feeding decisions managed by the personal
assistant suite (`advisor`, `career`, `ops`, surfaced by `chief-of-staff`).

**Key principle:** the script stores and queries; Claude does the sensemaking
(interviewing, question-framing, reading reports, matching claims across
engines, verifying, synthesizing).

This skill operationalizes the repo's [operating principles](../../docs/operating-principles.md):
primer notes (speak, don't type), interview-first, plan/execute split, explicit
⏸ OPERATOR CHECKPOINT moments, wisdom-of-the-crowd, and the three-question gate.

---

## Routing — when to use the analyst vs. an engine directly

| The ask | Route |
|---------|-------|
| Research that informs a decision in flight (advisor/career/ops) | **analyst mission** — it commissions engines and books the evidence |
| "Compare tools / evaluate X / survey a tech space" with no decision record needed | `tech-recon` directly |
| "What does the literature say about X" standalone | `scientific-literature` directly |
| Quick one-off web question | `/deep-research` skill or an ad-hoc thread |

If a mission's question is technology-shaped, the analyst still doesn't do the
work — it dispatches to `tech-recon` and reads the investigation back. Run
`analyst.py list-engines` for the live contract.

---

## Quick Start

### Prerequisites

- TypeDB running with the `alh_personal` database (provisioned by this skill's
  SessionStart hook when installed as a plugin)
- `uv` available; run commands from the skill directory or with `--project`

### Environment Variables

- `TYPEDB_HOST`: TypeDB server (default: localhost)
- `TYPEDB_PORT`: TypeDB port (default: 1729)
- `TYPEDB_DATABASE`: Database name (default: alh_personal)

### Essential Commands

```bash
# Open a mission (always capture the operator's messy primer)
uv run python skills/analyst/analyst.py create-mission \
    --name "EU battery market entry" \
    --decision-context "Whether to open an EU manufacturing line in 2027" \
    --time-horizon "2026-2029" --priority high \
    --primer "Voice-dictated brain dump, unedited..."

# Fan out parallel runs
uv run python skills/analyst/analyst.py add-run --mission mission-abc123 --model "claude-opus"

# Record a discrete claim from a run
uv run python skills/analyst/analyst.py add-finding --run run-def456 \
    --claim "EU battery demand grows ~30% CAGR through 2028" --confidence high

# Aggregate consensus for one claim group (agent matches the claims)
uv run python skills/analyst/analyst.py record-consensus \
    --findings finding-a1 finding-b2 finding-c3 --agree 3

# See what needs attention
uv run python skills/analyst/analyst.py list-findings --divergent
uv run python skills/analyst/analyst.py report-mission --id mission-abc123
```

### Command Output Pattern

`uv run` emits a `VIRTUAL_ENV` warning to stderr. Always use `2>/dev/null` when
piping output to a JSON parser -- never `2>&1`, which merges the warning into
stdout and breaks JSON parsing.

---

## The Workflow

Everything between checkpoints is agent work. The operator steps in only at the
⏸ OPERATOR CHECKPOINT moments.

### 1. Brief — capture the primer  ⏸ OPERATOR CHECKPOINT

Ask the operator for their messy, unstructured brain dump (voice dictation is
ideal): what decision is at stake, what they already believe, hunches, constraints,
politics, prior attempts. Do NOT ask them to structure it — you structure it.

```bash
analyst.py create-mission --name "..." --decision-context "..." --primer "<verbatim dump>"
```

A mission without `--decision-context` triggers a warning: research without a
decision in mind is a search-engine query, not an analyst brief.

### 2. Interview — surface unknown-unknowns  ⏸ OPERATOR CHECKPOINT

Before planning, interview the operator like a senior analyst taking a brief:

- What decision will this research change, and when is it made?
- Time horizon? Which sources count (and which are banned)? What is out of scope?
- What assumptions are you already making? What would change your mind?
- What haven't you considered? What context should you give me that I can't find?

Record the full Q&A: `analyst.py add-interview --mission <id> --content-file qa.md`,

From sciknow-io/alhazen-skill-personal-assistant, MIT.

More from sciknow-io/alhazen-skill-personal-assistant