| name | deep-research-foundations |
| description | Canonical Miadi / Mighty Eagle stewardship contract for creating and maintaining repository-local `foundations/<topic>/` packets with academic grounding, provenance discipline, source ledgers, gap analysis, and synthesis that can travel across Mighty Eagle, Gaia, IronSilk, and related repos.
|
| version | 0.2.0 |
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:
- Date context
- Why the packet matters
- Specific field angle and boundaries
- Source strategy
- Source quality bar
- 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.mdintent-understanding.mdsynthesis.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
