Imported from jgwill/Miadi (skills/deep-research-foundations/SKILL.md). Install upstream with npx skills add jgwill/Miadi --skill deep-research-foundations. Copyright stays with the author.

Deep Research Foundations

Use this skill when a repo needs a durable foundations/<topic>/ packet rather than a one-off research summary.

The skill preserves the useful deep-research orchestration pattern:

• date context
• MECE field decomposition
• source quality rules
• source ledger
• gap analysis
• synthesis

It removes person-specific residue and treats foundations work as a canonical Miadi / Mighty Eagle stewardship contract.

Stewardship Contract

Purpose

Create academically grounded, repo-local foundation packets that help a branch, skill, runtime, issue, or artifact stand on recognized fields, explicit provenance, and readable intent.

Stewardship Responsibilities

• Kherix owns academic rigor, source quality, citation discipline, and whether the packet is intellectually sound.
• MiaClaw owns structure, routing, packet shape, repo placement, crosswalks, and keeping the packet usable by engineering and stewardship workflows.
• AvaClaw is consulted when the packet needs relational framing, onboarding voice, narrative resonance, or human-facing transmission shaped with care.

Default Placement

Every repo owns its own local packet root:

foundations/<topic>/

Default rule:

• place the packet in the repo where the work will actually be consumed
• Mighty Eagle may maintain a higher-level registry or crosswalk across related repos
• QMD may index and federate packet content across repositories

Packet Shape

Recommended minimum structure:

foundations/<topic>/
  README.md
  source-ledger.yaml
  context-layer.md
  intent-understanding.md
  synthesis.md

For fielded packets, add one file or folder per field:

foundations/<topic>/
  README.md
  source-ledger.yaml
  context-layer.md
  intent-understanding.md
  synthesis.md
  <field-slug>.md

Explicit Layer Separation

1) Context-Layer

The context-layer captures the shared framing and durable metadata around the packet.

Include:

• shared language and canonical terms
• field list and MECE decomposition
• provenance notes
• source quality rules
• source ledger conventions
• repo placement
• QMD indexing / federation / crosswalk notes
• related issues, packets, specs, or PDE artifacts

Questions this layer answers:

• what language are we using?
• what fields are in scope?
• where does this packet live?
• how will provenance and indexing be maintained?

2) Intent-Understanding

The intent-understanding layer captures why the packet exists and what structural tension it resolves.

Include:

• why this branch, skill, issue, or artifact exists
• intended audience(s)
• desired outcome
• current reality
• structural tension being resolved
• decisions this packet is expected to support
• what success would make easier downstream

Questions this layer answers:

• why are we doing this now?
• who is this for?
• what decision or artifact must this packet strengthen?
• what tension does this packet help resolve?

Research Diamond

         [Broad: decompose question]
              /        \
    [Narrow: 3-6 parallel field agents]    ← Wave 1
              \        /
         [Evaluate: gaps, cautions]
              /        \
    [Deep: 1-2 targeted agents]            ← Wave 2 if needed
              \        /
         [Synthesize: foundations packet]

Start broad, go narrow in parallel, identify gaps, go deep on gaps, synthesize.

Workflow

Phase 0 — Establish Date Context

Record today’s date and include it in prompts, packet metadata, and the source ledger.

Phase 1 — Gather Local Context

Before external research:

• read local repo guidance (AGENTS.md, README.md, specs, skill docs, issue notes)
• inspect existing foundations/ content if present
• identify whether this packet is local-only, cross-repo, or registry-worthy
• note adjacent artifacts that the packet must support

Phase 2 — MECE Field Decomposition

Break the topic into mutually exclusive, collectively exhaustive fields.

Common field families:

• human-computer interaction
• software architecture / traceability
• knowledge organization
• governance / provenance
• narrative studies / meaning-making
• domain-specific academic fields implied by the topic

Scale effort to complexity:

• narrow factual check: 1-2 fields
• normal foundations packet: 3-4 fields
• complex cross-repo lineage: 4-6 fields plus critique pass

Phase 3 — Parallel Research

Each research lane should include:

1. Date context
2. Why the packet matters
3. Specific field angle and boundaries
4. Source strategy
5. Source quality bar
6. Expected output shape

Prompt skeleton:

You are researching [FIELD / ANGLE] for a repository-local foundations packet.
TODAY'S DATE: [date]
PURPOSE: [why this packet matters]
AUDIENCE: [who will use it]
ANGLE: [field scope]
BOUNDARIES: [what this lane does not cover]
SOURCE QUALITY: Prefer academic papers, standards, official docs, primary sources, and strong practitioner engineering writing.
OUTPUT: canonical concepts, key findings, cautions, engineering implications, provenance notes, and sources with URLs/DOIs.

Phase 4 — Gap Analysis

After all lanes return:

• check whether each field is adequately sourced
• identify contradictions
• identify unsupported claims
• identify missing fields or weak evidence
• run targeted follow-up research where risk is high

Phase 5 — Synthesis

The final packet should synthesize, not concatenate.

Recommended outputs:

• context-layer.md
• intent-understanding.md
• synthesis.md
• field files as needed
• source-ledger.yaml

source-ledger.yaml should include at minimum:

meta:
  packet: <topic-slug>
  generated: <date>
  method: deep-research-foundations
  verification_status: live-web-verified | training-knowledge-only | mixed
sources:
  - id: <short-id>
    field: <field>
    title: <title>
    url: <url>
    doi: <doi-if-any>
    supports: <claim-or-decision>
    verified: true|false

Phase 6 — Placement, Crosswalk, and Verification

Before calling the packet done:

• confirm it lives under the correct repo-local foundations/<topic>/
• add crosswalk notes if Mighty Eagle should reference it from a registry
• note whether QMD indexing/federation should be updated
• verify source-ledger integrity and representative claims
• preserve unrelated worktree state

Quality Gate

Do not call the packet complete unless:

• recognized fields are named
• context-layer and intent-understanding are clearly separated
• sources are cited with URLs and/or DOIs where available
• source quality is legible
• provenance is explicit
• engineering implications are actionable
• synthesis is readable and bounded
• repo placement is correct
• unrelated dirty state is untouched

Common Pitfalls

• creating a generic report instead of a repo-local foundations packet
• mixing provenance metadata with intent analysis until neither is clear
• failing to state audience or desired outcome
• flattening cross-repo stewardship into one repo without a crosswalk note
• keeping branch-specific or person-specific residue in a supposedly canonical skill
• staging unrelated repo changes while committing skill work