research-first-development · git:20260728.80a7ab6 · 2026-07-28 · sha256 3b1a1f4b74bbd004
research-first-development git:20260728.80a7ab6A
Immutable. This exact content is served forever at /api/v1/blob/3b1a1f4b74bbd004.
---
name: research-first-development
description: "Build knowledge bases that build software — research before code, teach before execute"
lastReviewed: 2026-04-30
---
# Research-First Development
> Build knowledge bases that build software — research before code, teach before execute
Methodology for AI-assisted development where investment in research, skill creation, and knowledge encoding **precedes** implementation. Discovered through the Dead Letter heir's masterclass on cognitive architecture utilization (February 2026).
---
## When to Use
- Starting any new project with the AI assistant
- Entering a new implementation phase of an existing project
- Onboarding the AI assistant to an unfamiliar domain
- When AI output quality is inconsistent (symptom: insufficient context)
- Before any complex multi-subsystem implementation
---
## Core Insight
Traditional software development: **Requirements → Design → Code → Test**
AI-assisted development with cognitive architecture: **Research → Teach → Plan → Execute**
> **The quality of AI output is directly proportional to the quality of knowledge in its context.**
Instead of the human writing code with AI assistance, **the human orchestrates intent while AI handles execution**. But AI can only execute what it understands. Therefore: invest in teaching before asking for output.
---
## The Research-First Paradigm
### Phase 0: Research Sprint (Before Any Code)
| Step | Activity | Output |
|------|----------|--------|
| 1 | **Competitive landscape analysis** | Understanding of prior art |
| 2 | **Technical feasibility research** | Deep research documents (3-5 minimum) |
| 3 | **Architecture decision records** | ADRs documenting key choices |
| 4 | **Core domain research** | Comprehensive domain knowledge |
| 5 | **Branding/identity decisions** | Project character and voice |
Each research document should:
- Explore one domain **exhaustively**
- Cite sources: academic papers, industry best practices, competitive analysis
- Be structured with clear sections, code examples, decision rationales
- Live in a `/docs/` or `/research/` directory
### Phase 1: Knowledge Encoding (Research → Skills)
| Step | Activity | Output |
|------|----------|--------|
| 1 | **Skill extraction** | 1-3 skills per research document |
| 2 | **Context instruction** | Central hub: `{project}-context.instructions.md` |
| 3 | **Workflow instruction** | Dev process: `{project}-development-workflow.instructions.md` |
| 4 | **Agent creation** | Builder + Validator agents |
| 5 | **Connection wiring** | 2-4 links per new file |
**Key distinction**:
- **Skills** encode *patterns and principles* — reusable, domain knowledge ("how does X work?")
- **Instructions** encode *procedures* — project-specific workflows ("how do I do X here?")
### Phase 2: Plan → Execute (Now You Code)
With sufficient knowledge encoded, implementation becomes **conversational**:
```
Human: "Implement the EventBus from the game engine spec"
the AI assistant: [Loads skill, reads patterns, implements with full context]
```
No re-explanation. No context loss. No hallucinated patterns.
---
## The 4-Dimension Gap Analysis
**When**: Before each major implementation phase.
**Purpose**: Ensure knowledge coverage across all four knowledge types before coding begins.
**Cadence**: Every phase boundary, every major milestone.
**Interactive**: Run `/gapanalysis` prompt for guided execution.
### The Four Dimensions
| Code | Dimension | Question | Covers |
|------|-----------|----------|--------|
| **GA-S** | Skills | "Does the AI assistant know the *patterns*?" | Domain knowledge, reusable techniques |
| **GA-I** | Instructions | "Does the AI assistant know the *procedures*?" | Project-specific workflows, step-by-step |
| **GA-A** | Agents | "Does the AI assistant have the right *roles*?" | Builder, Validator, Specialists |
| **GA-P** | Prompts | "Does the AI assistant have the right *interactive workflows*?" | Guided commands, repeatable rituals |
### Protocol (Per Dimension)
#### Step 1: Inventory What You're Building
List all subsystems, features, and integrations for this phase.
```markdown
## Phase N: Implementation Scope
- [ ] Subsystem A: {description}
- [ ] Subsystem B: {description}
- [ ] Integration: {description}
```
#### Step 2: Inventory Existing Knowledge
Catalogue current knowledge across all four dimensions:
```markdown
## Current Knowledge Inventory
| Dimension | Count | Relevant to Phase N |
|-----------|-------|---------------------|
| Skills (GA-S) | {N} | {list relevant} |
| Instructions (GA-I) | {N} | {list relevant} |
| Agents (GA-A) | {N} | {list relevant} |
| Prompts (GA-P) | {N} | {list relevant} |
```
#### Step 3: Map Capabilities to Needs (Per Dimension)
**GA-S (Skills)**: For each subsystem — "If I ask 'how does {X} work?', is there a skill?"
**GA-I (Instructions)**: For each workflow — "If I ask 'how do I do {X} here?', is there an instruction?"
**GA-A (Agents)**: For each role — "Is there an agent with this mental model and skill set?"
**GA-P (Prompts)**: For each interactive workflow — "Is there a guided `/command` for this?"
#### Step 4: Score Coverage
| Dimension | Coverage % | Items Needed |
|-----------|-----------|--------------|
| GA-S: Skills | {%} | {missing patterns} |
| GA-I: Instructions | {%} | {missing procedures} |
| GA-A: Agents | {%} | {missing roles} |
| GA-P: Prompts | {%} | {missing workflows} |
**Decision gate:**
- All 4 ≥ 75%: **Proceed to coding**
- Any < 75%: **Fill gaps first**
- Any < 50%: **Research sprint needed**
#### Step 5: Fill Gaps Before Coding
Create missing skills, instructions, agents, and prompts. Wire connections. **Then** begin implementation.
### GA-A Deep Dive: Agent Gap Analysis
Agents encode **cognitive roles** — distinct mental models with curated skill sets:
| Question | What It Detects |
|----------|----------------|
| "Is there a builder?" | Missing constructive thinker |
| "Is there a validator?" | Missing adversarial thinker |
| "Do agents hand off at domain boundaries?" | Missing specialization |
| "Does each agent load role-appropriate skills?" | Skill misconfiguration |
| "Are there domain-specific specialists?" | Missing for security, data, infrastructure |
**Minimum viable agent set**: Builder + Validator (the Two-Agent Pattern).
### GA-P Deep Dive: Prompt Gap Analysis
Prompts encode **interactive workflows** — guided sequences for repeatable tasks:
| Question | What It Detects |
|----------|----------------|
| "What do developers do repeatedly?" | Missing implementation prompts |
| "What workflows need specific sequencing?" | Missing structured prompts |
| "What tasks benefit from guided the AI assistant interaction?" | Missing mentoring prompts |
| "Are there review/audit rituals?" | Missing quality prompts |
**Prompt categories to check:**
| Category | Prompt Pattern | Example |
|----------|---------------|---------|
| Implementation | `/{project}-implement` | Guided feature development |
| Testing | `/{project}-test` or `/redteam` | Interactive test authoring |
| Deployment | `/{project}-deploy` | Deployment checklist |
| Review | `/review` or `/{project}-audit` | Quality review workflow |
| Learning | `/learn` | Domain learning session |
---
## The Two-Agent Pattern
For any non-trivial project, create at least two agents with **distinct mental models**:
| Agent Type | Focus | Mental Model | Question |
|------------|-------|--------------|----------|
| **Builder** | Feature implementation | Constructive | "How do I create this?" |
| **Validator** | Quality assurance | Adversarial | "How do I break this?" |
### Why Separate Agents?
Adversarial thinking requires a **different context** than constructive thinking. Separating agents allows each to:
- Optimize for its role's vocabulary and patterns
- Load only relevant skills (builder loads implementation skills; validator loads testing/security skills)
- Hand off cleanly at domain boundaries
### Naming Convention
| Agent | File | Trigger |
|-------|------|---------|
| Builder | `{project}-dev.agent.md` | Implementation tasks |
| Validator | `{project}-qa.agent.md` | Testing, review, audit tasks |
### Validator Agent Commands (Template)
| Command | Purpose |
|---------|---------|
| `/redteam` | Adversarial testing sweep |
| `/audit` | Compliance / quality audit |
| `/stress-test` | Performance and reliability |
| `/consistency` | Cross-system consistency check |
---
## Connection Hygiene (During Development)
Connections wired **at creation time** are 10x more valuable than connections discovered during maintenance. Practice "clean as you go":
| Practice | Why | How |
|----------|-----|-----|
| Wire at creation | Fresh knowledge = accurate links | Add `applyTo` patterns when creating any skill/instruction |
| 2-4 connections minimum | Prevents isolated knowledge islands | Every new file connects to at least 2 existing files |
| Star topology for instructions | Central activation hub | Every instruction connects to the project context instruction |
| Run Dream before major phases | Catch broken connections early | Use the dream prompt or `node .github/muscles/brain-qa.cjs` |
| Strength reflects reality | Don't over-connect | Critical = always co-activate; Low = rarely |
### Connection Strategy
> Connection patterns use frontmatter `applyTo` globs to link files. Use specific globs over generic patterns.
```
project-context.instructions.md (hub)
├── skill-a (Critical, Enables)
├── skill-b (Critical, Enables)
├── instruction-1 (High, Enables)
├── instruction-2 (High, Enables)
└── agent (High, Implements)
```
---
## Process Outcomes
| Outcome | Without Research-First | With Research-First |
|---------|----------------------|---------------------|
| Implementation quality | AI guesses at patterns | AI follows documented patterns |
| Style consistency | Varies per prompt | Single source of truth |
| Context between sessions | Lost, must re-explain | Persists in files, auto-loaded |
| Domain onboarding | Each prompt re-teaches | Knowledge loaded automatically |
| Debugging | Must re-teach context | References authoritative docs |
| Quality testing | Ad-hoc, incomplete | Encoded knowledge + QA agent |
---
## Approved Research Stamp
Research artifacts produced under this skill carry the **the AI assistant Approved Research** banner at the top of the file. The stamp is the visible certification that the seven critical-thinking disciplines were applied to the document's claims.
### Required header line
The first line of the file, before the `# Title`:
```markdown
```
### Path resolution
| Document location | Path to use |
|---|---|
| Repo root (`*.md`) | `assets/banner-research-assistance.svg` |
| `wiki/research/*.md` | `../assets/banner-research-assistance.svg` |
| `wiki/*.md` (root wiki) | `./assets/banner-research-assistance.svg` |
| Heir `docs/` or `research/` | `../assets/banner-research-assistance.svg` (after copying the SVG into the heir's `assets/`) |
### Source asset
The canonical SVG ships with this skill at:
```text
.github/skills/research-first-development/assets/banner-research-assistance.svg
```
The repo also keeps published copies at `assets/banner-research-assistance.svg` and `wiki/assets/banner-research-assistance.svg`. When stamping research in a new location, copy the SVG from the skill folder into the project's `assets/` directory and reference it from there.
### Quality bar (do not stamp unless this is true)
The stamp implies:
- Multiple sources consulted, with citations
- Alternatives or competing interpretations considered
- Evidence quality assessed (primary > peer-reviewed > practitioner > AI training data)
- Residual gaps and open questions named explicitly
- The seven critical-thinking disciplines applied at the depth the topic warrants
If the document does not meet that bar, **do not apply the stamp** — fix the document first. The stamp is a quality signal, not decoration.
### When to apply
- **Apply** to: literature surveys, comparison studies, gap analyses, architecture investigations, empirical findings, domain research documents living in `research/` or `docs/`.
- **Do not apply** to: PLAN.md, ROADMAP.md, READMEs, implementation logs, status reports, or meeting notes. Those have their own banner conventions.
---
## Replication Checklist
To apply Research-First Development to any new project:
- [ ] **Research phase**: Create 3-5 deep research documents before coding
- [ ] **Context instruction**: Create `{project}-context.instructions.md` as the hub
- [ ] **Workflow instruction**: Create `{project}-development-workflow.instructions.md`
- [ ] **Core skills**: Extract 5-10 skills from research docs
- [ ] **Builder agent**: Create `{project}-dev.agent.md` for implementation
- [ ] **Validator agent**: Create `{project}-qa.agent.md` for testing
- [ ] **Interactive prompts**: Create `{project}-implement`, `{project}-test`, `{project}-deploy` prompts
- [ ] **Connection network**: Wire all new files with 2-4 connections each
- [ ] **4D gap analysis**: Run GA-S, GA-I, GA-A, GA-P before each phase
- [ ] **Dream validation**: Use the dream prompt or run `node .github/muscles/brain-qa.cjs` to validate network health
---
## Heir Generalization
This skill is `inheritable` — every heir gets the full methodology.
### What Heirs Inherit
| Component | Heir Gets | Heir Customizes |
|-----------|-----------|-----------------|
| Research-first paradigm | Full methodology | Domain-specific research topics |
| 4-dimension gap analysis | GA-S, GA-I, GA-A, GA-P templates | Project-specific subsystem lists |
| Two-agent pattern | Builder + Validator template | Agent names, skills, commands |
| Connection hygiene | Wiring discipline | Project-specific connections |
| `/gapanalysis` prompt | Interactive workflow | — (universal) |
### Heir Adaptation Flow
```
Master provides: methodology + templates + quality gates
Heir adapts: project-specific skills, instructions, agents, prompts
Heir validates: run gap analysis with project scope
Master absorbs: generalizable patterns promoted back via heir-skill-promotion
```
### What Flows Back to Master
When heir knowledge is cross-project applicable:
1. **Patterns** → new Master skills or GK patterns
2. **Processes** → refined Master instructions
3. **Agent templates** → new agent patterns in Master
4. **Prompt workflows** → new prompts in Master
---
## Anti-Patterns
| Anti-Pattern | Why It Fails | Do Instead |
|-------------|-------------|------------|
| "Just start coding" | AI has no context, hallucinates patterns | Research → Teach → Plan → Execute |
| Skipping gap analysis | Discover missing knowledge mid-implementation | Run 4D protocol (GA-S/I/A/P) at every phase boundary |
| One mega-agent | Conflates builder/validator mental models | Separate agents with distinct roles |
| Orphan skills | Knowledge islands that never activate | Wire 2-4 connections at creation time |
| Research without encoding | Raw documents aren't loadable context | Extract skills from every research doc |
| Theory-only skills | Untested patterns break under pressure | Validate with real implementation, then encode |
| Skills-only gap analysis | Misses procedures, roles, and workflows | Always run all 4 dimensions |
| No prompts for repeatable work | Developers re-invent workflows each time | Create guided prompts for repeated tasks |
---
## Relationship to Existing Protocols
| Protocol | Phase | Relationship |
|----------|-------|-------------|
| **Bootstrap Learning** | Research | Research-first uses bootstrap learning for domains the AI assistant doesn't know |
| **Skill Selection Optimization** | Plan | SSO selects from skills that research-first created |
| **Project Scaffolding** | Execute | Scaffolding creates files; research-first creates *knowledge* first |
| **Skill Building** | Encode | Skill-building quality gates apply to research-extracted skills |
| **Dream Protocol** | Validate | Dream validates the connection network research-first wired |
| **Heir Skill Promotion** | Promote | Heir knowledge flows back to Master via promotion protocol |
| **Research-First Workflow** | Procedure | Instruction file provides step-by-step procedures for this skill |
---
## Troubleshooting
### AI output is inconsistent quality
**Problem**: Some responses are excellent, others miss the mark.
**Solution**: Run gap analysis. Inconsistency = knowledge coverage gaps. The subsystems with good output have skills; those without are getting guessed at.
**Why**: AI quality is proportional to context quality. No skill loaded = no patterns to follow.
### "I don't have time for research"
**Problem**: Feels slow to research before coding.
**Solution**: Research pays compound dividends. 2 days of research saves 2 weeks of debugging. The heir proved this: 18 skills + 9 instructions created before Phase 0 implementation began.
**Why**: You're not just building software — you're building a **knowledge base that builds software**.
### Gap analysis feels bureaucratic
**Problem**: 4 dimensions feels like overhead.
**Solution**: The ritual takes 15-30 minutes. It prevents days or weeks of rework. Scale it: small phases need a quick scan; major phases need the full 4D protocol. Use `/gapanalysis` prompt for guided execution.
**Why**: Discovering missing knowledge mid-implementation forces context-switching and rework.
---
## Activation Patterns
| Trigger | Response |
|---------|----------|
| "new project" | Full research-first workflow |
| "gap analysis" / "GA" | 4-dimension gap analysis (GA-S, GA-I, GA-A, GA-P) |
| "GA-S" / "skill gap" | Skills dimension only |
| "GA-I" / "instruction gap" | Instructions dimension only |
| "GA-A" / "agent gap" | Agents dimension only |
| "GA-P" / "prompt gap" | Prompts dimension only |
| "research first" | Core methodology explanation |
| "two-agent pattern" | Builder + Validator agent setup |
| "connection hygiene" | Connection best practices |
| "before coding" | Pre-implementation checklist |
| "knowledge encoding" | Research → Skill extraction workflow |
---
## Origin
Discovered by the Dead Letter heir (AI mystery game project, February 2026). The heir independently created 18 project-specific skills, 9 instructions, 2 agents, and 251 connections **before writing any implementation code** — proving that research-first investment in the cognitive architecture produces dramatically higher-quality AI-assisted development.
The 4-dimension gap analysis (GA-S, GA-I, GA-A, GA-P) was developed by your AI assistant to generalize the heir's methodology into a repeatable protocol for all projects and heirs.
The meta-insight: **You're not just building software — you're building a knowledge base that builds software.** The investment in research and skill creation pays compound dividends as the project grows.
---