context-aware-questions

name	context-aware-questions
description	Use when asked 'what am I missing?', reviewing an issue or draft before submission, or checking documentation completeness - detects requirement, spec, and doc gaps and generates prioritized actionable questions

Context-Aware Question Generator Skill

Analyze project context to surface information gaps and generate prioritized, actionable questions.

When to Use

Activate when:

• User asks "what am I missing?" or "what questions should I be asking?"
• Reviewing issues before starting work
• Analyzing documentation completeness
• Preparing a draft (issue, PR, document) for submission
• During project planning or kickoff

Fetching Issues

Where issues are needed, fetch them with the gh CLI (must be installed and authenticated):

gh issue list --state open --json number,title,body,labels,assignees
gh issue view <n> --comments

Analysis Modes

1. Project-Wide Review

When asked "what am I missing?" or "what questions should I be asking?":

1. Fetch all open issues (see Fetching Issues)
2. Analyze project structure
3. Check README and documentation
4. Analyze all gathered data for information gaps
5. Generate prioritized questions

2. Issue Review

When asked to review a specific issue:

1. Fetch the issue and all comments (see Fetching Issues)
2. Analyze for missing requirements, unclear specs, and gaps
3. Generate targeted questions for that issue

3. Draft Review

When reviewing a draft (issue, PR, note) before submission:

1. Analyze the provided text for completeness
2. Check against standard templates and best practices
3. Suggest specific improvements

4. Documentation Gap Analysis

When asked about documentation completeness:

1. Read README.md and files in docs/
2. Analyze what the project contains
3. Identify missing documentation by comparing project content to docs

Gap Detection Heuristics

Issue Analysis

• Missing acceptance criteria: No checkboxes, no "done when" statement
• Vague descriptions: Less than 100 characters, contains "unclear", "might", "maybe"
• Missing labels or assignees: Issue has no labels or no assignee
• Stale issues: Open more than 30 days with no activity
• Bug reports without reproduction steps: No "steps to reproduce" section

Documentation Analysis

• Missing README sections: No install, usage, or examples sections
• No dedicated docs/ directory: For projects with more than 10 files
• Short README: Less than 500 characters
• Missing license information: No LICENSE file or license section
• No inline documentation: Missing JSDoc/docstrings in key files

Project-Wide Analysis

• Conflicting descriptions across issues, README, and docs
• Missing architecture documentation: No system overview for complex projects
• Undocumented key files: Entry points without explaining comments
• No project overview available: Run the project-analysis skill first to map the project structure

Output Structure

Questions are categorized and prioritized:

Categories

• requirements: Missing acceptance criteria, unclear specs, vague descriptions
• technical: Implementation questions, architecture decisions
• documentation: Missing docs, unclear README sections
• process: Workflow gaps, missing labels/assignees
• consistency: Conflicting information across sources
• architecture: High-level design questions

Priorities

• high: Blocking or critical gaps that need immediate attention
• medium: Important gaps that should be addressed soon
• low: Nice-to-have clarifications

Example Output

## Information Gaps Found

### High Priority (3)
1. [requirements] Issue #42 lacks acceptance criteria
   - Context: "Add login feature" has no definition of done
   - Suggested Action: Add checkboxes with acceptance criteria

2. [documentation] No API documentation found
   - Context: Project has 15 endpoints but no API reference
   - Suggested Action: Create docs/api.md with endpoint documentation

### Medium Priority (5)
...

Best Practices

When Generating Questions

1. Always prioritize by impact
2. Group related questions together
3. Provide actionable suggested actions
4. Link to specific sources (issue number, file path)

When Reviewing Drafts

1. Be constructive, not critical
2. Suggest specific improvements with example text when helpful
3. Acknowledge what's already good

When Analyzing Documentation

1. Check against industry standards
2. Consider the project type (CLI needs different docs than library)