/define-jumbo-goals

name: define-jumbo-goals
description: Add Jumbo goals liberally to decompose objectives into finite units of work with bounded context. Use when defining new Jumbo goals from user requests, or to augment your own work to maintain scope while ensuring complementary work is registered.

Define Jumbo Goals

**Prompt:** Analyze the primary objective to discover the architectural context required, decompose the work into right-sized goals, and author each goal with precise objectives, verifiable criteria, and explicit scope — so that refinement and implementation proceed with minimal exploration overhead.

Why Definition Quality Matters

A goal's definition determines everything downstream. During refinement, the agent registers relations based on the objective and criteria. During implementation, `jumbo goal start` assembles context from those relations into an implementation prompt. Vague objectives produce vague relations. Vague relations produce bloated or incomplete context. The implementing agent then wastes tokens exploring what should have been stated upfront, or worse, builds the wrong thing.

**The goal definition is the spec.** Treat it with the rigor of a technical specification, not a backlog item.

Protocol

1. Align Goal and Project Purpose

Start by getting oriented with the overall project purpose (use a cached response if previously run in this session):

jumbo project show --northstar

The initiative to define a new goal could be self-driven, or have eminated from the user:

If from the User

Extract the user's intent through conversation. Identify:

• **What** needs to change (feature, fix, refactor, infrastructure)
• **Why** it needs to change (user problem, tech debt, prerequisite for other work)
• **Constraints** the user cares about (performance, compatibility, patterns to follow)

If the request is ambiguous, ask clarifying questions before proceeding. Do not guess intent.

If Self-Driven

Ensure the initiative is not in conflict with the project purpose. Abandon the initiative if it is, or adjust if slight fitting would align it.

2. Understand Context

Before writing any goal, survey the project to understand what exists:

jumbo components search --q "<query terms>"
jumbo components search --type <likely-type>
jumbo invariants search --q "<query terms>"
jumbo guidelines search --q "<query terms>"
jumbo decisions search --q "<query terms>"
jumbo dependencies search --q "<query terms>"

This discovery serves two purposes:

• **Inform decomposition**: Understanding the system's boundaries, patterns, and constraints reveals the natural seams along which to split work.
• **Inform criteria**: Existing invariants, decisions, and patterns dictate what "correct" looks like.

Also explore the codebase directly to understand current implementation:

# Find relevant source files
# Read key files to understand existing patterns
# Identify integration points and boundaries

3. Decompose into Right-Sized Goals

A goal is **right-sized** when:

• It produces a **shippable increment** — the codebase is better after this goal alone, even if later goals are never started.
• It can be **implemented in a single session** — an agent can start and complete it without context compaction.
• It has a **clear boundary** — scope-in and scope-out can be stated without hedging.
• It touches **one architectural concern** — avoid goals that mix, e.g., domain modeling with UI work with infrastructure changes.

**Decomposition heuristics:**

| Signal | Action | |--------|--------| | Work spans multiple bounded contexts or layers | Split by context/layer | | Work requires a new abstraction before feature code | Split: abstraction goal first, feature goal second | | Work has independent sub-deliverables | Split into parallel goals (no prerequisite chain) | | Work has sequential dependencies | Split into chained goals (use `--previous-goal` / `--next-goal`) | | Work is a single focused change | Keep as one goal |

**Sequencing tools:**

• `--prerequisite-goals <ids>`: Hard dependency — goal cannot start until prerequisites are complete.
• `--previous-goal <id>` / `--next-goal <id>`: Suggested ordering — chains goals for sequential flow.

When chaining goals, prefix each goal's title with its position in the chain (e.g., `1/3 Deprecate Architecture entity`, `2/3 Migrate context packets`, `3/3 Remove Architecture entity`). This communicates execution order to users and agents reviewing the backlog.

4. Author Each Goal

For each goal, compose the three pillars: **objective**, **criteria**, and **scope**.

Objective

The objective is a single sentence that answers: "What is being built or changed, and why?"

| Quality | Example | |---------|---------| | BAD | "Implement telemetry" | | BAD | "Add PostHog integration for tracking" | | GOOD | "Add anonymous usage telemetry to the CLI using PostHog so we can understand which commands are used and where failures occur" |

Rules:

• State the **what** and the **why** in one sentence.
• Name specific technologies, patterns, or components when known.
• Do not describe how — that belongs in criteria.

Success Criteria

Each criterion is a **verifiable statement** that the reviewing agent can confirm by reading code or running tests. Criteria are the implementation instructions in disguise.

| Quality | Example | |---------|---------| | BAD | "Telemetry works" | | BAD | "Good test coverage" | | GOOD | "Application layer defines a TelemetryPort interface with `trackEvent(name, properties)` and `identify(anonymousId)` methods" | | GOOD | "Infrastructure adapter implements TelemetryPort using PostHog Node SDK with fire-and-forget sends that never block the CLI event loop" | | GOOD | "First-run consent prompt stores preference in `~/.config/jumbo/telemetry.json` with schema `{ enabled: boolean, promptedAt: string }`" |

Rules:

• Each criterion describes a **single verifiable outcome**.