research-first-development

type	skill
lifecycle	stable
inheritance	inheritable
name	research-first-development
description	Build knowledge bases that build software — research before code, teach before execute
tier	standard
applyTo	**/*research*,**/*knowledge*,**/*learning*
currency	"2026-04-22T00:00:00.000Z"

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)

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

Code	Dimension	Question	Covers
GA-S	Skills	"Does Alex know the patterns?"	Domain knowledge, reusable techniques
GA-I	Instructions	"Does Alex know the procedures?"	Project-specific workflows, step-by-step
GA-A	Agents	"Does Alex have the right roles?"	Builder, Validator, Specialists
GA-P	Prompts	"Does Alex 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.

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

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

Document location	Path to use
Repo root (*.md)	assets/banner-research-assistance.svg
master-wiki/research/*.md	../assets/banner-research-assistance.svg
master-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:

.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

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

---