| name | requirement-insights |
| description | Discover requirement insights through evolution tracking and gap analysis. Use when (1) tracking how boundary-external issues are resolved across version chains, (2) building feature coverage matrices to identify uncovered functionality, (3) visualizing requirement evolution with Mermaid diagrams, (4) finding requirement gaps and overlaps, (5) generating next-direction recommendations based on unresolved issues and missing features. Also use when a user mentions 'evolution tracking', 'gap analysis', 'coverage matrix', 'requirement insights', 'unresolved issues', or 'feature coverage'. |
| license | MIT |
| compatibility | opencode |
Requirement Insights
Discover requirement insights from two complementary dimensions: evolution tracking (time dimension — which issues haven't converged) and gap analysis (feature dimension — which features aren't covered).
Two Insight Dimensions
| Dimension | What It Finds | Output Type |
|---|
| Evolution Tracking | Boundary-external issues not resolved across version chains | --output-type evolution |
| Gap Analysis | Features not covered by any document | --output-type gap |
| Both | Complete insights report | --output-type all (default) |
┌─ --output-type evolution ──→ 演进追踪结果 + Mermaid图
│
Input data ─────────────┼─ --output-type gap ──→ 覆盖矩阵 + 缺口分析
│
└─ --output-type all ──→ 全部（默认）
Evolution Tracking
From each document's boundary_issues, track resolution status across version chains:
V1.8.0 raises: "network latency causes inaccurate detection" → 🔴 unresolved
V2.1.0 resolves: "fast/slow device response speed gap" → 🟡 partial (V1 resolved)
V2.2.3 advances: "mixed-network latency self-adaptation" → 🟡 partial (extreme cases remain)
Key principle: "Partial resolution" is the most common status — requirements evolve incrementally.
Mermaid Visualization
flowchart TD
V1_8_0["V1.8.0 响应时延V1<br/>🔴 网络延时判定不准"]
V2_1_0["V2.1.0 响应时延V2<br/>🟡 快慢设备差异"]
V2_2_3["V2.2.3 响应时延V3<br/>🟢 已解决V2 ⚠️ 极端场景"]
V1_8_0 -->|解决| V2_1_0
V2_1_0 -->|部分解决| V2_2_3
Color coding: 🔴 unresolved, 🟡 partial, 🟢 resolved, ⚠️ new issue raised
Gap Analysis
Build a feature coverage matrix to identify uncovered functionality:
| Feature | V2.0.4 | V2.2.5 | V2.2.6 | Status |
|---|
| Data collection plan definition | ✅ | ❌ | ❌ | ✅ covered |
| Data query page | ❌ | ✅ | ❌ | ✅ covered |
| Terminal data collection impl | ❌ | ❌ | ✅ | ✅ covered |
| Data validation | ❌ | ❌ | ❌ | ❌ gap |
Key principle: Overlap is not always a problem — version evolution is normal overlap. Only unrelated duplicates are problematic.
Quick Start
All commands below assume the working directory is the skill root (skills/requirement-insights/).
Install dependencies first: pip install -r requirements.txt
Run insights analysis
python scripts/insights.py <classify_json> <analysis_dir> <output_json> [options]
python scripts/insights.py classify.json ./analysis/ result.json
python scripts/insights.py classify.json ./analysis/ result.json --output-type evolution
python scripts/insights.py classify.json ./analysis/ result.json --output-type gap
python scripts/insights.py classify.json ./analysis/ result.json --feature-dims dims.json
python scripts/insights.py classify.json ./analysis/ result.json --include-mermaid
Input
Required
- Classify result JSON — output from
prd-overview-classify
- Analysis directory — containing per-document analysis JSONs from
prd-per-analysis
Optional
- Feature dimensions — via
--feature-dims for user-defined feature list (skips LLM extraction)
- Mermaid output — via
--include-mermaid flag
Output Format
{
"project_name": "智能联动",
"output_type": "all",
"evolution": {
"evolution_chains": [
{
"chain_name": "响应时延",
"versions": [
{
"version": "V1.8.0",
"doc_id": "uuid1",
"title": "智能联动响应时延V1",
"boundary_issues_raised": ["网络延时导致判定不准确"],
"boundary_issues_resolved": [],
"boundary_issues_remaining": ["网络延时导致判定不准确"]
}
]
}
],
"summary": {
"total_chains": 5,
"total_issues": 19,
"resolved": 10,
"partial": 5,
"unresolved": 4
},
"mermaid_graph": "flowchart TD\n ..."
},
"gap_analysis": {
"feature_dimensions": ["数据采集方案定义", "数据查询页面"],
"coverage_matrix": [
{
"feature": "数据采集方案定义",
"covered_by": ["V2.0.4"],
"status": "covered"
},
{
"feature": "数据校验",
"covered_by": [],
"status": "gap"
}
],
"gaps": [
{
"feature": "数据校验",
"description": "无任何文档覆盖数据校验机制",
"severity": "high",
"suggestion": "建议新增需求文档覆盖此功能"
}
],
"overlaps": [
{
"feature": "响应时延判定",
"covered_by": ["V1.8.0", "V2.1.0", "V2.2.3"],
"note": "3篇文档覆盖同一功能，属正常演进"
}
],
"summary": {
"total_features": 4,
"covered": 3,
"gaps": 1,
"overlap_count": 1
}
},
"metadata": {
"total_docs": 29,
"output_type": "all",
"models_used": {"text": "claude-sonnet-4-20250514"}
}
}
Key Features
- Two insight dimensions in one Skill: Evolution tracking + gap analysis, selectable via
--output-type
- Semantic issue matching: Cross-version boundary issue matching uses LLM for semantic similarity (same issue described differently)
- Mermaid visualization: Evolution chain flowcharts with color-coded resolution status
- Feature extraction: LLM-driven feature dimension extraction from document boundaries
- Coverage matrix: Clear covered/gap/overlap status per feature
Dependencies
pip install -r requirements.txt
Scripts Reference
| Script | Purpose |
|---|
insights.py | Main entry: evolution tracking + gap analysis |
Prompts Reference
| Prompt | Purpose |
|---|
evolution-match.md | Cross-version boundary issue semantic matching |
feature-extraction.md | Feature dimension extraction from document boundaries |
gap-assessment.md | Gap severity assessment and suggestions |
For detailed API and customization, see references/usage-guide.md.
