sage

Corrects the 13 most common API design mistakes agents make — grounded in Geewax, Amundsen, Ousterhout, Kleppmann, and Gough/Bryant

Autonomous iteration toward a measurable outcome. Use when the user wants to optimize a numeric metric through repeated modify-verify cycles — reduce bundle size, increase test coverage, improve query time, lower readability score. Not for exploratory research, subjective judgment, or tasks without a verification command.

**Layer 1 — Domain Foundation**

Flutter patterns — widget architecture, state management, Impeller renderer, platform-adaptive design

Systematically uncovers customer jobs, pains, and gains using the Jobs-to-be-Done framework. Produces structured JTBD analyses with job performer definitions, job process maps, pains/gains, and desired outcome statements. Use when the user mentions jobs to be done, JTBD, customer jobs, unmet needs, pains and gains, value proposition canvas, switch interviews, outcome-driven innovation, desired outcomes, or asks why customers hire or fire a product. Also triggers when the user wants to understand what job a product solves, conduct customer discovery, reposition a product around needs, define unmet needs for a roadmap, analyze competitors through a jobs lens, or create messaging grounded in customer objectives. Do NOT use for general market sizing, feature prioritization without a customer-needs lens, or persona creation based on demographics alone.

Integrates sage-memory into Sage workflows. Teaches the agent when to remember (store findings during work), when to recall (search memory at session start and task start), and how to learn (structured knowledge capture via sage learn). Use when the user mentions memory, remember, recall, learn, capture knowledge, onboard to codebase, or when starting any session where sage-memory MCP tools are available.

Universal mobile development principles — offline-first, 60fps, touch, battery, platform patterns

Next.js 14/15 App Router patterns — server components, data fetching, caching, server actions

Typed knowledge graph stored in sage-memory. Use when creating or querying structured entities (Person, Project, Task, Event, Document), linking related objects, checking dependencies, planning multi-step actions as graph transformations, or when skills need to share structured state. Trigger on "remember that X is Y", "what do I know about", "link X to Y", "show dependencies", "what blocks X", entity CRUD, cross-skill data access, or any request involving structured relationships between things. Also trigger when the memory skill is active and the agent needs typed structure beyond flat prose.

Produces an opportunity map that assesses discovered customer needs against product capabilities, determines which to pursue, and sequences them. Takes any discovery output (JTBD analysis, research findings, lean canvas) as input and applies inside-out assessment to produce pursue/monitor/defer decisions. Use when the user asks what to focus on, what to build next, which opportunities to prioritize, or how to sequence product work. Also triggers when the user says "help me decide what to pursue" or "we have too many opportunities, help us focus." Do NOT use for detailed requirements (that's PRD) or for understanding customer needs (that's discovery).

Phase 1 of pack building. Identifies what pack to create, checks for existing packs, classifies the layer, and forks between community pack and project overlay paths. Triggers on: build a pack, create a pack, customize pack, make a skill pack.

Phase 4 of pack building. Generates pack files from observations and processed sources. Handles both community pack (full structure) and project overlay (overrides.md only) paths.

Phase 3 of pack building. Runs test prompts WITHOUT the pack loaded to establish a baseline of agent failures. Records what the agent gets wrong as evidence for patterns and anti-patterns. Community pack path only — overlays skip this phase.

Phase 2 of pack building. Gathers sources (docs, blogs, issues, user context) and filters them through the judgment-not-knowledge lens. Extracts only information that corrects agent mistakes — discards documentation summaries.

Phase 5 of pack building. Runs automated checks, re-runs test prompts WITH the pack loaded, and measures behavior change against the Phase 3 baseline. Determines if the pack earns its context tokens.

Produces a Product Requirements Document (PRD) grounded in JTBD outcomes. Takes a JTBD analysis as input and transforms high-opportunity outcomes into structured, prioritized, testable requirements. Use when the user mentions PRD, product requirements, product spec, requirements document, or asks what to build based on a JTBD analysis. Also triggers when the user wants to define scope for an initiative, align a team on what to build, or translate customer needs into product requirements. Do NOT use for technical design documents, project plans, or feature specs that prescribe solutions.

