Issue Intelligence (Phase 1, conditional)

Read this when Phase 1 step 4 fires — issue-tracker intent was detected in Phase 0.2. references/grounding.md owns the four-step sequence (scan → fall back or scope → cluster → await); this file owns the payload of each call and the scoping question's construction.

The lens works against whichever tracker is reachable — GitHub, Linear, or Jira. Probe by capability (a connector/MCP, a documented API, or a documented CLI), never by assuming a specific binary exists. A missing binary or env var is not proof the tracker is unreachable.

a. Scan call

Read references/agents/issue-intelligence-analyst.md and dispatch a generic subagent seeded with that prompt, the focus hint, the <scratch-dir> resolved earlier in Phase 1, and the instruction that it is in SCAN mode.

It probes tracker access, does one bounded fetch, persists that fetched set to <scratch-dir>/issue-scan.json, and returns the distribution, a signal count, and an ambiguity assessment. It does not cluster.

The scan call may run alongside the other Phase 1 grounding agents.

b. Fallback markers

Two outcomes end the lens before the cluster call. Both are warn-and-proceed — never block the run on them:

First line is the Issue analysis unavailable: marker (no reachable tracker) — log "{that message}. Proceeding with standard ideation." and continue with the remaining grounding.
Fewer than 5 eligible issues — note "Insufficient issue signal for theme analysis" and continue.

In both cases Phase 2 falls back to the six-frame default fleet rather than the 4-agent issue-tracker fleet — and a fallback re-derives only what the abandoned surface determined, and never re-resolves anything else. Carry forward Phase 0.5's already-resolved scaling state — which overrides ended up active after its collisions, plus the raw total or explicit survivor count. Do not re-read the prompt's raw signals: a go deep run that also said quick wins has already had tactical suppressed, and re-deriving from the raw signal would resurrect the waived floor and lowered volume on a maximum-depth run. Re-derive only the two values the frame count determined — the agent count and the per-frame split — because the surface changes from at most 4 themes to the 6 defaults. Carrying the old agent count would leave 4 agents holding 6 frames, the packing this skill rejects; carrying the old per-frame volume would multiply a requested total by the new frame count. See the fleet variants in references/divergent-ideation.md. No scoping question is asked.

b. Scoping gate (the orchestrator decides; at most one question)

Read the scan's ambiguity assessment.

Auto-scope silently by default. Compose the scope from focus hint → priority (when populated) → workflow-state → recency.

Fire one blocking scoping question (per the asking rules in references/grounding.md) only on irreducible ambiguity: two or more coherent, materially-different scopes that no single deliberately-varied sample could fairly represent. Skip it entirely when the scan is unambiguous.

Its options are the scan's distribution-derived slices plus an always-present "analyze a representative sample of everything," so the user can decline to narrow. When the slices plus that option would exceed the platform's blocking-tool option cap (Codex request_user_input takes 2-3 explicit options; AskUserQuestion takes 4), show the highest-mass slices that fit and fold the rest into the representative-sample option, or fall back to a numbered chat list. Never drop the representative-sample option.

This is a grounding / subject-scoping question — the same kind as the Phase 0.2 subject gate ("what should the agent work on"), not a Phase 0.4 solution-constraint question. It counts toward the ≤3-question grain, and "Surprise me" stays available.

c. Cluster call

Dispatch the analyst again in CLUSTER mode, passing the resolved scope and the same <scratch-dir> so it reuses the persisted issue-scan.json rather than re-fetching. It returns the leverage-ranked themes plus coverage accounting.

d. What consolidation must carry

The consolidated grounding summary's Issue intelligence section carries the theme summaries (titles, descriptions, issue counts, leverage, trend directions) and the cluster call's coverage accounting — fetched / eligible / analyzed / excluded / unknown-remainder, with any >N lower bound. That accounting is the non-exhaustive-coverage disclosure; it has to reach Phase 2 ideation and the Phase 4 artifact rather than being dropped at consolidation.

Themes become Phase 2 frames per the issue-tracker override in references/divergent-ideation.md.

4.7 KiB Raw Permalink Blame History