---
type: skill
lifecycle: stable
inheritance: inheritable
name: "research-first-development"
description: Build knowledge bases that build software — research before code, teach before execute
tier: extended
applyTo: '**/*research*,**/*first*,**/*development*'
currency: 2026-04-22
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
![the AI assistant Research Assistance — Approved Research](RELATIVE_PATH/assets/banner-research-assistance.svg)
```

### 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.

---