How gstack Implements the Search Before Building Principle

gstack operationalizes Search Before Building by auto-injecting a markdown preamble section—derived from ETHOS.md—into every high-tier skill, enforcing a three-layer knowledge hierarchy and mandatory Eureka moment logging before any code generation occurs.

The gstack repository treats "Search Before Building" (SBB) as a first-class architectural constraint rather than a loose guideline. By encoding the principle directly into skill preambles through a typed resolver pipeline, the system ensures AI agents search existing knowledge layers before writing unfamiliar code.

The Canonical Definition in ETHOS.md

The single source of truth for the Search Before Building philosophy lives in [ETHOS.md](https://github.com/garrytan/gstack/blob/main/ETHOS.md). This file defines the three knowledge layers that agents must evaluate:

• Layer 1 — Tried and true solutions that should not be reinvented
• Layer 2 — New and popular approaches that require scrutiny
• Layer 3 — First-principles reasoning that is prized above all

The document also introduces the Eureka moment: when first-principles reasoning contradicts conventional wisdom, the agent must name the insight and log it for analytics.

Generating the Preamble Section

The [generate-search-before-building.ts](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/preamble/generate-search-before-building.ts) resolver transforms the ETHOS.md definitions into executable instructions. It exports a single function that returns a markdown block tailored to the current skill context:

// scripts/resolvers/preamble/generate-search-before-building.ts
export function generateSearchBeforeBuildingSection(ctx: TemplateContext): string {
  return `## Search Before Building

Before building anything unfamiliar, **search first**. See \`${ctx.paths.skillRoot}/ETHOS.md\`.
- **Layer 1** (tried and true) — don't reinvent.
- **Layer 2** (new and popular) — scrutinize.
- **Layer 3** (first principles) — prize above all.

**Eureka:** When first‑principles reasoning contradicts conventional wisdom, name it and log:
\`\`\`bash
jq -n --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
     --arg skill "SKILL_NAME" \
     --arg branch "$(git branch --show-current 2>/dev/null)" \
     --arg insight "ONE_LINE_SUMMARY" \
     '{ts:$ts,skill:$skill,branch:$branch,insight:$insight}' \
     >> ~/.gstack/analytics/eureka.jsonl 2>/dev/null || true
\`\`\``;
}

This function injects the three-layer framework and a copy-pasteable logging command that agents can execute when they encounter a Eureka insight.

Tier-Based Injection into Skills

The [preamble.ts](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/preamble.ts) resolver controls which skills receive the Search Before Building section. It conditionally appends the generated markdown only to tier 3 or higher skills, ensuring foundational workflows receive the full guidance while lightweight skills remain uncluttered:

// scripts/resolvers/preamble.ts
if (tier >= 3) {
  sections.push(
    generateRepoModeSection(),
    generateSearchBeforeBuildingSection(ctx)
  );
}

This tier-gating ensures that complex, multi-step skills—such as architectural planning or eng-review workflows—carry the SBB mandate, while simple utility skills skip the overhead.

Preventing Duplication in Skill Composition

When skills invoke other skills via {{INVOKE_SKILL:...}}, the [composition.ts](https://github.com/garrytan/gstack/blob/main/scripts/resolvers/composition.ts) resolver prevents redundant Search Before Building sections from stacking. It includes the section title in a skip list that parent skills pass to children:

// scripts/resolvers/composition.ts
const DEFAULT_SKIPS = [
  'Preamble (run first)',
  'AskUserQuestion Format',
  'Completeness Principle — Boil the Lake',
  'Search Before Building',
  // ... other skipped sections
];

By declaring "Search Before Building" as a default skip, the system ensures the principle appears exactly once per workflow chain, maintaining clean context windows.

Logging Eureka Moments

The implementation includes a concrete logging mechanism for Layer 3 (first principles) breakthroughs. When an agent's reasoning contradicts conventional wisdom, the preamble instructs them to append a structured JSON line to ~/.gstack/analytics/eureka.jsonl using jq. This creates an audit trail of novel insights that can be analyzed later to measure how often the system breaks from established patterns.

Summary

• ETHOS.md defines the Search Before Building principle and its three knowledge layers (tried and true, new and popular, first principles).
• generateSearchBeforeBuildingSection in generate-search-before-building.ts renders the principle as a markdown block with Eureka logging instructions.
• preamble.ts injects the section only into tier ≥ 3 skills, targeting complex workflows.
• composition.ts skips the section in child skill invocations to prevent duplication.
• The Eureka logging command provides a concrete mechanism for agents to record first-principles insights.

Frequently Asked Questions

What are the three knowledge layers in gstack's Search Before Building?

According to the source code in ETHOS.md, the three layers are Layer 1 (tried and true solutions that should not be reinvented), Layer 2 (new and popular approaches requiring scrutiny), and Layer 3 (first-principles reasoning that is prized above all others). Agents must search these layers sequentially before generating unfamiliar code.

How does gstack prevent duplicate Search Before Building sections?

The composition.ts resolver includes "Search Before Building" in its DEFAULT_SKIPS array. When a parent skill invokes a child skill, this skip list ensures the SBB preamble is rendered only once at the top of the workflow chain, avoiding context window bloat.

What triggers the Eureka moment logging?

A Eureka moment occurs when an agent applies first-principles reasoning (Layer 3) that contradicts conventional wisdom or established patterns. The generateSearchBeforeBuildingSection function injects a bash command using jq that appends a timestamped JSON object to ~/.gstack/analytics/eureka.jsonl, creating an audit trail of novel insights.

Which skills include the Search Before Building preamble?

Only tier 3 or higher skills receive the Search Before Building section. The preamble.ts resolver checks the tier variable and conditionally pushes the generated section into the skill's preamble array, ensuring complex skills enforce the principle while lightweight utilities remain streamlined.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}