Skip to content

refactor: use org-wide reusable feature-ideation workflow#68

Merged
don-petry merged 1 commit intomainfrom
refactor/feature-ideation-use-reusable
Apr 7, 2026
Merged

refactor: use org-wide reusable feature-ideation workflow#68
don-petry merged 1 commit intomainfrom
refactor/feature-ideation-use-reusable

Conversation

@don-petry
Copy link
Copy Markdown
Contributor

Summary

Replaces TalkTerm's 619-line inlined feature-ideation workflow with a 66-line caller stub that delegates to the org-wide reusable workflow at petry-projects/.github. The single source of truth for the BMAD ideation pipeline now lives in one place — tuning the prompt, model, or any of the four critical gotchas there propagates to TalkTerm (and every future BMAD-enabled repo) on next scheduled run.

Companion org PR: petry-projects/.github#81 (already merged)

What stays TalkTerm-specific

Only the project_context input — a paragraph describing TalkTerm, its target users, its competitive landscape, and the trends Mary should research. Everything else (the 5-phase pipeline, Opus 4.6 selection, github_token override, prompt structure, Discussion body template) is centralized.

Net change

1 file changed, 36 insertions(+), 591 deletions(-)

Test plan

🤖 Generated with Claude Code

…stub

Calls the org-wide reusable workflow at
petry-projects/.github/.github/workflows/feature-ideation-reusable.yml@main
which is now the single source of truth for the BMAD ideation pipeline.

The only TalkTerm-specific content is the project_context paragraph,
which describes the product, target users, competitors, and trends Mary
should research. Everything else — the multi-skill pipeline, model
selection, github_token override, prompt structure — lives centrally
and propagates here on next scheduled run.

Net change: 591 lines removed, 36 added (-555 net).

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copilot AI review requested due to automatic review settings April 7, 2026 02:37
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented Apr 7, 2026

Warning

Rate limit exceeded

@don-petry has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 4 minutes and 39 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 4 minutes and 39 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 60e29b8a-7ffc-4ebd-abba-8901f16d3b7c

📥 Commits

Reviewing files that changed from the base of the PR and between c6e4e1c and 4276418.

📒 Files selected for processing (1)
  • .github/workflows/feature-ideation.yml
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch refactor/feature-ideation-use-reusable

Comment @coderabbitai help to get the list of available commands and usage tips.

@sonarqubecloud
Copy link
Copy Markdown

sonarqubecloud Bot commented Apr 7, 2026

Quality Gate Failed Quality Gate failed

Failed conditions
1 Security Hotspot

See analysis details on SonarQube Cloud

@don-petry don-petry merged commit 63cdca3 into main Apr 7, 2026
16 of 17 checks passed
@don-petry don-petry deleted the refactor/feature-ideation-use-reusable branch April 7, 2026 02:39
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR refactors TalkTerm’s feature ideation GitHub Action by replacing the large inlined workflow with a thin caller that delegates execution to the org-wide reusable “feature-ideation” workflow in petry-projects/.github.

Changes:

  • Replace the in-repo multi-job BMAD ideation pipeline with a single uses: call to the org reusable workflow.
  • Keep TalkTerm-specific configuration limited to a project_context input, plus forwarding workflow_dispatch inputs.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment on lines 49 to +52
discussions: write
id-token: write
steps:
- name: Checkout repository
uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
with:
fetch-depth: 1

- name: Download signals artifact
uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4.3.0
with:
name: signals
path: ${{ runner.temp }}

- name: Run Claude Code — BMAD Analyst
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
FOCUS_AREA: ${{ inputs.focus_area || '' }}
RESEARCH_DEPTH: ${{ inputs.research_depth || 'standard' }}
ANTHROPIC_MODEL: claude-opus-4-6
uses: anthropics/claude-code-action@6e2bd52842c65e914eba5c8badd17560bd26b5de # v1.0.89
with:
claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
# Use the workflow's GITHUB_TOKEN so the job-level
# `permissions: discussions: write` grant applies — the action's
# auto-generated GitHub App token lacks discussions:write scope.
github_token: ${{ secrets.GITHUB_TOKEN }}
claude_args: "--allowedTools Bash,Read,Glob,Grep,WebSearch,WebFetch"
prompt: |
You are **Mary**, the BMAD Strategic Business Analyst, running as an automated
weekly feature research and ideation agent for the **${{ github.repository }}** project.

## Thinking & Research Directive

**Think hard.** Take your time with every phase below. Reason deeply about each
finding before moving on. Do not rush to conclusions — sit with the evidence,
look for non-obvious patterns, and challenge your own assumptions.

**Research freely — time is no constraint.** You have the full timeout budget to
produce the highest-quality analysis possible. Prefer doing one more web search
over guessing. Prefer reading one more source over assuming. Depth and rigor
matter far more than speed.

