Specification Questionnaire with Gemini¶

📋 Overview¶

The Specification Questionnaire feature uses Gemini AI to automatically generate a tailored specification questionnaire when an issue is ready to be planned. This questionnaire helps clarify technical and functional details before implementation begins.

🎯 Purpose¶

This feature enables you to:

Clarify requirements before development starts
Identify ambiguities in issue descriptions
Standardize the specification gathering process
Improve implementation quality through better preparation
Reduce back-and-forth between developers and product owners

🚀 How to Use¶

Method 1: Automatic via Label¶

Create or select an issue in your GitHub project
Move the issue to the "Ready" column on your Project Board
Add the plan-with-gemini label to the issue
Wait a few seconds - A GitHub Actions workflow will trigger
Check the comment - The questionnaire will be posted automatically as a comment

Method 2: Manual via Workflow Dispatch¶

Go to the Actions tab of your repository
Select the "Plan with Gemini QCM" workflow
Click "Run workflow"
Enter the issue number
Click "Run workflow" to start

📝 Types of Generated Questions¶

The questionnaire automatically adapts to the issue type:

For Features (`type:feature`)¶

Feature scope (MVP vs full feature)
User interface (expected UI/UX)
Integration and dependencies (affected systems)
Performance and scalability (performance constraints)
Open question for additional details

For Bugs (`type:bug`)¶

Severity and impact (bug criticality)
Reproducibility (frequency and conditions)
Affected environment (dev, staging, prod)
Fix approach (hotfix vs full fix)
Open question for logs and debugging

For Tasks (`type:task`)¶

Main objective (refactoring, setup, documentation)
Technical approach (technical plan vs investigation)
Dependencies and blockers (prerequisites)
Success criteria (expected deliverables)
Open question for specific constraints

⚙️ Configuration¶

Prerequisites¶

Gemini API Key: Obtain a key from Google AI Studio
GitHub Secret: Configure GEMINI_API_KEY in the repository secrets

Setting Up the Secret¶

# In your repository's GitHub settings
Settings → Secrets and variables → Actions → New repository secret

Name: GEMINI_API_KEY
Value: <your-gemini-api-key>

Environment Variables (optional)¶

You can also configure in .env for local testing:

GEMINI_API_KEY=your_gemini_api_key_here
GH_TOKEN=your_github_token_here
GH_OWNER=your_github_username
GH_REPO=project-name

🔧 Command Line Usage¶

The script can also be run manually:

# Generate a questionnaire for issue #42
python scripts/generate_qcm.py --issue 42

# Generate and automatically post as a comment
python scripts/generate_qcm.py --issue 42 --post-comment

# Save to a file
python scripts/generate_qcm.py --issue 42 --output qcm-issue-42.md

Available Options¶

Option	Description
`--issue`	Issue number (required)
`--owner`	Repository owner (optional, defaults from env)
`--repo`	Repository name (optional, defaults from env)
`--post-comment`	Post the questionnaire as a comment on the issue
`--output`	Output file to save the questionnaire

📊 GitHub Actions Workflow¶

The workflow .github/workflows/plan-with-gemini.yml:

Triggers on: plan-with-gemini label added to an issue
Can also be triggered: Manually via workflow_dispatch
Generates: A tailored questionnaire using Gemini
Posts: The questionnaire as a comment on the issue
Adds: The qcm-generated label once complete

Process Diagram¶

Issue created → Moved to "Ready" → "plan-with-gemini" label added
                                              ↓
                                    GitHub Actions workflow triggered
                                              ↓
                                    Python script executed
                                              ↓
                                    Gemini generates the questionnaire
                                              ↓
                                    Questionnaire posted as comment
                                              ↓
                                    "qcm-generated" label added

🎨 Questionnaire Format¶

The generated questionnaire follows this Markdown format:

## 🎯 Specification Questionnaire

> This questionnaire helps you clarify the details...

### Question 1: [Question Title]

**Context:** [Why this question matters]

- [ ] Option A: [Description]
- [ ] Option B: [Description]
- [ ] Option C: [Description]

### Open Question: Additional Information

**Are there any important details to consider?**

[Space for free-form answer]

---

**Instructions:** Please check the relevant options...

🔍 Example Output¶

For a feature issue requesting "Add dark mode", the questionnaire might include:

Scope: Simple toggle vs fully customizable theme
Persistence: localStorage vs user preferences in DB
Auto-detection: Whether or not to respect system preferences
Components: Which UI elements should support dark mode
Open question: Specific colors, accessibility, etc.

❓ FAQ¶

How do I customize the questions?¶

The questions are generated by Gemini based on the issue content. To get more relevant questions:

Provide a detailed description in the issue
Use the appropriate issue templates
Add context in the "Motivation" section

What if the questionnaire isn't generated?¶

Verify that GEMINI_API_KEY is configured in the secrets
Check the workflow logs in the Actions tab
Verify the Gemini API quota hasn't been exceeded
Retry by removing and re-adding the label

Can I modify the questionnaire template?¶

Yes! Edit the _generate_template_qcm() method in scripts/generate_qcm.py to customize the fallback templates.

Can the questionnaire be regenerated?¶

Yes, remove the plan-with-gemini label and add it again to trigger a new generation.

🛠️ Troubleshooting¶

Error: "GEMINI_API_KEY not set"¶

Solution: Configure the GEMINI_API_KEY secret in the repository settings.

Error: "API rate limit exceeded"¶

Solution: Wait a few minutes or use an API key with a higher quota.

The workflow doesn't trigger¶

Checks: - The exact label is plan-with-gemini (case-sensitive) - The workflow file exists in .github/workflows/ - The GITHUB_TOKEN permissions are correct

The comment isn't posted¶

Checks: - The GitHub token has issues: write permissions - The issue isn't locked - Check the workflow logs for more details

📚 Resources¶

🔄 Integration with Existing Workflow¶

This feature integrates with the existing project management workflow:

Backlog → Issue created
Ready → plan-with-gemini label added → Questionnaire generated
Answer the questionnaire → Team responds to the questions
In Progress → auto-branch label added → Branch created
In Review → PR opened
Done → PR merged

🎯 Best Practices¶

Systematically add the plan-with-gemini label for complex features
Answer the questionnaire before adding the auto-branch label
Keep the answers in the issue for future reference
Iterate if needed by regenerating the questionnaire if questions remain
Document the decisions made following the questionnaire in the issue

📈 Metrics and Tracking¶

The qcm-generated label allows you to track: - Number of issues that received a questionnaire - Questionnaire completion rate - Impact on implementation quality