Skills: Tech Recon

Goal-driven technology investigation — systematically research, compare, and visualize competing systems against user-defined success criteria.

Purpose

Tech-recon turns technology evaluation from ad hoc web searches into a structured, queryable investigation. It runs an 8-question interview to define your goal and success criteria, discovers candidate systems, ingests their documentation, writes structured notes via parallel subagents, and renders Observable Plot visualizations in a dashboard.

Use this skill when you need to choose between frameworks, databases, libraries, or platforms — especially when the decision involves multiple criteria and multiple candidates.

The 7-Phase Pipeline

Phase	Name	What Happens
1	Interview	8 conversational questions → goal + success criteria
2	Discovery	Find candidate systems; user approves list
3	Ingestion	Parallel subagents ingest primary sources per system
4	Sensemaking	Parallel subagents write structured notes per system
5	Viz Planning	Propose visualizations mapped to success criteria
6	Analysis	Implement Observable Plot visualizations
7	Dashboard	Browse at `http://localhost:3001/tech-recon`

Prerequisites

TypeDB running: make db-start
Dependencies installed: uv sync --all-extras
Dashboard (for Phase 7): cd dashboard && npm run dev or docker compose up -d dashboard

Commands

Investigation Lifecycle

# Start a new investigation (after interview)
uv run python .claude/skills/tech-recon/tech_recon.py start-investigation \
    --name "Graph DB alternatives" \
    --goal "Choose a graph DB for knowledge graph + agent memory" \
    --success-criteria "Schema inference, Python API, active community, open source"

# Show investigation details
uv run python .claude/skills/tech-recon/tech_recon.py show-investigation \
    --id INVESTIGATION_ID

# Advance to next iteration
uv run python .claude/skills/tech-recon/tech_recon.py advance-iteration \
    --investigation INVESTIGATION_ID

Discovery

# Add a candidate system
uv run python .claude/skills/tech-recon/tech_recon.py add-system \
    --investigation INVESTIGATION_ID \
    --name "TypeDB" \
    --url "https://typedb.com" \
    --github-url "https://github.com/typedb/typedb" \
    --description "Polymorphic database with type theory foundations"

# List candidate systems
uv run python .claude/skills/tech-recon/tech_recon.py list-systems \
    --investigation INVESTIGATION_ID

# Approve a system for ingestion
uv run python .claude/skills/tech-recon/tech_recon.py approve-system \
    --id SYSTEM_ID

Ingestion

# Ingest homepage
uv run python .claude/skills/tech-recon/tech_recon.py ingest-page \
    --url "https://typedb.com" --system SYSTEM_ID

# Ingest GitHub repository (README + file tree)
uv run python .claude/skills/tech-recon/tech_recon.py ingest-repo \
    --url "https://github.com/typedb/typedb" --system SYSTEM_ID

# Ingest documentation site (recursively)
uv run python .claude/skills/tech-recon/tech_recon.py ingest-docs \
    --url "https://typedb.com/docs" --system SYSTEM_ID --max-pages 20

# Ingest a PDF (whitepaper, paper)
uv run python .claude/skills/tech-recon/tech_recon.py ingest-pdf \
    --url "https://example.com/paper.pdf" --system SYSTEM_ID

# List artifacts
uv run python .claude/skills/tech-recon/tech_recon.py list-artifacts \
    --system SYSTEM_ID

# Show artifact content
uv run python .claude/skills/tech-recon/tech_recon.py show-artifact \
    --id ARTIFACT_ID

Sensemaking

# Write a structured note (topics: architecture, api, data-model, integration,
#   performance, community, comparison, assessment)
uv run python .claude/skills/tech-recon/tech_recon.py write-note \
    --system SYSTEM_ID \
    --topic architecture \
    --content "## Architecture\n\nTypeDB uses a polymorphic type system..."

# Note about the investigation (cross-system)
uv run python .claude/skills/tech-recon/tech_recon.py write-note \
    --investigation INVESTIGATION_ID \
    --topic comparison \
    --content "## Cross-System Comparison\n\n..."

# List notes
uv run python .claude/skills/tech-recon/tech_recon.py list-notes \
    --system SYSTEM_ID

uv run python .claude/skills/tech-recon/tech_recon.py list-notes \
    --investigation INVESTIGATION_ID --topic assessment

# Show note
uv run python .claude/skills/tech-recon/tech_recon.py show-note \
    --id NOTE_ID

Analysis and Visualization

# Generate a visualization plan from notes + success criteria
uv run python .claude/skills/tech-recon/tech_recon.py plan-analyses \
    --investigation INVESTIGATION_ID

# Add an analysis (after user approves plan)
uv run python .claude/skills/tech-recon/tech_recon.py add-analysis \
    --investigation INVESTIGATION_ID \
    --title "GitHub Stars Comparison" \
    --analysis-type bar \
    --query "match \$s isa tech-recon-system, has name \$n, has star-count \$sc; fetch { \"name\": \$n, \"stars\": \$sc };" \
    --plot-code "Plot.barY(data, {x: 'name', y: 'stars'}).plot()"

# Run an analysis (executes TQL, returns data for dashboard)
uv run python .claude/skills/tech-recon/tech_recon.py run-analysis \
    --id ANALYSIS_ID

# List all analyses
uv run python .claude/skills/tech-recon/tech_recon.py list-analyses \
    --investigation INVESTIGATION_ID

Typical Workflow

You: I need to choose a vector database for semantic search

Agent: [runs 8-question interview, one question per turn]
       [synthesizes goal + success criteria, shows for approval]

Agent: start-investigation --name "Vector DB selection" ...

You: Search for candidates

Agent: [uses web-search + GitHub to find 5-6 candidates]
       [presents table for approval]

You: Looks good, let's go

Agent: [dispatches ingestion subagents in parallel, 1 per system]
       [dispatches sensemaking subagents in parallel, 1 per system]
       [proposes viz plan: star comparison, license matrix, Python API feature table]

You: Approved

Agent: [implements Observable Plot charts]
       [opens http://localhost:3001/tech-recon]

Schema

Entities

Entity	Subtype of	Key Attributes
`tech-recon-investigation`	`collection`	`goal-description`, `success-criteria`
`tech-recon-system`	`domain-thing`	`url`, `github-url`, `language`, `license`, `star-count`, `status`
`tech-recon-artifact`	`artifact`	`artifact-type`, `url`, `content`, `cache-path`
`tech-recon-analysis`	`artifact`	`title`, `description`, `analysis-type`, `plot-code`, `tql-query`
`tech-recon-note`	`note`	`topic`, `tag`, `content`

Relations

Relation	Purpose
`investigated-in`	Links system to investigation
`sourced-from`	Links artifact to system or investigation
`analysis-of`	Links analysis to investigation
`aboutness` (core)	Links notes to systems or investigations
`collection-membership` (core)	Links systems into investigations

Dashboard

URL: http://localhost:3001/tech-recon

Route	Content
`/tech-recon`	All investigations with goal and status
`/tech-recon/[id]`	Investigation detail: systems, notes, analyses
`/tech-recon/[id]/system/[sid]`	System detail: artifacts and notes
`/tech-recon/[id]/analyses`	Visualization gallery
`/tech-recon/[id]/analysis/[aid]`	Single visualization with Observable Plot render

Tech Recon