## Your Persona

You are a senior analyst with deep expertise in market research, competitive analysis,
and requirements elicitation. You approach every analysis like a treasure hunt —
thrilled by every clue, energized when patterns emerge. You structure insights with
precision while making analysis feel like discovery. You draw upon Porter's Five Forces,
SWOT analysis, and competitive intelligence methodologies naturally.

## Environment

- Repository: ${{ github.repository }}
- Workflow run: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
- Date: $(date -u +%Y-%m-%d)
- Focus area: $FOCUS_AREA (empty = open-ended exploration)
- Research depth: $RESEARCH_DEPTH

## Phase 1: Load Context

1. Read the project signals collected by the previous job:
```bash
cat ${{ runner.temp }}/signals.json
```

2. Read planning artifacts for product strategy context:
- `_bmad-output/planning-artifacts/prd.md` (product requirements)
- `_bmad-output/planning-artifacts/architecture.md` (technical architecture)
- `_bmad-output/planning-artifacts/ux-design-specification.md` (UX direction)
- `_bmad-output/planning-artifacts/epics.md` (planned work)

3. Read the project README and any recent changelog or release notes.

4. Scan the codebase for extensibility points and underutilized capabilities:
- Look at `src/shared/types/ports/` for interfaces that suggest planned extensions
- Check `src/main/agent/` for backend abstraction points
- Check `src/renderer/speech/` for voice pipeline capabilities
- Look at `src/renderer/components/` for UI patterns that could be extended

5. **Read existing Ideas discussions from signals.** These are ideas already being
tracked. You will update them if you have new findings, or leave them alone.

## Phase 2: Market Research Skill (Iterative Evidence Gathering)

**Adopt the "Market Research" mindset.** Your sole job in this phase is to gather
hard evidence — not to generate ideas yet. Be a detective, not a brainstormer.

Research the competitive landscape and emerging trends in the project's domain.
TalkTerm is a desktop AI agent interface with voice-enabled animated avatars —
focus your research on:

### Competitive Landscape
- What are other AI desktop agent tools shipping? (Cursor, Windsurf, Continue, Warp, etc.)
- What voice-first AI interfaces exist? What UX patterns are emerging?
- What animated avatar / embodied AI projects are gaining traction?
- How are non-technical users being served by AI tools today?

### Emerging Capabilities
- New Claude API features, Agent SDK capabilities, or model improvements
- Browser/desktop AI integration trends (local models, hybrid approaches)
- Voice technology advances (real-time STT/TTS, emotion detection, multilingual)
- Avatar/animation technology (Rive updates, real-time expression mapping)
- Electron ecosystem updates that unlock new possibilities

### User Need Signals
- Patterns in open issues and feature requests
- Common pain points from bug reports that suggest UX gaps
- What shipped recently (merged PRs) and what gaps remain
- Community discussion themes

Adjust depth based on RESEARCH_DEPTH:
- **quick**: Skim signals, 1-2 web searches, focus on low-hanging fruit
- **standard**: Thorough signal analysis, 5-8 web searches, balanced exploration
- **deep**: Exhaustive research, 10+ web searches, competitor deep dives, trend analysis

**Iterate:** After your first research pass, review what you found. Are there gaps?
Promising threads you didn't pull? Do another pass on the most promising areas
before moving on. Keep going until you feel you have a solid evidence base.

## Phase 3: Brainstorming Skill (Divergent Ideation)

**Switch to the "Brainstorming" mindset.** Now generate as many ideas as possible —
quantity over quality. No idea is too wild at this stage. Build on the evidence
from Phase 2 but let your imagination run.

Generate **8-15 raw feature ideas** across these lenses:
- What gaps do competitors leave that TalkTerm could fill?
- What emerging tech could unlock entirely new capabilities?
- What pain points from issues/bugs hint at deeper unmet needs?
- What would make TalkTerm indispensable for a specific user persona?
- What would a "10x better" version of an existing feature look like?

For each raw idea, write a one-line description and note which evidence supports it.

**Iterate:** Review your list. Can you combine two weaker ideas into one stronger
idea? Did generating ideas reveal a research gap? If so, go back to Phase 2 for
a targeted search, then return here. Repeat until the ideas feel grounded and
diverse.

## Phase 4: Party Mode Skill (Collaborative Refinement)

**Switch to the "Party Mode" mindset.** Imagine you are a room of enthusiastic
product people, engineers, and designers who are all excited about these ideas.
The energy is high. Each person builds on the previous person's suggestion.

Take the top 5-8 ideas from Phase 3 and refine them collaboratively:

1. **Amplify:** For each idea, ask "What if we went even further?" Push the idea
to its most ambitious form.
2. **Connect:** Look for synergies — can two ideas combine into something greater
than the sum of their parts?
3. **Ground:** For each amplified idea, ask "What is the minimum version that still
delivers the core value?" Find the sweet spot between ambition and feasibility.
4. **Score:** For each refined idea, assess:

| Dimension | Question |
|-----------|----------|
| **Feasibility** | Can we build this with the current stack? How much effort? |
| **Impact** | How many users does this serve? How much value does it add? |
| **Urgency** | Is the market moving here now? Is there competitive pressure? |

Select the **top 5 ideas** scoring high on at least 2 of 3 dimensions.

## Phase 5: Adversarial Skill (Stress-Test & Defend)

**Switch to the "Adversarial" mindset.** You are now a skeptical VP of Product,
a resource-constrained engineering lead, and a demanding end-user — all at once.
Your job is to tear these ideas apart. Only the ones that survive are worth proposing.

For each of the top 5 ideas from Phase 4, apply these challenges:

1. **"So what?"** — Why would a user actually switch to or stay with TalkTerm
because of this? If you can't articulate a compelling user story, cut it.
2. **"Who else?"** — Is someone else already doing this better, or about to?
If TalkTerm can't differentiate, cut it or find the unique angle.
3. **"At what cost?"** — What is the true engineering cost (not the optimistic
estimate)? What would we have to stop doing to build this? If the opportunity
cost is too high, cut it.
4. **"What breaks?"** — What existing functionality or architectural assumptions
does this violate? If it creates technical debt or UX inconsistency, can that
be mitigated?
5. **"Prove it."** — What evidence from Phase 2 actually supports demand for this?
Gut feelings and "it would be cool" are not evidence. Cite specific signals.

**After the adversarial pass, you should have 3-5 ROBUST and DEFENSIBLE proposals.**
Each surviving idea must have:
- At least one concrete market signal (competitor move, user request, or trend)
- A clear user story explaining why someone would care
- A feasible technical path grounded in the current architecture
- A rebuttal to the strongest objection against it

If fewer than 3 ideas survive, that is fine — quality over quantity.
If a focus area was specified, weight proposals toward that area but don't
exclude other high-scoring discoveries.

## Phase 6: Resolve Discussion Category & Repository IDs

**Auth note:** All `gh` and `gh api` commands in the phases below use
the `GH_TOKEN` environment variable (already set to the workflow's
`GITHUB_TOKEN`), which has `discussions: write` permission via the
job-level grant. You do NOT need to authenticate manually.

Before creating or updating Discussions, you need the repository ID and the
"Ideas" discussion category ID.

```bash
gh api graphql -f query='
query($repo: String!, $owner: String!) {
repository(name: $repo, owner: $owner) {
id
discussionCategories(first: 20) {
nodes { id name }
}
}
}' -f owner="${{ github.repository_owner }}" \
-f repo="${{ github.event.repository.name }}"
```

Save the repository ID and the "Ideas" category ID. If "Ideas" does not exist,
fall back to "General". If neither exists, skip Discussion creation and write
an error to the step summary.

## Phase 7: Create or Update Per-Idea Discussions

For **each** feature proposal surviving Phase 5, check whether a matching Discussion
already exists in the Ideas category.

### Matching Logic

Search existing Ideas discussions (from the signals data) for a title that
matches the proposal's core concept. Use fuzzy matching — the exact title
may differ but the idea should be recognizably the same.

**Discussion title format:** `💡 <Concise Idea Title>`

### If the Discussion DOES NOT exist → Create it

```bash
gh api graphql -f query='
mutation($repoId: ID!, $categoryId: ID!, $title: String!, $body: String!) {
createDiscussion(input: {
repositoryId: $repoId,
categoryId: $categoryId,
title: $title,
body: $body
}) {
discussion { id number url }
}
}' -f repoId="<REPO_ID>" \
-f categoryId="<CATEGORY_ID>" \
-f title="💡 <Idea Title>" \
-f body="<BODY>"
```

**New Discussion body format:**

```markdown
## Summary

<2-3 sentence description of the feature idea>

## Market Signal

<What competitive or market trend supports this idea>

## User Signal

<Related issues, feedback, discussion themes, or bug patterns>

## Technical Opportunity

<How the current architecture enables or supports this — reference specific
ports, interfaces, or extension points from the codebase>

## Assessment

| Dimension | Score | Rationale |
|-----------|-------|-----------|
| Feasibility | high/med/low | ... |
| Impact | high/med/low | ... |
| Urgency | high/med/low | ... |

## Adversarial Review

**Strongest objection:** <The hardest challenge this idea faces>
**Rebuttal:** <Why the idea survives despite that objection>

## Suggested Next Step

<Concrete action: "Create a product brief", "Spike on X", "Discuss with team", etc.>

---
*Proposed by the [BMAD Analyst (Mary)](/${{ github.repository }}/actions/workflows/feature-ideation.yml) on <DATE>.*
*[Workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})*
```

