diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 626c8e8..b291a64 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "plugins": [ { "name": "compound-engineering", - "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 28 specialized agents and 47 skills.", + "description": "AI-powered development tools that get smarter with every use. Make each unit of engineering work easier than the last. Includes 29 specialized agents and 47 skills.", "version": "2.40.0", "author": { "name": "Kieran Klaassen", diff --git a/docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md b/docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md new file mode 100644 index 0000000..9afc291 --- /dev/null +++ b/docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md @@ -0,0 +1,65 @@ +--- +date: 2026-03-16 +topic: issue-grounded-ideation +--- + +# Issue-Grounded Ideation Mode for ce:ideate + +## Problem Frame + +When a team wants to ideate on improvements, their issue tracker holds rich signal about real user pain, recurring failures, and severity patterns — but ce:ideate currently only looks at the codebase and past learnings. Teams have to manually synthesize issue patterns before ideating, or they ideate without that context and miss what their users are actually hitting. + +The goal is not "fix individual bugs" but "generate strategic improvement ideas grounded in the patterns your issue tracker reveals." 25 duplicate bugs about the same failure mode is a signal about collaboration reliability, not 25 separate problems. + +## Requirements + +- R1. When the user's argument indicates they want issue-tracker data as input (e.g., "bugs", "github issues", "open issues", "what users are reporting", "issue patterns"), ce:ideate activates an issue intelligence step alongside the existing Phase 1 scans +- R2. A new **issue intelligence agent** fetches, clusters, deduplicates, and analyzes issues, returning structured theme analysis — not a list of individual issues +- R3. The agent fetches **open issues** plus **recently closed issues** (approximately 30 days), filtering out issues closed as duplicate, won't-fix, or not-planned. Recently fixed issues are included because they show which areas had enough pain to warrant action. +- R4. Issue clusters drive the ideation frames in Phase 2 using a **hybrid strategy**: derive frames from clusters, pad with default frames (e.g., "assumption-breaking", "leverage/compounding") when fewer than 4 clusters exist. This ensures ideas are grounded in real pain patterns while maintaining ideation diversity. +- R5. The existing Phase 1 scans (codebase context + learnings search) still run in parallel — issue analysis is additive context, not a replacement +- R6. The issue intelligence agent detects the repository from the current directory's git remote +- R7. Start with GitHub issues via `gh` CLI. Design the agent prompt and output structure so Linear or other trackers can be added later without restructuring the ideation flow. +- R8. The issue intelligence agent is independently useful outside of ce:ideate — it can be dispatched directly by a user or other workflows to summarize issue themes, understand the current landscape, or reason over recent activity. Its output should be self-contained, not coupled to ideation-specific context. +- R9. The agent's output must communicate at the **theme level**, not the individual-issue level. Each theme should convey: what the pattern is, why it matters (user impact, severity, frequency, trend direction), and what it signals about the system. The output should help a human or agent fully understand the importance and shape of each theme without needing to read individual issues. + +## Success Criteria + +- Running `/ce:ideate bugs` on a repo with noisy/duplicate issues (like proof's 25+ LIVE_DOC_UNAVAILABLE variants) produces clustered themes, not a rehash of individual issues +- Surviving ideas are strategic improvements ("invest in collaboration reliability infrastructure") not bug fixes ("fix LIVE_DOC_UNAVAILABLE") +- The issue intelligence agent's output is structured enough that ideation sub-agents can engage with themes meaningfully +- Ideation quality is at least as good as the default mode, with the added benefit of issue grounding + +## Scope Boundaries + +- GitHub issues only in v1 (Linear is a future extension) +- No issue triage or management — this is read-only analysis for ideation input +- No changes to Phase 3 (adversarial filtering) or Phase 4 (presentation) — only Phase 1 and Phase 2 frame derivation are affected +- The issue intelligence agent is a new agent file, not a modification to an existing research agent +- The agent is designed as a standalone capability that ce:ideate composes, not an ideation-internal module +- Assumes `gh` CLI is available and authenticated in the environment +- When a repo has too few issues to cluster meaningfully (e.g., < 5 open+recent), the agent should report that and ce:ideate should fall back to default ideation with a note to the user + +## Key Decisions + +- **Pattern-first, not issue-first**: The output is improvement ideas grounded in bug patterns, not a prioritized bug list. The ideation instructions already prevent "just fix bug #534" thinking. +- **Hybrid frame strategy**: Clusters derive ideation frames, padded with defaults when thin. Pure cluster-derived frames risk too few frames; pure default frames risk ignoring the issue signal. +- **Flexible argument detection**: Use intent-based parsing ("reasonable interpretation rather than formal parsing") consistent with the existing volume hint system. No rigid keyword matching. +- **Open + recently closed**: Including recently fixed issues provides richer pattern data — shows which areas warranted action, not just what's currently broken. +- **Additive to Phase 1**: Issue analysis runs as a third parallel agent alongside codebase scan and learnings search. All three feed the grounding summary. +- **Titles + labels + sample bodies**: Read titles and labels for all issues (cheap), then read full bodies for 2-3 representative issues per emerging cluster. This handles both well-labeled repos (labels drive clustering, bodies confirm) and poorly-labeled repos (bodies drive clustering). Avoids reading all bodies which is expensive at scale. + +## Outstanding Questions + +### Deferred to Planning + +- [Affects R2][Technical] What structured output format should the issue intelligence agent return? Likely theme clusters with: theme name, issue count, severity distribution, representative issue titles, and a one-line synthesis. +- [Affects R3][Technical] How to detect GitHub close reasons (completed vs not-planned vs duplicate) via `gh` CLI? May need `gh issue list --state closed --json stateReason` or label-based filtering. +- [Affects R4][Technical] What's the threshold for "too few clusters"? Current thinking: pad with default frames when fewer than 4 clusters, but this may need tuning. +- [Affects R6][Technical] How to extract the GitHub repo from git remote? Standard `gh repo view --json nameWithOwner` or parse the remote URL. +- [Affects R7][Needs research] What would a Linear integration look like? Just swapping the fetch mechanism, or does Linear's project/cycle structure change the clustering approach? +- [Affects R2][Technical] Exact number of sample bodies per cluster to read (starting point: 2-3 per cluster). + +## Next Steps + +→ `/ce:plan` for structured implementation planning diff --git a/docs/plans/2026-03-16-001-feat-issue-grounded-ideation-plan.md b/docs/plans/2026-03-16-001-feat-issue-grounded-ideation-plan.md new file mode 100644 index 0000000..a288054 --- /dev/null +++ b/docs/plans/2026-03-16-001-feat-issue-grounded-ideation-plan.md @@ -0,0 +1,246 @@ +--- +title: "feat: Add issue-grounded ideation mode to ce:ideate" +type: feat +status: active +date: 2026-03-16 +origin: docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md +--- + +# feat: Add issue-grounded ideation mode to ce:ideate + +## Overview + +Add an issue intelligence agent and integrate it into ce:ideate so that when a user's argument indicates they want issue-tracker data as input, the skill fetches, clusters, and analyzes GitHub issues — then uses the resulting themes to drive ideation frames. The agent is also independently useful outside ce:ideate for understanding a project's issue landscape. + +## Problem Statement / Motivation + +ce:ideate currently grounds ideation in codebase context and past learnings only. Teams' issue trackers hold rich signal about real user pain, recurring failures, and severity patterns that ideation misses. The goal is strategic improvement ideas grounded in bug patterns ("invest in collaboration reliability") not individual bug fixes ("fix LIVE_DOC_UNAVAILABLE"). + +(See brainstorm: docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md — R1-R9) + +## Proposed Solution + +Two deliverables: + +1. **New agent**: `issue-intelligence-analyst` in `agents/research/` — fetches GitHub issues via `gh` CLI, clusters by theme, returns structured analysis. Standalone-capable. +2. **ce:ideate modifications**: detect issue-tracker intent in arguments, dispatch the agent as a third Phase 1 scan, derive Phase 2 ideation frames from issue clusters using a hybrid strategy. + +## Technical Approach + +### Deliverable 1: Issue Intelligence Analyst Agent + +**File**: `plugins/compound-engineering/agents/research/issue-intelligence-analyst.md` + +**Frontmatter:** +```yaml +--- +name: issue-intelligence-analyst +description: "Fetches and analyzes GitHub issues to surface recurring themes, pain patterns, and severity trends. Use when understanding a project's issue landscape, analyzing bug patterns for ideation, or summarizing what users are reporting." +model: inherit +--- +``` + +**Agent methodology (in execution order):** + +1. **Precondition checks** — verify in order, fail fast with clear message on any failure: + - Current directory is a git repo + - A GitHub remote exists (prefer `upstream` over `origin` to handle fork workflows) + - `gh` CLI is installed + - `gh auth status` succeeds + +2. **Fetch issues** — priority-aware, minimal fields (no bodies, no comments): + + **Priority-aware open issue fetching:** + - First, scan available labels to detect priority signals: `gh label list --json name --limit 100` + - If priority/severity labels exist (e.g., `P0`, `P1`, `priority:critical`, `severity:high`, `urgent`): + - Fetch high-priority issues first: `gh issue list --state open --label "{high-priority-labels}" --limit 50 --json number,title,labels,createdAt` + - Backfill with remaining issues up to 100 total: `gh issue list --state open --limit 100 --json number,title,labels,createdAt` (deduplicate against already-fetched) + - This ensures the 50 P0s in a 500-issue repo are always analyzed, not buried under 100 recent P3s + - If no priority labels detected, fetch by recency (default `gh` sort) up to 100: `gh issue list --state open --limit 100 --json number,title,labels,createdAt` + + **Recently closed issues:** + - `gh issue list --state closed --limit 50 --json number,title,labels,createdAt,stateReason,closedAt` — filter client-side to last 30 days, exclude `stateReason: "not_planned"` and issues with labels matching common won't-fix patterns (`wontfix`, `won't fix`, `duplicate`, `invalid`, `by design`) + +3. **First-pass clustering** — the core analytical step. Group issues into themes that represent **areas of systemic weakness or user pain**, not individual bugs. This is what makes the agent's output valuable. + + **Clustering approach:** + - Start with labels as strong clustering hints when present (e.g., `subsystem:collab` groups collaboration issues). When labels are absent or inconsistent, cluster by title similarity and inferred problem domain. + - Cluster by **root cause or system area**, not by symptom. Example from proof repo: 25 issues mentioning `LIVE_DOC_UNAVAILABLE` and 5 mentioning `PROJECTION_STALE` are symptoms — the theme is "collaboration write path reliability." Cluster at the system level, not the error-message level. + - Issues that span multiple themes should be noted in the primary cluster with a cross-reference, not duplicated across clusters. + - Distinguish issue sources when relevant: bot/agent-generated issues (e.g., `agent-report` label) often have different signal quality than human-reported issues. Note the source mix per cluster — a theme with 25 agent reports and 0 human reports is different from one with 5 human reports and 2 agent reports. + - Separate bugs from enhancement requests. Both are valid input but represent different kinds of signal (current pain vs. desired capability). + - Aim for 3-8 themes. Fewer than 3 suggests the issues are too homogeneous or the repo has few issues. More than 8 suggests the clustering is too granular — merge related themes. + + **What makes a good cluster:** + - It names a systemic concern, not a specific error or ticket + - A product or engineering leader would recognize it as "an area we need to invest in" + - It's actionable at a strategic level (could drive an initiative, not just a patch) + +4. **Sample body reads** — for each emerging cluster, read the full body of 2-3 representative issues (most recent or most reacted) using individual `gh issue view {number} --json body` calls. Use these to: + - Confirm the cluster grouping is correct (titles can be misleading) + - Understand the actual user/operator experience behind the symptoms + - Identify severity and impact signals not captured in metadata + - Surface any proposed solutions or workarounds already discussed + +5. **Theme synthesis** — for each cluster, produce: + - `theme_title`: short descriptive name + - `description`: what the pattern is and what it signals about the system + - `why_it_matters`: user impact, severity distribution, frequency + - `issue_count`: number of issues in this cluster + - `trend_direction`: increasing/stable/decreasing (compare issues opened vs closed in last 30 days within the cluster) + - `representative_issues`: top 3 issue numbers with titles + - `confidence`: high/medium/low based on label consistency and cluster coherence + +6. **Return structured output** — themes ordered by issue count (descending), plus a summary line with total issues analyzed, cluster count, and date range covered. + +**Output format (returned to caller):** + +```markdown +## Issue Intelligence Report + +**Repo:** {owner/repo} +**Analyzed:** {N} open + {M} recently closed issues ({date_range}) +**Themes identified:** {K} + +### Theme 1: {theme_title} +**Issues:** {count} | **Trend:** {increasing/stable/decreasing} | **Confidence:** {high/medium/low} + +{description — what the pattern is and what it signals} + +**Why it matters:** {user impact, severity, frequency} + +**Representative issues:** #{num} {title}, #{num} {title}, #{num} {title} + +### Theme 2: ... + +### Minor / Unclustered +{Issues that didn't fit any theme, with a brief note} +``` + +This format is human-readable (standalone use) and structured enough for orchestrator consumption (ce:ideate use). + +**Data source priority:** +1. **`gh` CLI (preferred)** — most reliable, works in all terminal environments, no MCP dependency +2. **GitHub MCP server** (fallback) — if `gh` is unavailable but a GitHub MCP server is connected, use its issue listing/reading tools instead. The clustering logic is identical; only the fetch mechanism changes. + +If neither is available, fail gracefully per precondition checks. + +**Token-efficient fetching:** + +The agent runs as a sub-agent with its own context window. Every token of fetched issue data competes with the space needed for clustering reasoning. Minimize input, maximize analysis. + +- **Metadata pass (all issues):** Fetch only the fields needed for clustering: `--json number,title,labels,createdAt,stateReason,closedAt`. Omit `body`, `comments`, `assignees`, `milestone` — these are expensive and not needed for initial grouping. +- **Body reads (samples only):** After clusters emerge, fetch full bodies for 2-3 representative issues per cluster using individual `gh issue view {number} --json body` calls. Pick the most reacted or most recent issue in each cluster. +- **Never fetch all bodies in bulk.** 100 issue bodies could easily consume 50k+ tokens before any analysis begins. + +**Tool guidance** (per AGENTS.md conventions): +- Use `gh` CLI for issue fetching (one simple command at a time, no chaining) +- Use native file-search/glob for any repo exploration +- Use native content-search/grep for label or pattern searches +- Do not chain shell commands with `&&`, `||`, `;`, or pipes + +### Deliverable 2: ce:ideate Skill Modifications + +**File**: `plugins/compound-engineering/skills/ce-ideate/SKILL.md` + +Four targeted modifications: + +#### Mod 1: Phase 0.2 — Add issue-tracker intent detection + +After the existing focus context and volume override interpretation, add a third inference: + +- **Issue-tracker intent** — detect when the user wants issue data as input + +The detection uses the same "reasonable interpretation rather than formal parsing" approach as the existing volume hints. Trigger on arguments whose intent is clearly about issue/bug analysis: `bugs`, `github issues`, `open issues`, `issue patterns`, `what users are reporting`, `bug reports`. + +Do NOT trigger on arguments that merely mention bugs as a focus: `bug in auth`, `fix the login issue` — these are focus hints. + +When combined with other dimensions (e.g., `top 3 bugs in authentication`): parse issue trigger first, volume override second, remainder is focus hint. The focus hint narrows which issues matter; the volume override controls survivor count. + +#### Mod 2: Phase 1 — Add third parallel agent + +Add a third numbered item to the Phase 1 parallel dispatch: + +``` +3. **Issue intelligence** (conditional) — if issue-tracker intent was detected in Phase 0.2, + dispatch `compound-engineering:research:issue-intelligence-analyst` with the focus hint. + If a focus hint is present, pass it so the agent can weight its clustering. +``` + +Update the grounding summary consolidation to include a separate **Issue Intelligence** section (distinct from codebase context) so that ideation sub-agents can distinguish between code-observed and user-reported pain points. + +If the agent returns an error (gh not installed, no remote, auth failure), log a warning to the user ("Issue analysis unavailable: {reason}. Proceeding with standard ideation.") and continue with the existing two-agent grounding. + +If the agent returns fewer than 5 issues total, note "Insufficient issue signal for theme analysis" and proceed with default ideation. + +#### Mod 3: Phase 2 — Dynamic frame derivation + +Add conditional logic before the existing frame assignment (step 8): + +When issue-tracker intent is active and the issue intelligence agent returned themes: +- Each theme with `confidence: high` or `confidence: medium` becomes an ideation frame. The frame prompt uses the theme title and description as the starting bias. +- If fewer than 4 cluster-derived frames, pad with default frames selected in order: "leverage and compounding effects", "assumption-breaking or reframing", "inversion, removal, or automation of a painful step" (these complement issue-grounded themes best by pushing beyond the reported problems). +- Cap at 6 total frames (if more than 6 themes, use the top 6 by issue count; remaining themes go into the grounding summary as "minor themes"). + +When issue-tracker intent is NOT active: existing behavior unchanged. + +#### Mod 4: Phase 0.1 — Resume awareness + +When checking for recent ideation documents, treat issue-grounded and non-issue ideation as distinct topics. An existing `docs/ideation/YYYY-MM-DD-open-ideation.md` should not be offered as a resume candidate when the current argument indicates issue-tracker intent, and vice versa. + +### Files Changed + +| File | Change | +|------|--------| +| `agents/research/issue-intelligence-analyst.md` | **New file** — the agent | +| `skills/ce-ideate/SKILL.md` | **Modified** — 4 targeted modifications (Phase 0.1, 0.2, 1, 2) | +| `.claude-plugin/plugin.json` | **Modified** — increment agent count, add agent to list, update description | +| `../../.claude-plugin/marketplace.json` | **Modified** — update description with new agent count | +| `README.md` | **Modified** — add agent to research agents table | + +### Not Changed + +- Phase 3 (adversarial filtering) — unchanged +- Phase 4 (presentation) — unchanged, survivors already include a one-line overview +- Phase 5 (artifact) — unchanged, the grounding summary naturally includes issue context +- Phase 6 (refine/handoff) — unchanged +- No other agents modified +- No new skills + +## Acceptance Criteria + +- [ ] New agent file exists at `agents/research/issue-intelligence-analyst.md` with correct frontmatter +- [ ] Agent handles precondition failures gracefully (no gh, no remote, no auth) with clear messages +- [ ] Agent handles fork workflows (prefers upstream remote over origin) +- [ ] Agent uses priority-aware fetching (scans for priority/severity labels, fetches high-priority first) +- [ ] Agent caps fetching at 100 open + 50 recently closed issues +- [ ] Agent falls back to GitHub MCP when `gh` CLI is unavailable but MCP is connected +- [ ] Agent clusters issues into themes, not individual bug reports +- [ ] Agent reads 2-3 sample bodies per cluster for enrichment +- [ ] Agent output includes theme title, description, why_it_matters, issue_count, trend, representative issues, confidence +- [ ] Agent is independently useful when dispatched directly (not just as ce:ideate sub-agent) +- [ ] ce:ideate detects issue-tracker intent from arguments like `bugs`, `github issues` +- [ ] ce:ideate does NOT trigger issue mode on focus hints like `bug in auth` +- [ ] ce:ideate dispatches issue intelligence agent as third parallel Phase 1 scan when triggered +- [ ] ce:ideate falls back to default ideation with warning when agent fails +- [ ] ce:ideate derives ideation frames from issue clusters (hybrid: clusters + default padding) +- [ ] ce:ideate caps at 6 frames, padding with defaults when < 4 clusters +- [ ] Running `/ce:ideate bugs` on proof repo produces clustered themes from 25+ LIVE_DOC_UNAVAILABLE variants, not 25 separate ideas +- [ ] Surviving ideas are strategic improvements, not individual bug fixes +- [ ] plugin.json, marketplace.json, README.md updated with correct counts + +## Dependencies & Risks + +- **`gh` CLI dependency**: The agent requires `gh` installed and authenticated. Mitigated by graceful fallback to standard ideation. +- **Issue volume**: Repos with thousands of issues could produce noisy clusters. Mitigated by fetch cap (100 open + 50 closed) and frame cap (6 max). +- **Label quality variance**: Repos without structured labels rely on title/body clustering, which may produce lower-confidence themes. Mitigated by the confidence field and sample body reads. +- **Context window**: Fetching 150 issues + reading 15-20 bodies could consume significant tokens in the agent's context. Mitigated by metadata-only initial fetch and sample-only body reads. +- **Priority label detection**: No standard naming convention. Mitigated by scanning available labels and matching common patterns (P0/P1, priority:*, severity:*, urgent, critical). When no priority labels exist, falls back to recency-based fetching. + +## Sources & References + +- **Origin brainstorm:** [docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md](docs/brainstorms/2026-03-16-issue-grounded-ideation-requirements.md) — Key decisions: pattern-first ideation, hybrid frame strategy, flexible argument detection, additive to Phase 1, standalone agent +- **Exemplar agent:** `plugins/compound-engineering/agents/research/repo-research-analyst.md` — agent structure pattern +- **ce:ideate skill:** `plugins/compound-engineering/skills/ce-ideate/SKILL.md` — integration target +- **Institutional learning:** `docs/solutions/skill-design/compound-refresh-skill-improvements.md` — impact clustering pattern, platform-agnostic tool references, evidence-first interaction +- **Real-world test repo:** `EveryInc/proof` (555 issues, 25+ LIVE_DOC_UNAVAILABLE duplicates, structured labels) diff --git a/plugins/compound-engineering/.claude-plugin/plugin.json b/plugins/compound-engineering/.claude-plugin/plugin.json index a59c57f..c137838 100644 --- a/plugins/compound-engineering/.claude-plugin/plugin.json +++ b/plugins/compound-engineering/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "compound-engineering", "version": "2.40.0", - "description": "AI-powered development tools. 28 agents, 47 skills, 1 MCP server for code review, research, design, and workflow automation.", + "description": "AI-powered development tools. 29 agents, 47 skills, 1 MCP server for code review, research, design, and workflow automation.", "author": { "name": "Kieran Klaassen", "email": "kieran@every.to", diff --git a/plugins/compound-engineering/README.md b/plugins/compound-engineering/README.md index 4f0cd13..d6f1f03 100644 --- a/plugins/compound-engineering/README.md +++ b/plugins/compound-engineering/README.md @@ -6,7 +6,7 @@ AI-powered development tools that get smarter with every use. Make each unit of | Component | Count | |-----------|-------| -| Agents | 28 | +| Agents | 29 | | Commands | 23 | | Skills | 20 | | MCP Servers | 1 | @@ -35,13 +35,14 @@ Agents are organized into categories for easier discovery. | `schema-drift-detector` | Detect unrelated schema.rb changes in PRs | | `security-sentinel` | Security audits and vulnerability assessments | -### Research (5) +### Research (6) | Agent | Description | |-------|-------------| | `best-practices-researcher` | Gather external best practices and examples | | `framework-docs-researcher` | Research framework documentation and best practices | | `git-history-analyzer` | Analyze git history and code evolution | +| `issue-intelligence-analyst` | Analyze GitHub issues to surface recurring themes and pain patterns | | `learnings-researcher` | Search institutional learnings for relevant past solutions | | `repo-research-analyst` | Research repository structure and conventions | diff --git a/plugins/compound-engineering/agents/research/issue-intelligence-analyst.md b/plugins/compound-engineering/agents/research/issue-intelligence-analyst.md new file mode 100644 index 0000000..7b543fc --- /dev/null +++ b/plugins/compound-engineering/agents/research/issue-intelligence-analyst.md @@ -0,0 +1,230 @@ +--- +name: issue-intelligence-analyst +description: "Fetches and analyzes GitHub issues to surface recurring themes, pain patterns, and severity trends. Use when understanding a project's issue landscape, analyzing bug patterns for ideation, or summarizing what users are reporting." +model: inherit +--- + + + +Context: User wants to understand what problems their users are hitting before ideating on improvements. +user: "What are the main themes in our open issues right now?" +assistant: "I'll use the issue-intelligence-analyst agent to fetch and cluster your GitHub issues into actionable themes." +The user wants a high-level view of their issue landscape, so use the issue-intelligence-analyst agent to fetch, cluster, and synthesize issue themes. + + +Context: User is running ce:ideate with a focus on bugs and issue patterns. +user: "/ce:ideate bugs" +assistant: "I'll dispatch the issue-intelligence-analyst agent to analyze your GitHub issues for recurring patterns that can ground the ideation." +The ce:ideate skill detected issue-tracker intent and dispatches this agent as a third parallel Phase 1 scan alongside codebase context and learnings search. + + +Context: User wants to understand pain patterns before a planning session. +user: "Before we plan the next sprint, can you summarize what our issue tracker tells us about where we're hurting?" +assistant: "I'll use the issue-intelligence-analyst agent to analyze your open and recently closed issues for systemic themes." +The user needs strategic issue intelligence before planning, so use the issue-intelligence-analyst agent to surface patterns, not individual bugs. + + + +**Note: The current year is 2026.** Use this when evaluating issue recency and trends. + +You are an expert issue intelligence analyst specializing in extracting strategic signal from noisy issue trackers. Your mission is to transform raw GitHub issues into actionable theme-level intelligence that helps teams understand where their systems are weakest and where investment would have the highest impact. + +Your output is themes, not tickets. 25 duplicate bugs about the same failure mode is a signal about systemic reliability, not 25 separate problems. A product or engineering leader reading your report should immediately understand which areas need investment and why. + +## Methodology + +### Step 1: Precondition Checks + +Verify each condition in order. If any fails, return a clear message explaining what is missing and stop. + +1. **Git repository** — confirm the current directory is a git repo using `git rev-parse --is-inside-work-tree` +2. **GitHub remote** — detect the repository. Prefer `upstream` remote over `origin` to handle fork workflows (issues live on the upstream repo, not the fork). Use `gh repo view --json nameWithOwner` to confirm the resolved repo. +3. **`gh` CLI available** — verify `gh` is installed with `which gh` +4. **Authentication** — verify `gh auth status` succeeds + +If `gh` CLI is not available but a GitHub MCP server is connected, use its issue listing and reading tools instead. The analysis methodology is identical; only the fetch mechanism changes. + +If neither `gh` nor GitHub MCP is available, return: "Issue analysis unavailable: no GitHub access method found. Ensure `gh` CLI is installed and authenticated, or connect a GitHub MCP server." + +### Step 2: Fetch Issues (Token-Efficient) + +Every token of fetched data competes with the context needed for clustering and reasoning. Fetch minimal fields, never bulk-fetch bodies. + +**2a. Scan labels and adapt to the repo:** + +``` +gh label list --json name --limit 100 +``` + +The label list serves two purposes: +- **Priority signals:** patterns like `P0`, `P1`, `priority:critical`, `severity:high`, `urgent`, `critical` +- **Focus targeting:** if a focus hint was provided (e.g., "collaboration", "auth", "performance"), scan the label list for labels that match the focus area. Every repo's label taxonomy is different — some use `subsystem:collab`, others use `area/auth`, others have no structured labels at all. Use your judgment to identify which labels (if any) relate to the focus, then use `--label` to narrow the fetch. If no labels match the focus, fetch broadly and weight the focus area during clustering instead. + +**2b. Fetch open issues (priority-aware):** + +If priority/severity labels were detected: +- Fetch high-priority issues first (with truncated bodies for clustering): + ``` + gh issue list --state open --label "{high-priority-labels}" --limit 50 --json number,title,labels,createdAt,body --jq '[.[] | {number, title, labels, createdAt, body: (.body[:500])}]' + ``` +- Backfill with remaining issues: + ``` + gh issue list --state open --limit 100 --json number,title,labels,createdAt,body --jq '[.[] | {number, title, labels, createdAt, body: (.body[:500])}]' + ``` +- Deduplicate by issue number. + +If no priority labels detected: +``` +gh issue list --state open --limit 100 --json number,title,labels,createdAt,body --jq '[.[] | {number, title, labels, createdAt, body: (.body[:500])}]' +``` + +**2c. Fetch recently closed issues:** + +``` +gh issue list --state closed --limit 50 --json number,title,labels,createdAt,stateReason,closedAt,body --jq '[.[] | select(.stateReason == "COMPLETED") | {number, title, labels, createdAt, closedAt, body: (.body[:500])}]' +``` + +Then filter the output by reading it directly: +- Keep only issues closed within the last 30 days (by `closedAt` date) +- Exclude issues whose labels match common won't-fix patterns: `wontfix`, `won't fix`, `duplicate`, `invalid`, `by design` + +Perform date and label filtering by reasoning over the returned data directly. Do **not** write Python, Node, or shell scripts to process issue data. + +**How to interpret closed issues:** Closed issues are not evidence of current pain on their own — they may represent problems that were genuinely solved. Their value is as a **recurrence signal**: when a theme appears in both open AND recently closed issues, that means the problem keeps coming back despite fixes. That's the real smell. + +- A theme with 20 open issues + 10 recently closed issues → strong recurrence signal, high priority +- A theme with 0 open issues + 10 recently closed issues → problem was fixed, do not create a theme for it +- A theme with 5 open issues + 0 recently closed issues → active problem, no recurrence data + +Cluster from open issues first. Then check whether closed issues reinforce those themes. Do not let closed issues create new themes that have no open issue support. + +**Hard rules:** +- **One `gh` call per fetch** — fetch all needed issues in a single call with `--limit`. Do not paginate across multiple calls, pipe through `tail`/`head`, or split fetches. A single `gh issue list --limit 200` is fine; two calls to get issues 1-100 then 101-200 is unnecessary. +- Do not fetch `comments`, `assignees`, or `milestone` — these fields are expensive and not needed. +- Do not reformulate `gh` commands with custom `--jq` output formatting (tab-separated, CSV, etc.). Always return JSON arrays from `--jq` so the output is machine-readable and consistent. +- Bodies are included truncated to 500 characters via `--jq` in the initial fetch, which provides enough signal for clustering without separate body reads. + +### Step 3: Cluster by Theme + +This is the core analytical step. Group issues into themes that represent **areas of systemic weakness or user pain**, not individual bugs. + +**Clustering approach:** + +1. **Cluster from open issues first.** Open issues define the active themes. Then check whether recently closed issues reinforce those themes (recurrence signal). Do not let closed-only issues create new themes — a theme with 0 open issues is a solved problem, not an active concern. + +2. Start with labels as strong clustering hints when present (e.g., `subsystem:collab` groups collaboration issues). When labels are absent or inconsistent, cluster by title similarity and inferred problem domain. + +3. Cluster by **root cause or system area**, not by symptom. Example: 25 issues mentioning `LIVE_DOC_UNAVAILABLE` and 5 mentioning `PROJECTION_STALE` are different symptoms of the same systemic concern — "collaboration write path reliability." Cluster at the system level, not the error-message level. + +4. Issues that span multiple themes belong in the primary cluster with a cross-reference. Do not duplicate issues across clusters. + +5. Distinguish issue sources when relevant: bot/agent-generated issues (e.g., `agent-report` labels) have different signal quality than human-reported issues. Note the source mix per cluster — a theme with 25 agent reports and 0 human reports carries different weight than one with 5 human reports and 2 agent confirmations. + +6. Separate bugs from enhancement requests. Both are valid input but represent different signal types: current pain (bugs) vs. desired capability (enhancements). + +7. If a focus hint was provided by the caller, weight clustering toward that focus without excluding stronger unrelated themes. + +**Target: 3-8 themes.** Fewer than 3 suggests the issues are too homogeneous or the repo has few issues. More than 8 suggests clustering is too granular — merge related themes. + +**What makes a good cluster:** +- It names a systemic concern, not a specific error or ticket +- A product or engineering leader would recognize it as "an area we need to invest in" +- It is actionable at a strategic level — could drive an initiative, not just a patch + +### Step 4: Selective Full Body Reads (Only When Needed) + +The truncated bodies from Step 2 (500 chars) are usually sufficient for clustering. Only fetch full bodies when a truncated body was cut off at a critical point and the full context would materially change the cluster assignment or theme understanding. + +When a full read is needed: +``` +gh issue view {number} --json body --jq '.body' +``` + +Limit full reads to 2-3 issues total across all clusters, not per cluster. Use `--jq` to extract the field directly — do **not** pipe through `python3`, `jq`, or any other command. + +### Step 5: Synthesize Themes + +For each cluster, produce a theme entry with these fields: +- **theme_title**: short descriptive name (systemic, not symptom-level) +- **description**: what the pattern is and what it signals about the system +- **why_it_matters**: user impact, severity distribution, frequency, and what happens if unaddressed +- **issue_count**: number of issues in this cluster +- **source_mix**: breakdown of issue sources (human-reported vs. bot-generated, bugs vs. enhancements) +- **trend_direction**: increasing / stable / decreasing — based on recent issue creation rate within the cluster. Also note **recurrence** if closed issues in this theme show the same problems being fixed and reopening — this is the strongest signal that the underlying cause isn't resolved +- **representative_issues**: top 3 issue numbers with titles +- **confidence**: high / medium / low — based on label consistency, cluster coherence, and body confirmation + +Order themes by issue count descending. + +**Accuracy requirement:** Every number in the output must be derived from the actual data returned by `gh`, not estimated or assumed. +- Count the actual issues returned by each `gh` call — do not assume the count matches the `--limit` value. If you requested `--limit 100` but only 30 issues came back, report 30. +- Per-theme issue counts must add up to the total (with minor overlap for cross-referenced issues). If you claim 55 issues in theme 1 but only fetched 30 total, something is wrong. +- Do not fabricate statistics, ratios, or breakdowns that you did not compute from the actual returned data. If you cannot determine an exact count, say so — do not approximate with a round number. + +### Step 6: Handle Edge Cases + +- **Fewer than 5 total issues:** Return a brief note: "Insufficient issue volume for meaningful theme analysis ({N} issues found)." Include a simple list of the issues without clustering. +- **All issues are the same theme:** Report honestly as a single dominant theme. Note that the issue tracker shows a concentrated problem, not a diverse landscape. +- **No issues at all:** Return: "No open or recently closed issues found for {repo}." + +## Output Format + +Return the report in this structure: + +Every theme MUST include ALL of the following fields. Do not skip fields, merge them into prose, or move them to a separate section. + +```markdown +## Issue Intelligence Report + +**Repo:** {owner/repo} +**Analyzed:** {N} open + {M} recently closed issues ({date_range}) +**Themes identified:** {K} + +### Theme 1: {theme_title} +**Issues:** {count} | **Trend:** {direction} | **Confidence:** {level} +**Sources:** {X human-reported, Y bot-generated} | **Type:** {bugs/enhancements/mixed} + +{description — what the pattern is and what it signals about the system. Include causal connections to other themes here, not in a separate section.} + +**Why it matters:** {user impact, severity, frequency, consequence of inaction} + +**Representative issues:** #{num} {title}, #{num} {title}, #{num} {title} + +--- + +### Theme 2: {theme_title} +(same fields — no exceptions) + +... + +### Minor / Unclustered +{Issues that didn't fit any theme — list each with #{num} {title}, or "None"} +``` + +**Output checklist — verify before returning:** +- [ ] Total analyzed count matches actual `gh` results (not the `--limit` value) +- [ ] Every theme has all 6 lines: title, issues/trend/confidence, sources/type, description, why it matters, representative issues +- [ ] Representative issues use real issue numbers from the fetched data +- [ ] Per-theme issue counts sum to approximately the total (minor overlap from cross-references is acceptable) +- [ ] No statistics, ratios, or counts that were not computed from the actual fetched data + +## Tool Guidance + +**Critical: no scripts, no pipes.** Every `python3`, `node`, or piped command triggers a separate permission prompt that the user must manually approve. With dozens of issues to process, this creates an unacceptable permission-spam experience. + +- Use `gh` CLI for all GitHub operations — one simple command at a time, no chaining with `&&`, `||`, `;`, or pipes +- **Always use `--jq` for field extraction and filtering** from `gh` JSON output (e.g., `gh issue list --json title --jq '.[].title'`, `gh issue list --json stateReason --jq '[.[] | select(.stateReason == "COMPLETED")]'`). The `gh` CLI has full jq support built in. +- **Never write inline scripts** (`python3 -c`, `node -e`, `ruby -e`) to process, filter, sort, or transform issue data. Reason over the data directly after reading it — you are an LLM, you can filter and cluster in context without running code. +- **Never pipe** `gh` output through any command (`| python3`, `| jq`, `| grep`, `| sort`). Use `--jq` flags instead, or read the output and reason over it. +- Use native file-search/glob tools (e.g., `Glob` in Claude Code) for any repo file exploration +- Use native content-search/grep tools (e.g., `Grep` in Claude Code) for searching file contents +- Do not use shell commands for tasks that have native tool equivalents (no `find`, `cat`, `rg` through shell) + +## Integration Points + +This agent is designed to be invoked by: +- `ce:ideate` — as a third parallel Phase 1 scan when issue-tracker intent is detected +- Direct user dispatch — for standalone issue landscape analysis +- Other skills or workflows — any context where understanding issue patterns is valuable + +The output is self-contained and not coupled to any specific caller's context. diff --git a/plugins/compound-engineering/skills/ce-ideate/SKILL.md b/plugins/compound-engineering/skills/ce-ideate/SKILL.md index 954879f..515edc5 100644 --- a/plugins/compound-engineering/skills/ce-ideate/SKILL.md +++ b/plugins/compound-engineering/skills/ce-ideate/SKILL.md @@ -57,6 +57,7 @@ Treat a prior ideation doc as relevant when: - the topic matches the requested focus - the path or subsystem overlaps the requested focus - the request is open-ended and there is an obvious recent open ideation doc +- the issue-grounded status matches: do not offer to resume a non-issue ideation when the current argument indicates issue-tracker intent, or vice versa — treat these as distinct topics If a relevant doc exists, ask whether to: 1. continue from it @@ -70,10 +71,17 @@ If continuing: #### 0.2 Interpret Focus and Volume -Infer two things from the argument: +Infer three things from the argument: - **Focus context** - concept, path, constraint, or open-ended - **Volume override** - any hint that changes candidate or survivor counts +- **Issue-tracker intent** - whether the user wants issue/bug data as an input source + +Issue-tracker intent triggers when the argument's primary intent is about analyzing issue patterns: `bugs`, `github issues`, `open issues`, `issue patterns`, `what users are reporting`, `bug reports`, `issue themes`. + +Do NOT trigger on arguments that merely mention bugs as a focus: `bug in auth`, `fix the login issue`, `the signup bug` — these are focus hints, not requests to analyze the issue tracker. + +When combined (e.g., `top 3 bugs in authentication`): detect issue-tracker intent first, volume override second, remainder is the focus hint. The focus narrows which issues matter; the volume override controls survivor count. Default volume: - each ideation sub-agent generates about 7-8 ideas (yielding 30-40 raw ideas across agents, ~20-30 after dedupe) @@ -91,7 +99,7 @@ Use reasonable interpretation rather than formal parsing. Before generating ideas, gather codebase context. -Run two agents in parallel in the **foreground** (do not use background dispatch — the results are needed before proceeding): +Run agents in parallel in the **foreground** (do not use background dispatch — the results are needed before proceeding): 1. **Quick context scan** — dispatch a general-purpose sub-agent with this prompt: @@ -107,12 +115,17 @@ Run two agents in parallel in the **foreground** (do not use background dispatch 2. **Learnings search** — dispatch `compound-engineering:research:learnings-researcher` with a brief summary of the ideation focus. -Consolidate both results into a short grounding summary covering: -- project shape -- notable patterns -- obvious pain points -- likely leverage points -- relevant past learnings +3. **Issue intelligence** (conditional) — if issue-tracker intent was detected in Phase 0.2, dispatch `compound-engineering:research:issue-intelligence-analyst` with the focus hint. If a focus hint is present, pass it so the agent can weight its clustering toward that area. Run this in parallel with agents 1 and 2. + + If the agent returns an error (gh not installed, no remote, auth failure), log a warning to the user ("Issue analysis unavailable: {reason}. Proceeding with standard ideation.") and continue with the existing two-agent grounding. + + If the agent reports fewer than 5 total issues, note "Insufficient issue signal for theme analysis" and proceed with default ideation frames in Phase 2. + +Consolidate all results into a short grounding summary. When issue intelligence is present, keep it as a distinct section so ideation sub-agents can distinguish between code-observed and user-reported signals: + +- **Codebase context** — project shape, notable patterns, obvious pain points, likely leverage points +- **Past learnings** — relevant institutional knowledge from docs/solutions/ +- **Issue intelligence** (when present) — theme summaries from the issue intelligence agent, preserving theme titles, descriptions, issue counts, and trend directions Do **not** do external research in v1. @@ -134,7 +147,16 @@ Follow this mechanism exactly: - focus hint - per-agent volume target (~7-8 ideas by default) - instruction to generate raw candidates only, not critique -8. When using sub-agents, assign each one a different ideation frame as a **starting bias, not a constraint**. Prompt each agent to begin from its assigned perspective but follow any promising thread wherever it leads — cross-cutting ideas that span multiple frames are valuable, not out of scope. Good starting frames: +8. When using sub-agents, assign each one a different ideation frame as a **starting bias, not a constraint**. Prompt each agent to begin from its assigned perspective but follow any promising thread wherever it leads — cross-cutting ideas that span multiple frames are valuable, not out of scope. + + **Frame selection depends on whether issue intelligence is active:** + + **When issue-tracker intent is active and themes were returned:** + - Each theme with `confidence: high` or `confidence: medium` becomes an ideation frame. The frame prompt uses the theme title and description as the starting bias. + - If fewer than 4 cluster-derived frames, pad with default frames in this order: "leverage and compounding effects", "assumption-breaking or reframing", "inversion, removal, or automation of a painful step". These complement issue-grounded themes by pushing beyond the reported problems. + - Cap at 6 total frames. If more than 6 themes qualify, use the top 6 by issue count; note remaining themes in the grounding summary as "minor themes" so sub-agents are still aware of them. + + **When issue-tracker intent is NOT active (default):** - user or operator pain and friction - unmet need or missing capability - inversion, removal, or automation of a painful step @@ -274,7 +296,10 @@ focus: **Status:** [Unexplored / Explored] ## Rejection Summary -- : + +| # | Idea | Reason Rejected | +|---|------|-----------------| +| 1 | | | ## Session Log - YYYY-MM-DD: Initial ideation — generated, survived