Systematic techniques for breaking through when stuck. Activate when: the agent has tried 3+ approaches without resolution, complexity is spiraling with growing special cases, a test keeps failing after multiple fix attempts, or the solution feels forced with no alternatives considered.

Product management process — JTBD analysis, opportunity mapping, user interview design, and PRD writing. Discovery → Planning → Delivery.

React Native patterns — New Architecture (Fabric/TurboModules), Expo, navigation, performance

React 18/19 patterns and anti-patterns — hooks discipline, component architecture, state management

Captures agent mistakes, corrections, and discovered gotchas so they are not repeated. Use when: (1) a command or operation fails unexpectedly, (2) the user corrects the agent, (3) the agent discovers non-obvious behavior through debugging, (4) an API or tool behaves differently than expected, (5) a better approach is found for a recurring task. Also searches past learnings before starting tasks to avoid known pitfalls. Activate alongside the memory skill — they share sage-memory but serve different purposes (memory = codebase knowledge, self-learning = agent mistakes and gotchas).

Build, validate, and publish Sage skills — discover patterns from source material, draft skill files, validate quality.

Integration patterns for Flutter + Firebase + Riverpod — auth, Firestore, Cloud Functions, project structure

Integration patterns for Next.js + Tailwind CSS + Prisma + Auth.js — the seams between frameworks

**Layer 3 — Stack Composition**

Integration patterns for Expo + React Navigation + Zustand + MMKV + TanStack Query

Designs complete user interview research packages: research brief, screener, interview guide, and analysis framework. Supports discovery interviews, switch interviews, contextual inquiry, and evaluative interviews. Use when the user needs to validate JTBD hypotheses, test a concept with users, understand switching behavior, or observe how users interact with a product. Also triggers when the user says "I need to talk to users," "help me plan user interviews," "write an interview guide," "I need to validate this assumption," or "design a research study." Do NOT use for quantitative research (surveys, A/B tests) or for conducting the research itself.

Reverse-engineers the current design system from screenshots or a live URL. Extracts colors, typography, spacing, component patterns, and layout structure. Use when redesigning an existing page, auditing a current design, or when the user says "audit this design", "what's the current design system", "analyze this page", or provides a URL and says "redesign".

Produces a design brief from the evaluation that feeds directly into the specification and planning skills. Translates MUST keep / MAY change / SHOULD improve classifications into concrete design directions with user-confirmed decisions. Use after ux-evaluate when the user has confirmed the classifications, or when the user says "create the design brief", "what should the redesign look like", or "write the design direction".

UX design process — research, evaluation, specification, design, and review woven into the development workflow.

User research and context gathering — understands who users are, what they do, and why

Compares current design system against category benchmarks to produce a structured gap analysis. Classifies every design element as MUST keep (brand identity), SHOULD keep (working patterns), MAY change (style updates), or SHOULD improve (gaps vs. category). Use after ux-audit and ux-research complete, or when the user says "evaluate this design", "what should we change", "gap analysis", or "compare against competitors".

Evaluates implementation against usability heuristics — Nielsen's 10, Norman's principles, Krug's laws

Adds UX-specific tasks to the development plan — usability testing, review checkpoints, design validation

Researches design patterns and best practices from category leaders for a specific product type. Analyzes competitor homepages, landing pages, or app screens to identify industry conventions and opportunities for differentiation. Use when redesigning and the user says "research competitors", "what do others do", "best practices for this type of page", or during a redesign task where category context would improve decisions.

Enriches feature specifications with UX requirements — error states, user flows, accessibility, five-planes analysis

Produces UX writing deliverables: voice and tone guides, microcopy for specific features, and content audits of existing product copy. Use when the user needs to define a product's voice, write interface copy for a feature, audit existing microcopy quality, or establish UX writing guidelines. Also triggers when the user says "write the button labels," "what should the error message say," "create a voice and tone guide," "audit the product copy," "write microcopy for this flow," or "the copy doesn't sound right." Do NOT use for marketing copy, blog posts, landing page content, or email campaigns — those are marketing writing, not UX writing.

Universal web development principles — accessibility (WCAG 2.2), performance (Core Web Vitals), security headers (OWASP), SEO, responsive design, error UX, and loading states. Framework-agnostic.