| 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?":
- Fetch all open issues (see Fetching Issues)
- Analyze project structure
- Check README and documentation
- Analyze all gathered data for information gaps
- Generate prioritized questions
2. Issue Review
When asked to review a specific issue:
- Fetch the issue and all comments (see Fetching Issues)
- Analyze for missing requirements, unclear specs, and gaps
- Generate targeted questions for that issue
3. Draft Review
When reviewing a draft (issue, PR, note) before submission:
- Analyze the provided text for completeness
- Check against standard templates and best practices
- Suggest specific improvements
4. Documentation Gap Analysis
When asked about documentation completeness:
- Read README.md and files in docs/
- Analyze what the project contains
- 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
- Always prioritize by impact
- Group related questions together
- Provide actionable suggested actions
- Link to specific sources (issue number, file path)
When Reviewing Drafts
- Be constructive, not critical
- Suggest specific improvements with example text when helpful
- Acknowledge what's already good
When Analyzing Documentation
- Check against industry standards
- Consider the project type (CLI needs different docs than library)
