Refine Jumbo Goals

Refine Jumbo Goals

Prompt: Refine one or more Jumbo goals by registering comprehensive relations to project entities so that an autonomous agent has optimal context for correct implementation.

Why Refinement Matters

When jumbo goal start is run, the goal's registered relations determine what context is assembled and provided to the implementing agent. Missing relations mean missing constraints, patterns, or domain knowledge. Irrelevant relations waste tokens and dilute focus. Thorough refinement is the single highest-leverage activity for autonomous goal execution quality.

Protocol

1. Initiate Refinement

jumbo goal refine --id <goal-id>

Review the goal's objective, criteria, and scope.

2. Explore All Project Entities

You MUST explore ALL entity categories to build a complete picture of available entities:

jumbo invariants list
jumbo guidelines list
jumbo decisions search -q <query>
jumbo dependencies search -q <query>
jumbo components search -q <query>

Here are some examples demonstrated various ways to search for components:

# Search by name (substring or wildcard)
jumbo components search --name "Auth*"
jumbo components search --name "*Gateway"

# Search by type
jumbo components search --type service
jumbo components search --type lib

# Free-text search across description and responsibility
jumbo components search --query "event handling"

# Compact output for quick discovery (id, name, type only)
jumbo components search --output compact --type service

# Combine filters (AND logic)
jumbo components search --name "*Controller" --type service

Run multiple targeted searches derived from the goal's domain. Only fall back to jumbo components list if searches are insufficient to identify all relevant components.

Do not skip any entity category. Every category is a potential source of implementation context.

3. Evaluate Every Entity Against the Goal

Use different evaluation strategies depending on the entity category:

Invariants & Guidelines — evaluate by exclusion

Review every invariant and guideline returned. For each, ask: "Can I confidently say the implementing agent will never need this?" Only exclude those where the answer is clearly yes. A missed constraint causes QA rejections — but over-relating creates context rot that dilutes focus. The bar is confidence of irrelevance, not possible relevance.

• Invariants: Review all. Exclude only those confidently unrelated to the goal's scope.
• Guidelines: Review all. Exclude only those confidently unrelated to the goal's scope.

Components, Decisions & Dependencies — evaluate by inclusion

Use targeted searches to find entities the implementation will modify, use, or depend on. For each candidate, ask: "Will the implementing agent need to know about this to execute correctly?" Only register entities with direct, actionable relevance.

• Decisions: Which architectural decisions inform, motivate, or constrain this change?
• Components: Which system components will be created, modified, deleted, or depended upon?
• Dependencies: Which external libraries are involved in the implementation?

4. Register Relations

For every relevant entity, register a relation:

jumbo relation add \
  --from-type goal \
  --from-id <goal-id> \
  --to-type <entity-type> \
  --to-id <entity-id> \
  --relation-type <type> \
  --description "<why this relation matters for implementation>"

Relation types:

Description quality is critical. The description is what the implementing agent reads. It must explain the specific relevance to this goal, not just restate the entity's title.

• BAD: "Related to this invariant"
• BAD: "Must follow this guideline"
• GOOD: "Removal must not leave orphaned registrations or broken import paths across layer boundaries"
• GOOD: "Ensure the read-side query path remains intact after removing the old handler"