Instruction file imported from fabioc-aloha/alex-cognitive-architecture (.github/instructions/heir-project-improvement.instructions.md). Copyright stays with the author.

Heir Project Improvement

How heirs build trifectas for their own projects and apply research-first development to raise quality

Related: trifecta-audit (defines the model), research-first-workflow (provides methodology), heir-skill-promotion (discoveries may promote), research-first-development skill (4D gap analysis patterns)

Quick Reference

Part 1: Creating Heir Trifectas

What is a Trifecta?

A capability encoded in all three memory systems:

Not everything needs a trifecta. Most skills work fine alone. A trifecta is for capabilities that are central to this project's daily work.

Scripts are muscles, not memories. Scripts (.ps1, .js, .ts) are execution artifacts that perform physical work — they are NOT a fourth memory system. Trifecta files reference scripts ("run build.ps1 after step 3"), but scripts are never a trifecta component.

Step 1: Identify Your Core Capabilities

List the 3-5 capabilities most central to your project's daily work:

## Project Core Capabilities

1. [Capability A] — used daily, complex workflow
2. [Capability B] — platform-specific, deep domain
3. [Capability C] — user invokes by name regularly
4. [Capability D] — critical but currently under-documented

Discovery questions:

• What does this project do every day?
• What workflows have the most steps?
• What domain knowledge is hardest to re-explain each session?
• What would a new Alex session struggle with most?

Step 2: Run the Heir Why Test

For each candidate, answer four questions:

Classification:

┌─ [capability-name]
│  Q1 (Frequency):     [daily / weekly / monthly / rare]
│  Q2 (Domain depth):  [deep / moderate / shallow]
│  Q3 (User-invoked):  [yes / no]
│  Q4 (Complexity):    [6+ steps / 3-5 / 1-2]
└─ Classification: TRIFECTA | INSTRUCTION+SKILL | SKILL-ONLY

Decision matrix:

Step 3: Create Missing Components

For each trifecta candidate, create the missing files:

Creating an Heir Instruction

<!-- .github/instructions/{capability}.instructions.md -->

```instructions
---
description: "{One-line description of the procedure}"
applyTo: "**/*relevant-pattern*"
---

# {Capability Name}

> {Purpose statement}

**Related**: Link to the corresponding skill that provides domain patterns

---

## When to Run

| Trigger | Scope |
|---------|-------|
| {trigger-1} | {what it does} |
| {trigger-2} | {what it does} |

---

## Procedure

### Step 1: {First step}
{Detailed instructions}

### Step 2: {Second step}
{Detailed instructions}

### Step 3: {Third step}
{Detailed instructions}

---

## Troubleshooting

| Issue | Fix |
|-------|-----|
| {common-problem-1} | {solution} |
| {common-problem-2} | {solution} |
```

#### Creating an Heir Prompt

```markdown
<!-- .github/prompts/{capability}.prompt.md -->
---
description: "{Interactive workflow description}"
agent: "Alex"
---

# /command — {Capability Name}

Guide me through {what this prompt does}.

## Context
- Read `.github/skills/{capability}/SKILL.md` for domain patterns
- Follow `.github/instructions/{capability}.instructions.md` for procedure

## Workflow
1. **Assess**: {What to evaluate first}
2. **Plan**: {How to decide the approach}
3. **Execute**: {What to build/do}
4. **Validate**: {How to verify quality}

## Output
{What the user should have at the end}

Naming Conventions for Discoverability

Every trifecta component must share a common name prefix for Copilot semantic search:

Use identical base names (e.g., code-review) across all three files so Copilot's semantic search can correlate them.

Part 2: Research-First Development

When to Use

• Starting a new project phase
• Onboarding to an unfamiliar domain
• When AI output quality is inconsistent (symptom: insufficient context)
• Before any complex multi-subsystem implementation

The Flow

Research → Teach → Plan → Execute

Traditional: Requirements → Design → Code → Test (AI guesses at patterns)
Research-first: Research → Encode knowledge → Gap analysis → Code (AI follows documented patterns)

Step 1: Research Sprint

Before writing any code, create research documents:

Quality gate: Each research doc has code examples, decision rationale, and cited sources.

Step 2: Encode Knowledge

Transform research into loadable knowledge:

Minimum encoding:

• 1-3 skills per research document
• 1 context instruction (the project hub: {project}-context.instructions.md)
• 1 workflow instruction (coding conventions: {project}-development-workflow.instructions.md)
• 2 agents minimum: Builder + Validator (the Two-Agent Pattern)

Step 3: Run 4-Dimension Gap Analysis

Before each implementation phase, audit knowledge coverage across all four dimensions:

For each dimension: List what you're building → check coverage → score percentage → fill gaps.

Decision gate:

• All 4 ≥ 75%: Proceed to coding
• Any < 75%: Fill gaps first
• Any < 50%: Research sprint needed

Use the /gapanalysis prompt for interactive guidance.

Step 4: Execute with Full Context

With knowledge encoded:

• No re-explanation between sessions (skills auto-load)
• No hallucinated patterns (documented patterns available)
• No inconsistent quality (every subsystem has a skill)

Process Templates

Quick Start (Small Phase)

## Pre-Phase Checklist

- [ ] Research: 1-2 docs on new domains
- [ ] Skills: 1 skill per new subsystem
- [ ] Instructions: Dev workflow instruction exists
- [ ] Agents: Builder + Validator created
- [ ] Prompts: /implement prompt exists
- [ ] Gap analysis: Quick 4D scan (all ≥ 75%)

Full Process (Major Phase)

## Pre-Phase Checklist

- [ ] Research: 3-5 deep docs, ADRs for major decisions
- [ ] Skills: 1-3 skills per research doc (5-10 total)
- [ ] Instructions: Context hub + workflow + deployment + testing
- [ ] Agents: Builder + Validator + domain specialists
- [ ] Prompts: /implement, /test, /deploy, /redteam
- [ ] Gap analysis: Full 4D protocol (all ≥ 75%)
- [ ] Architecture: All files have complete frontmatter (applyTo, description)
- [ ] Validation: brain-qa passes with 0 critical issues

Part 3: Combining Both — The Improvement Workflow

Research-first and trifecta creation work together:

1. Run /improve prompt
2. Identify core capabilities → trifecta candidates
3. For each candidate:
   a. Research the domain (if gaps exist)
   b. Encode as skill (domain patterns)
   c. Encode as instruction (procedural steps)
   d. Encode as prompt (interactive workflow)
   e. Use consistent naming across all three
4. Run /gapanalysis for full 4D coverage audit
5. Fill remaining gaps
6. Validate with Dream

Anti-Patterns

Mission-Critical Projects (NASA Standards)

For safety-critical, mission-critical, or high-reliability heir projects, adopt NASA/JPL Power of 10 standards:

## Pre-Phase Checklist (Mission-Critical)

- [ ] All recursive functions have `maxDepth` parameter
- [ ] All `while` loops have `MAX_ITERATIONS` counter
- [ ] All arrays/maps have maximum size limits
- [ ] No function exceeds 60 lines
- [ ] Critical paths have ≥2 assertions
- [ ] Maximum 4 levels of nesting
- [ ] Optional chaining on all object access
- [ ] Compiler warnings = 0

When to apply: User mentions "mission-critical", "safety-critical", "NASA standards", "high reliability", or the heir manages critical infrastructure (medical, aerospace, financial, infrastructure).

When Improvements Should Promote to Master

Activation Triggers

Instruction created: 2026-02-13 | Purpose: Teach heirs to build trifectas and apply research-first development