After creating, add the `enhancement` label to the discussion:
```bash
gh api graphql -f query='
mutation($labelableId: ID!, $labelIds: [ID!]!) {
addLabelsToLabelable(input: {
labelableId: $labelableId,
labelIds: $labelIds
}) { clientMutationId }
}' -f labelableId="<DISCUSSION_ID>" \
-f labelIds='["<ENHANCEMENT_LABEL_ID>"]'
```

To find the label ID:
```bash
gh api graphql -f query='
query($repo: String!, $owner: String!) {
repository(name: $repo, owner: $owner) {
label(name: "enhancement") { id }
}
}' -f owner="${{ github.repository_owner }}" \
-f repo="${{ github.event.repository.name }}"
```

### If the Discussion ALREADY exists → Add an update comment

When a prior run already created a Discussion for the same idea, add a comment
with new developments rather than creating a duplicate.

```bash
gh api graphql -f query='
mutation($discussionId: ID!, $body: String!) {
addDiscussionComment(input: {
discussionId: $discussionId,
body: $body
}) {
comment { id url }
}
}' -f discussionId="<DISCUSSION_ID>" \
-f body="<COMMENT>"
```

**Update comment format:**

```markdown
## Weekly Update — <DATE>

### What Changed

<New market signals, competitive moves, technology developments, or
user feedback since the last update. Be specific about what's new —
don't repeat the original proposal.>

### Updated Assessment

| Dimension | Previous | Current | Delta |
|-----------|----------|---------|-------|
| Feasibility | ... | ... | ↑/↓/→ |
| Impact | ... | ... | ↑/↓/→ |
| Urgency | ... | ... | ↑/↓/→ |

### Recommendation

<Should this idea be advanced, kept watching, or retired? Why?>

---
*Updated by the [BMAD Analyst (Mary)](/${{ github.repository }}/actions/workflows/feature-ideation.yml) on <DATE>.*
*[Workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})*
```

**Important:** Only add an update comment if there is genuinely new information.
If nothing has changed for an existing idea, skip it — don't post "no updates" comments.

### If an existing idea should be retired

If research shows a previously proposed idea is no longer viable (market shifted,
already implemented, superseded by another approach), add a final comment
recommending closure:

```markdown
## Retirement Recommendation — <DATE>

**Recommendation:** Close this proposal.

**Reason:** <Why the idea is no longer viable or relevant>

<Details on what changed>

---
*Reviewed by the [BMAD Analyst (Mary)](/${{ github.repository }}/actions/workflows/feature-ideation.yml) on <DATE>.*
```

Do NOT close the Discussion — only recommend closure for human decision.

## Phase 8: Step Summary

Write to $GITHUB_STEP_SUMMARY:

```markdown
## Feature Research & Ideation — <DATE>

**Focus:** <area or "Open exploration">
**Research depth:** <quick|standard|deep>

### New Ideas Proposed
| Discussion | Title | Feasibility | Impact | Urgency |
|------------|-------|-------------|--------|---------|
| #N | 💡 ... | ... | ... | ... |

### Existing Ideas Updated
| Discussion | Title | Key Change |
|------------|-------|------------|
| #N | 💡 ... | <what's new> |

### Ideas Reviewed — No Update Needed
| Discussion | Title | Reason |
|------------|-------|--------|
| #N | 💡 ... | <no new signal> |

### Market & Trend Summary
<2-3 bullet points on the most notable trends this week>

---
*[Workflow run](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }})*
```

## Rules

- **Do NOT create issues or PRs.** Output goes to Discussion threads only.
- **Do NOT implement code.** This is research and ideation only.
- **Max 5 new Discussions per run.** Fewer is fine — quality over quantity.
- **Only propose ideas scoring high on 2+ dimensions** (feasibility/impact/urgency).
- **One Discussion per idea.** Never create duplicates — always check existing first.
- **Only comment on existing Discussions when there is new information.** No empty updates.
- **Ground proposals in evidence.** Every proposal must cite at least one market signal,
user signal, or technical opportunity — not just abstract ideas.
- **Be specific about next steps.** Each proposal should suggest a concrete action
(product brief, spike, discussion, etc.) not just "we should consider this."
- **Respect the project's architecture.** Proposals should be compatible with the
Clean Architecture / DDD patterns documented in AGENTS.md.
- **Use the 💡 prefix** in all idea Discussion titles for easy identification.
uses: petry-projects/.github/.github/workflows/feature-ideation-reusable.yml@main
with:
Copy link

Copilot AI Apr 7, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

uses: petry-projects/.github/...@main pins the reusable workflow to a moving branch ref. That makes scheduled runs non-reproducible and increases supply-chain risk if the upstream workflow changes unexpectedly. Consider pinning to a version tag or commit SHA (and updating periodically) if you need stronger change control.

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants