gstack/docs/designs/SELF_LEARNING_V0.md

Design: GStack Self-Learning Infrastructure

Generated by /office-hours + /plan-ceo-review + /plan-eng-review on 2026-03-28 Branch: garrytan/ce-features Repo: gstack Status: ACTIVE Mode: Open Source / Community

Problem Statement

GStack runs 30+ skills across sessions but learns nothing between them. A /review session catches an N+1 query pattern, and the next /review on the same codebase starts from scratch. A /ship run discovers the test command, and every future /ship re-discovers it. A /investigate finds a tricky race condition, and no future session knows about it.

Every AI coding tool has this problem. Cursor has per-user memory. Claude Code has CLAUDE.md. Windsurf has persistent context. But none of them compound. None of them structure what they learn. None of them share knowledge across skills.

What We're Building

Per-project institutional knowledge that compounds across sessions and skills. Structured, typed, confidence-scored learnings that every gstack skill can read and write. The goal: after 20 sessions on the same codebase, gstack knows every architectural decision, every past bug pattern, and every time it was wrong.

North Star

/autoship (Release 4). A full engineering team in one command. Describe a feature, approve the plan, everything else is automatic. /autoship can't work without learnings, because without memory it repeats the same mistakes. Releases 1-3 are the infrastructure that makes /autoship actually work.

Audience

YC founders building with AI. The people who run gstack on real codebases 20+ times a week and notice when it asks the same question twice.

Differentiation

Tool	Memory model	Scope	Structure
Cursor	Per-user chat memory	Per-session	Unstructured
CLAUDE.md	Static file	Per-project	Manual
Windsurf	Persistent context	Per-session	Unstructured
GStack	Per-project JSONL	Cross-session, cross-skill	Typed, scored, decaying

---

Release Roadmap

Release 1: "GStack Learns" (v0.14)

Headline: Every session makes the next one smarter.

What ships:

• Learnings persistence at ~/.gstack/projects/{slug}/learnings.jsonl
• /learn skill for manual review, search, prune, export
• Confidence calibration on all review findings (1-10 scores with display rules)
• Confidence decay for observed/inferred learnings (1pt/30d)
• Cross-project learnings discovery (opt-in, AskUserQuestion consent)
• "Learning applied" callouts when reviews match past learnings
• Integration into /review, /ship, /plan-*, /office-hours, /investigate, /retro

Schema (Supabase-compatible):

{
  "ts": "2026-03-28T12:00:00Z",
  "skill": "review",
  "type": "pitfall",
  "key": "n-plus-one-activerecord",
  "insight": "Always check includes() for has_many in list endpoints",
  "confidence": 8,
  "source": "observed",
  "branch": "feature-x",
  "commit": "abc1234",
  "files": ["app/models/user.rb"]
}

Types: pattern | pitfall | preference | architecture | tool Sources: observed | user-stated | inferred | cross-model

Architecture: append-only JSONL. Duplicates resolved at read time ("latest winner" per key+type). No write-time mutation, no race conditions. Follows the existing gstack-review-log pattern.

Release 2: "Review Army" (v0.15)

Headline: 10 specialist reviewers on every PR.

What ships:

• Parallel review agents: always-on (correctness, testing, maintainability) + conditional (security, performance, API, data-migrations, reliability) + stack-specific (Rails, TypeScript, Python, frontend-races)
• Red team reviewer activated for large diffs and high-risk domains
• Structured findings with confidence scores + merge/dedup across agents

Release 3: "Smart Ceremony" (v0.16)

Headline: GStack respects your time.

What ships:

• Scope assessment (TINY/SMALL/MEDIUM/LARGE) in /review, /ship, /autoplan
• Ceremony skipping based on diff size and scope category
• File-based todo lifecycle (/triage for interactive approval, /resolve for batch resolution via parallel agents)

Release 4: "/autoship — One Command, Full Feature" (v0.17)

Headline: Describe a feature. Approve the plan. Everything else is automatic.

What ships:

• /autoship autonomous pipeline: office-hours → autoplan → build → review → qa → ship → learn. 7 phases, 1 approval gate (the plan).
• /ideate brainstorming skill (parallel divergent agents + adversarial filtering)
• Research agents in /plan-eng-review (codebase analyst, history analyst, best practices researcher, learnings researcher)

Release 5: "Studio" (v0.18)

Headline: The full-stack AI engineering studio.

What ships:

• Figma design sync (pixel-matching iteration loop)
• Feature video recording (auto-generated PR demos)
• PR feedback resolution (parallel comment resolver)
• Swarm orchestration (multi-worktree parallel builds)
• /onboard (auto-generated contributor guide)
• /triage-prs (batch PR triage for maintainers)
• Codex build delegation (delegate implementation to Codex CLI)
• Cross-platform portability (Copilot, Kiro, Windsurf output)

---

Acknowledged Inspiration

The self-learning roadmap was inspired by ideas from the Compound Engineering project by Nico Bailon. Their exploration of learnings persistence, parallel review agents, and autonomous pipelines catalyzed the design of GStack's approach. We adapted every concept to fit GStack's template system, voice, and architecture rather than porting directly.