hm-l3-research-chain

Files (9)

• SKILL.md
• evals.json · evals/
• .gitkeep · metrics/
• rich-gate-scorecard.md · metrics/
• chain-stages.md · references/
• tool-matrix.md · references/
• validate-skill.sh · scripts/
• .gitkeep · templates/
• chain-continuation.md · templates/

SKILL.md (first lines)

## Overview

Orchestrate the canonical research pipeline: detect → research → synthesize → artifact. Use when starting research tasks, chaining investigation skills, producing final artifacts from multiple sources, or when research needs to be structured and repeatable. Produces synthesized research outputs with citation tracking and evidence persistence.

## The Iron Law

```
Research without synthesis is hoarding. Synthesis without evidence is hallucination.
Ingestion without caching is repetition.
```

# Research Chain
## The Canonical Chain

```
┌──────────┐     ┌─────────────┐     ┌──────────────┐     ┌───────────┐     ┌──────────┐
│  INGEST  │ ──→ │   DETECT    │ ──→ │   RESEARCH   │ ──→ │ SYNTHESIZE│ ──→ │ ARTIFACT │
│(hm-tech-  │     │(hm-detective)│     │(hm-deep-     │     │(hm-synthesis)│   │ (export) │
│ stack-ingest)│  │             │     │   research)  │     │           │     │          │
└──────────┘     └─────────────┘     └──────────────┘     └───────────┘     └──────────┘
```

### Stage 0: Ingest (hm-tech-stack-ingest)

**Purpose:** Cache third-party repositories, SDK docs, and API references BEFORE researching. This ensures all downstream stages validate against REAL code, not assumptions.

```bash
# Check if the target tech stack is already cached
ls references/tech-stacks/<name>/ && cat references/tech-stacks/<name>/metadata.json

# If missing or stale, run the ingestion pipeline
# hm-tech-stack-ingest handles: DETECT → DISCOVER → INGEST → ORGANIZE → INDEX
```

**Output:** Cached tech stack in `references/tech-stacks/<name>/` with TOC.md, metadata.json, api/, docs/, examples/

**Gate:** Cached assets must have valid `metadata.json` with `version`, `source_url`, and `ingest_date`. If the cached version differs from the installed version, re-ingestion must complete before research starts.

### Stage 1: Detect (hm-detective)

**Purpose:** Understand what you are looking at before researching.

```bash
# SCAN mode — tech stack detection
# READ mode — targeted file reads
# DEEP mode — comprehensive codebase scan
```

**Output:** `.tech-registry.json` + initial findings

**Gate:** detection output must name scope, search modes used, and any missing/inaccessible areas before research starts.

### Stage 2: Research (hm-deep-research)

**Purpose:** Gather evidence using version-matched documentation and MCP tools.

```bash
# Context7 for API verification
# Tavily for current information
# Repomix for codebase structure
```

**Output:** Structured findings with citations

**Gate:** research output must include source evaluation, contradiction status, and blocked-source notes before synthesis starts.

### Stage 3: Synthesize (hm-synthesis)

**Purpose:** Compress findings into actionable artifacts.

```bash
# Compression tiers: Snapshot → Focused → Signature
# Artifact export: markdown, JSON, or plan files
```

**Output:** Final artifact (report, plan, or specification)

**Gate:** synthesis output must include methodology/limitations and link each recommendation to evidence.

### Stage 4: Artifact + Continuation

**Purpose:** Persist lineage so a later agent can resume without rediscovering the chain.

**Required artifact metadata:**

```yaml
research_chain_id: YYYY-MM-DD-topic-slug
detect_artifact: path-or-summary
research_artifact: path-or-summary
synthesis_artifact: path-or-summary
sources_reviewed: []
blocked_sources: []
contradictions: resolved | unresolved | none
next_action: verify | implement | ask | block
```

**Stop rule:** If a required stage artifact is missing, return `BLOCKED` with the missing gate. Do not synthesize or mark complete from partial chain state.

## When to Use the Full Chain

| Situation | Use Chain? |
|-----------|-----------|
| Exploring an unfamiliar codebase | Yes — full chain |
| Verifying a single API signature | No — Context7 only |
| Writing a project specification | Yes — full chain |
| Quick bug investigation | Partial — detect + research, skip synthesis |
| Producing a migration plan | Yes — full chain |

## Anti-Patterns

| Anti-Pattern | Detection | Correction |
|-------------|-----------|------------|
| **The Skipped Detect** | Jumps straight to research without scanning | Always run hm-detective SCAN first |
| **The Hoarder** | Gathers 50 sources but never synthesizes | Cap research time, force synthesis stage |
| **The Single-Source** | Uses only one tool (e.g., only web search) | Use the full MCP matrix |
| **The Orphan Artifact** | Produces artifact but never links to source evidence | Every claim in artifact must cite source |
| **The Ungated Chain** | Starts a later stage while prior stage output is missing | Stop and create the missing stage artifact first |

## Self-Correction

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin