| 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:
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.
- Name specific types, methods, file locations, schemas, or behaviors.
- Make criteria architecture-aware — reference the project's patterns (ports/adapters, event sourcing, CQRS) when the implementation must conform.
- Order criteria from foundational to dependent — the implementing agent reads them top to bottom.
- Include a testing criterion — specify what tests exist and what they verify.
- If a refactoring skill applies, add
skill:<skill-name> as a criterion.
Scope
Scope tells the implementing agent where to work and where not to touch.
--scope-in "src/application/telemetry/" "src/infrastructure/posthog/" "src/cli/commands/config.ts"
--scope-out "src/domain/" "src/infrastructure/persistence/"
Rules:
- Use file paths or directory prefixes, not abstract descriptions.
scope-in lists files/directories that WILL be created or modified.scope-out lists files/directories that MUST NOT be modified (protects unrelated code).- When creating new files, include the intended path in scope-in even though it does not exist yet.
- Scope-out is especially valuable for goals that touch shared infrastructure — it prevents the agent from "fixing" unrelated code.
5. Register the Goal
Run jumbo goal add --help to confirm current flags and syntax before registering. Pass the objective, criteria, scope, and sequencing flags composed in the previous steps.
For multi-goal decompositions, register goals in dependency order so that sequencing flags can reference already-created IDs.
Goal Chaining with Previous/Next Goals
The --previous-goal and --next-goal flags create a chain — an ordered sequence of goals that an agent works through end-to-end. Chaining is distinct from prerequisites:
- Prerequisites (
--prerequisite-goals) are hard gates — a goal cannot start until its prerequisites are complete.
- Chains (
--previous-goal / --next-goal) are navigational — when the agent finishes one goal, the chain tells it what to pick up next without the user intervening.
Chaining is the primary mechanism for long-running autonomous sessions without context rot. Each goal in the chain carries its own focused context assembled at start time. When the agent completes goal A and transitions to goal B, jumbo goal start assembles fresh, relevant context for B — discarding the accumulated noise from A's implementation. The agent effectively gets a clean context window scoped precisely to the next unit of work, without losing the benefits of sequential execution.
When to chain:
- Work decomposes into ordered steps where each builds on the prior (e.g., "define port abstraction" → "implement adapter" → "wire into CLI").
- The combined work would exceed comfortable context limits if attempted as a single goal.
When NOT to chain:
- Goals are independent and can be worked in any order — leave them unchained so the agent (or user) can prioritize freely.
- Goals have hard dependencies where failure of one invalidates the next — use
--prerequisite-goals instead, which enforces completion before start.
6. Verify Before Handing Off
After all goals are registered, verify:
Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|
| "Implement feature X" as sole criterion | Agent has no spec, explores and guesses | Break into 5-8 specific verifiable outcomes |
| Scope-in says "src/" | Everything is in scope, nothing is protected | List specific directories and files |
| No scope-out | Agent may refactor neighboring code | Explicitly exclude adjacent areas |
| Goal mixes domain + infrastructure + tests | Too broad, risks compaction | Split by architectural layer |
| Criteria reference "should" or "ideally" | Ambiguous — pass or fail? | Rewrite as binary verifiable statements |
| 15+ criteria on one goal | Goal is too large | Decompose into multiple goals |
| No testing criterion | Agent skips tests | Always include what tests must exist |
Rules
- Never register a goal without discovery. Always explore the architecture, components, and constraints before writing objectives and criteria. Definition without context produces goals that fight the architecture.
- Never write criteria the reviewing agent cannot verify. If a criterion requires subjective judgment ("clean code", "good performance"), replace it with a measurable statement ("no function exceeds 30 lines", "response time under 200ms for 1000 records").
- Never skip scope. Every goal must have scope-in. Most goals should have scope-out. Unbounded scope invites unbounded implementation.
- Always decompose before defining. Resist the urge to create one large goal. Think in shippable increments.
- Always verify goal coverage. The union of all goals must fully address the starting objective. Gaps between goals are gaps in delivery.
