Research First Development

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 Alex
• Entering a new implementation phase of an existing project
• Onboarding Alex 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)

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)

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"
Alex: [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

Protocol (Per Dimension)

Step 1: Inventory What You're Building

List all subsystems, features, and integrations for this phase.

## Phase N: Implementation Scope
- [ ] Subsystem A: {description}
- [ ] Subsystem B: {description}
- [ ] Integration: {description}

Step 2: Inventory Existing Knowledge

Catalogue current knowledge across all four dimensions:

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

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:

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:

Prompt categories to check:

The Two-Agent Pattern

For any non-trivial project, create at least two agents with distinct mental models:

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

Validator Agent Commands (Template)

Connection Hygiene (During Development)

Connections wired at creation time are 10x more valuable than connections discovered during maintenance. Practice "clean as you go":

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

Approved Research Stamp

Research artifacts produced under this skill carry the Alex 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:

![Alex Research Assistance — Approved Research](RELATIVE_PATH/assets/banner-research-assistance.svg)

Path resolution

Source asset

The canonical SVG ships with this skill at:

.github/skills/research-first-development/assets/banner-research-assistance.svg

The repo also keeps published copies at assets/banner-research-assistance.svg and master-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

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

Relationship to Existing Protocols

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

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 Master Alex 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.