# How gstack Implements the Search Before Building Principle

> Discover how gstack enforces Search Before Building. It injects ETHOS.md knowledge layers and logs Eureka moments before code generation, ensuring efficient development.

- Repository: [Garry Tan/gstack](https://github.com/garrytan/gstack)
- Tags: how-to-guide
- Published: 2026-05-15

---

**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](https://github.com/garrytan/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)](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/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:

```typescript
// 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/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:

```typescript
// 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/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:

```typescript
// 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`](https://github.com/garrytan/gstack/blob/main/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`](https://github.com/garrytan/gstack/blob/main/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`](https://github.com/garrytan/gstack/blob/main/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.