hm-l3-deep-research

Files (18)

• SKILL.md
• .gitkeep · evals/
• evals.json · evals/
• .gitkeep · metrics/
• rich-gate-scorecard.md · metrics/
• brainstorming-shaping.md · references/
• case-comparison.md · references/
• edge-cases.md · references/
• interface-tradeoffs.md · references/
• requirements-vs-spec.md · references/
• research-patterns.md · references/
• .gitkeep · scripts/
• validate-rich-package.sh · scripts/
• .gitkeep · templates/
• contradiction-matrix.md · templates/
• source-evaluation.md · templates/
• .gitkeep · workflows/
• sequential-research-gates.md · workflows/

SKILL.md (first lines)

## Overview

Conduct version-matched deep research with MCP tools and citation tracking. Use when investigating libraries, verifying API signatures, gathering multi-source evidence, or producing comprehensive research reports. Returns structured findings with citations and evidence persistence.

## Quick Jump

| Research Need | Start Here |
|---------------|------------|
| "This case vs. that case" | [Case Comparison](references/case-comparison.md) |
| "Something went wrong" | [Edge Cases](references/edge-cases.md) |
| "When do I stop researching?" | [Requirements vs. Spec](references/requirements-vs-spec.md) |
| "Where do I draw the line?" | [Interface Tradeoffs](references/interface-tradeoffs.md) |
| "Turn findings into features" | [Brainstorming & Shaping](references/brainstorming-shaping.md) |
| "What kind of research am I doing?" | [Research Patterns](references/research-patterns.md) |
| "This is high-stakes or exhaustive" | [Sequential Research Gates](workflows/sequential-research-gates.md) |
| "Which sources should I trust?" | [Source Evaluation Template](templates/source-evaluation.md) |
| "Sources disagree" | [Contradiction Matrix](templates/contradiction-matrix.md) |

<execution_context>
For reading modes during investigation: load skill "hm-detective"
Reading modes: SKIM for orientation, SCAN for targeted extraction, DEEP for interface analysis

For cached tech stack assets (offline API signatures, repo references): load skill "hm-tech-stack-ingest"
Cross-architecture research routing: When hm-tech-stack-ingest has cached a library, use the cached
API signatures instead of Context7 or web searches. This validates against REAL code, not assumptions.

For artifact export and compression: load skill "hm-synthesis"
Export tier: Standard (findings + decisions) for most research
Compression: Snapshot for full analysis, Focused for targeted investigation

For chain orchestration: load skill "hm-research-chain"
hm-deep-research is Stage 2 of the canonical research chain.
</execution_context>

## Cross-Architecture Research Routing

When `hm-tech-stack-ingest` has cached a library's full source, API signatures, or documentation, route research requests through cached assets BEFORE external MCP tools.

### Routing Decision Tree

```
Is the target library cached in references/tech-stacks/<name>/?
├── YES → Use cached assets first
│   ├── Need API signature? → grep references/tech-stacks/<name>/api/
│   ├── Need full source? → read references/tech-stacks/<name>/raw/
│   ├── Need usage examples? → read references/tech-stacks/<name>/examples/
│   └── Cached version differs from installed? → Flag discrepancy, use installed version
└── NO → Use MCP tools (Context7, DeepWiki, Repomix, Tavily)
    └── After research, consider ingesting via hm-tech-stack-ingest for future use
```

### Validation Priority

When both cached assets and web documentation are available:

| Source | Priority | When to Trust |
|--------|----------|---------------|
| **Cached source code** (repomix raw/) | HIGHEST | For API signatures, type definitions, and implementation details |
| **Cached API docs** (context7 api/) | HIGH | For official API behavior and examples |
| **Cached structured docs** (deepwiki docs/) | MEDIUM | For architecture overview and module relationships |
| **Web search** (Tavily, Brave) | LOW | Only for current information, news, or community patterns |
| **Live Context7** | FALLBACK | When nothing is cached |

**Rule:** If cached source code exists for the exact version in use, validate every claimed API signature against the cached source. Do not trust web documentation without verification against cached code.

---

## The Six Concepts

Every research task touches at least two of these. Complex tasks touch all six.

### 1. Case Comparison — "This Case vs. That Case"

Research is comparative by nature. You are always deciding between approaches, tools, patterns, or solutions. The case comparison framework gives you a structure for side-by-side analysis.

**When to use it**: Every time you evaluate two or more options.

| Dimension | Case A | Case B |
|-----------|--------|--------|
| Approach | [what A does] | [what B does] |
| Depth needed | [shallow/medium/deep] | [shallow/medium/deep] |
| Risk of wrong answer | [low/medium/high] | [low/medium/high] |
| Time to validate | [hours/days] | [hours/days] |
| Reversibility | [easy/hard] | [easy/hard] |

**Example**: "Should we use Prisma or Drizzle for our ORM?"

| | Prisma | Drizzle |
|---|--------|---------|
| Approach | Schema-first, generated client | SQL-like, type-inferred |
| Depth needed | Medium (docs are thorough) | Deep (patterns are emergent) |
| Risk of wrong answer | Medium (lock-in) | Low (closer to SQL) |
| Time to validate | 2 days (migration tooling) | 1 day (simpler setup) |
| Reversibility | Hard (schema migration) | Easy (raw SQL fallback) |

Load [references/case-comparison.md](references/case-comparison.md) for 5 complete case pairs with decision frameworks.

---

### 2. Edge Cases — When Research Goes Wrong

Research fails in predictable ways. The top 6 failure modes:

| Failure | Signal | First Response |
|---------|--------|----------------|
| Contradictory sources | Two authoritative sources disagree | Check dates. Newer wins, but verify changelogs. |
| Outdated information | Last update > 12 months, API version mismatch | Search with freshness filter. Check GitHub releases. |
| Too new for patterns | < 6 months old, < 100 GitHub stars | Read source code directly. Build a prototype. |
| Vendor docs are wrong | Code doesn't match documented behavior | Create a minimal repro. File an issue. Use the code, not the docs. |
| No clear winner | 3+ valid approaches, zero differentiation | Define your constraints first. Pick the simplest that fits. |
| Scope creep | Research question keeps expanding | Write a one-sentence scope. Anything outside = separate investigation. |

Load [references/edge-cases.md](references/edge-cases.md) for each failure's full resolution workflow.

---

### 3. Requirements vs. Spec — When to Stop Researching

Research has a natural endpoint. Cross it and you are writing a specification, not doing research. The boundary looks like this:

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin