hm-l3-synthesis

Files (16)

• SKILL.md
• .gitkeep · evals/
• evals.json · evals/
• .gitkeep · metrics/
• rich-gate-scorecard.md · metrics/
• artifact-export.md · references/
• compression-tiers.md · references/
• corpus-gate.md · references/
• cross-dep-analysis.md · references/
• interface-extraction.md · references/
• pattern-classifier.md · references/
• validated-playbooks.md · references/
• .gitkeep · scripts/
• validate-rich-package.sh · scripts/
• .gitkeep · templates/
• contradiction-consensus.md · templates/

SKILL.md (first lines)

## Overview

Compress research findings into actionable artifacts with tiered reduction. Use when packing codebases, extracting interfaces, producing validated reports, or classifying patterns. Produces compressed outputs at three reduction tiers with cross-dependency analysis.

## Quick Jump

| Task | Section | Detail |
|------|---------|--------|
| "Compress this repo" | Compression Tiers | [Three Compression Tiers](#three-compression-tiers) |
| "What depends on what?" | Cross-Dep Analysis | [references/cross-dep-analysis.md](references/cross-dep-analysis.md) |
| "Extract the API surface" | Interface Extraction | [references/interface-extraction.md](references/interface-extraction.md) |
| "What patterns does this use?" | Pattern Classification | [references/pattern-classifier.md](references/pattern-classifier.md) |
| "Is my corpus big enough?" | Corpus Gate | [references/corpus-gate.md](references/corpus-gate.md) |
| "Export findings that last" | Artifact Export | [references/artifact-export.md](references/artifact-export.md) |
| "Sources disagree" | Contradiction + Consensus | [templates/contradiction-consensus.md](templates/contradiction-consensus.md) |

<execution_context>
For reading modes during analysis: 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 for validation): load skill "hm-tech-stack-ingest"
Use cached API signatures to validate against REAL code before generating artifacts or quality gates.

For research findings to synthesize: load skill "hm-deep-research"
hm-synthesis consumes structured research outputs with citations and evidence levels.

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

---

## Three Compression Tiers

Every packing operation selects one tier. Default: Focused.

### Evidence-Backed Synthesis Gate

Before producing a final report, plan, or reusable artifact:

1. Group findings into themes only after each theme has cited evidence.
2. Fill `templates/contradiction-consensus.md` for conflicts, weak consensus, or unresolved claims.
3. Add a methodology/limitations section when sources are partial, stale, vendor-biased, or inaccessible.
4. Separate recommendations from facts; recommendations need rationale and alternatives.
5. Export provenance: source list, reviewed materials, unresolved gaps, and continuation path.

**BLOCKED rule:** If a high-impact contradiction remains unresolved, the artifact may recommend investigation, but it must not claim a settled answer.

| Tier | Reduction | Content | When |
|------|-----------|---------|------|
| **Snapshot** | 0% | Full source, every line, every comment | Final audit, security review, legal compliance |
| **Focused** | ~50% | Tree-sitter signatures + key implementations (public exports, error paths, config) | Dependency analysis, code review prep, onboarding |
| **Signature** | ~70% | Types, interfaces, exports, module boundaries only | Architecture planning, API contract extraction, budget-constrained context |

### Decision Table

```
What do you need?
|
+-- "Every line matters" (audit, security, legal)
|   -> SNAPSHOT: repomix_pack_codebase(compress=false)
|
+-- "How does this work?" (review, onboarding, deps)
|   -> FOCUSED: repomix_pack_codebase(compress=true) + grep for key implementations
|
+-- "What's the shape?" (architecture, contracts, planning)
|   -> SIGNATURE: extract types/interfaces only (see interface-extraction.md)
|
+-- "I'm not sure yet"
|   -> FOCUSED: safest default, readable at half the cost
```

### Tier Comparison

| Property | Snapshot | Focused | Signature |
|----------|----------|---------|-----------|
| Full source | Yes | Signatures + selective body | Types only |
| Comments | Yes | Stripped | Stripped |
| Private members | Yes | No | No |
| Error handling paths | Yes | Yes | Signatures only |
| Import graph | Reconstruct | Reconstruct | Explicit |
| Avg tokens (1000 LOC) | ~8000 | ~4000 | ~2400 |

See [references/compression-tiers.md](references/compression-tiers.md) for per-language settings, repomix configuration, and worked examples.

---

## Cross-Dependency Analysis Protocol

5-step protocol. Run sequentially. No shortcuts.

```
MAP → CLASSIFY → DETECT → RESOLVE → VALIDATE
```

### MAP — List Every Dependency

```bash
grep -rn "import.*from\|require(" src/ --include="*.ts" > /tmp/deps-raw.txt
grep -rn "emit\|on(" src/ --include="*.ts" >> /tmp/deps-raw.txt
```

Output: raw import/require/event list with file:line pairs.

### CLASSIFY — Tag Each Dependency

| Category | Pattern | Example |
|----------|---------|---------|
| **internal** | Same package, `./` or `../` imports | `import { foo } from "./helpers"` |
| **external** | node_modules, npm packages | `import { z } from "zod"` |
| **peer** | Required but not bundled | e.g., `react` for a React plugin, `express` for middleware |
| **dev** | Build/test only | `vitest`, `typescript` |

### DETECT — Find Problems

| Problem | Detection |
|---------|-----------|
| Version conflict | Same package at different versions in dependency tree |
| Circular dependency | File A imports B, B imports A (direct or transitive) |

From shynlee04/hivemind-plugin, MIT.

More from shynlee04/hivemind-plugin