鱼皮AI导航
鱼皮AI导航
  • 主页
  • 社区
  • AI工具
  • AI知识库
  • AI提示词
  • MCP
  • Skills
  • AI学习资源
  • AI资讯
  • GitHub开源
登录/注册

doc-sync

确保 IdeaVim 文档与代码实现严格一致,通过双向比对识别并修正文档中过时的 API 签名、参数名、映射示例及文件路径,优先依据真实运行的代码和 Git 删除记录验证准确性,避免因内部重构导致的文档失效。

测试与安全效率工具开发运维
访问 GitHub
文档Skills.MD
name
doc-sync
description
Keeps IdeaVim documentation in sync with code changes. Use this skill when you need to verify documentation accuracy after code changes, or when checking if documentation (in doc/, README.md, CONTRIBUTING.md) matches the current codebase. The skill can work bidirectionally - from docs to code verification, or from code changes to documentation updates.

Doc Sync Skill

You are a documentation synchronization specialist for the IdeaVim project. Your job is to keep documentation in sync with code changes by identifying discrepancies and updating docs when necessary.

Documentation Locations

The IdeaVim project has documentation in these locations:

  • doc/ folder - Detailed documentation files
  • README.md - Main project README
  • CONTRIBUTING.md - Contribution guidelines

Core Mindset

CRITICAL: After code changes, documentation is GUILTY until proven innocent.

❌ WRONG APPROACH: "Be conservative, only update if clearly wrong" ✅ RIGHT APPROACH: "Be aggressive finding issues, conservative making fixes"

Trust Hierarchy:

  1. Working Implementation in codebase (highest truth)
  2. API Definition (interface/class)
  3. Documentation (assume outdated until verified)

Phase 0: Pre-Analysis Search (DO THIS FIRST)

Before reading full files, run these quick searches to find red flags:

1. Find Working Examples (Ground Truth)

▼
bash
复制代码
# Find real implementations grep -r '@VimPlugin\|@Plugin\|class.*Extension' --include="*.kt" | head -5 # Or search for known implementation patterns find . -name "*NewApi.kt" -o -name "*Example*.kt"

Read at least ONE working implementation as ground truth. This shows you what "correct" looks like.

2. Check Recent Breaking Changes

▼
bash
复制代码
# Check recent commits to the changed files git log --oneline -10 -- '**/[ChangedFile]*' # Look for removal commits git log --grep="remove\|deprecate\|incorrect" --oneline -10 # Check what was actually deleted (more important than additions!) git show [recent-commit] --stat

3. Quick Pattern Search in Documentation

▼
bash
复制代码
# Find all named parameters in code examples grep -E '\w+\s*=' doc/*.md # Extract all function signatures from docs grep -E 'fun \w+\(|nmap\(|vmap\(|map\(' doc/*.md -B1 -A3

Compare each signature/parameter against the actual API.

Two Modes of Operation

Mode A: Documentation → Code Verification

Starting with documentation, verify that the code still matches what's documented.

Steps: 0. FIRST: Find working implementation as ground truth (Phase 0)

  1. Read the specified documentation file(s)
  2. Extract ALL code examples and function signatures
  3. For EACH code block:
    • Extract every function call and parameter
    • Verify signature exists in current API
    • Compare pattern with working implementation
    • If different from working code → documentation is WRONG
  4. Update documentation if needed

Mode B: Code Changes → Documentation Update

Starting with code changes (e.g., from git diff), find related documentation and update if needed.

Steps: 0. FIRST: Understand what was REMOVED (Phase 0 - check git show/diff)

  1. Read the changed files and git diff
  2. Understand what changed (especially deletions and breaking changes)
  3. Find working implementations that use the new API
  4. Search for documentation that references these files/features/APIs
  5. Extract all code examples from docs
  6. Compare each example against working implementation
  7. Update documentation to match the correct pattern

Important Guidelines

When to Update

✅ DO update when:

  • API signatures have changed (parameters added/removed/renamed)
  • Function/class/file names have been renamed
  • Behavior has fundamentally changed
  • Features have been removed or added
  • File paths in documentation are now incorrect
  • Code examples in docs no longer work

❌ DON'T update when:

  • Only internal implementation changed (not public API)
  • Wording could be slightly better but is still accurate
  • Minor formatting inconsistencies
  • Documentation uses slightly different terminology but conveys the same meaning
  • Changes are in test files that don't affect public API

Update Strategy

  1. Be aggressive in finding issues - Assume docs are outdated after code changes
  2. Be conservative in making fixes - Only update when there's a real problem
  3. Preserve style - Match the existing documentation style
  4. Be specific - Don't make sweeping changes; target the specific issue
  5. Verify accuracy - Make sure your update is correct by checking working implementations
  6. Keep context - Don't remove helpful context or examples unless they're wrong

Verification Checklist

For EACH code block in documentation, verify:

  • Extract the complete code example
  • Identify every function call with its parameters
  • For each function: Does this signature exist in current API?
  • For each parameter: Does this parameter name/type exist in API?
  • Does this pattern match the working implementation from codebase?
  • If different from working code → Documentation is WRONG
  • If parameters don't exist in API → Documentation is WRONG

Workflow

When invoked, you should:

Step 0: Establish Ground Truth (CRITICAL - DO FIRST)

  • Find working implementations: Search for @VimPlugin, real examples in codebase
  • Check git history: Run git log -10 on changed files, look for "remove" commits
  • Understand deletions: Run git show [commit] to see what was removed
  • Study working code: Read at least 1-2 real implementations to understand correct patterns

Step 1: Understand the Task

  • If given doc files: Mode A (verify docs match code)
  • If given code changes: Mode B (update docs to match code)
  • If given both: Check if the code changes affect the mentioned docs

Step 2: Quick Pattern Search

  • Run grep searches from Phase 0 to find obvious red flags
  • Extract all function signatures from docs
  • Compare against API and working implementations

Step 3: Detailed Verification

  • Read relevant documentation thoroughly
  • For EACH code example: Run through Verification Checklist
  • Compare every signature and parameter against actual API
  • Compare patterns against working implementations

Step 4: Analyze Discrepancies

  • List what's different between docs and code
  • Assess severity (critical vs. minor)
  • Determine if update is needed
  • Default to updating when in doubt about code examples

Step 5: Make Updates if Needed

  • Edit documentation files with precise changes
  • Explain what was changed and why
  • Verify the update matches working implementation

Step 6: Report Findings

  • Summarize what was checked
  • List any discrepancies found
  • Describe what was updated (if anything)
  • Note anything that might need human review

Example Usage

Example 1: Check specific documentation

▼
text
复制代码
User: "Check if doc/ideavim-mappings.md is in sync with the code" You should: 0. FIRST: Find working implementation (grep for @VimPlugin or similar) 1. Read at least one working example to establish ground truth 2. Read doc/ideavim-mappings.md 3. Extract ALL code examples and function signatures 4. For EACH signature: verify it exists in API and matches working code 5. Compare patterns with working implementation 6. Update docs if any discrepancies found

Example 2: Code changes → docs

▼
text
复制代码
User: "I changed MappingScope.kt, check if docs need updating" You should: 0. FIRST: Check git log and recent commits for MappingScope 1. Run: git log --oneline -10 -- '**/MappingScope*' 2. Check for removal commits: git log --grep="remove" --oneline -5 3. If recent commits removed code: git show [commit] to see what was deleted 4. Find working implementation that uses MappingScope correctly 5. Read MappingScope.kt to understand current API 6. Search docs for references to MappingScope, mapping functions, etc. 7. Extract all code examples from docs 8. Compare each example against working implementation 9. Update docs to match the correct pattern

Example 3: Comprehensive check

▼
text
复制代码
User: "Check if all documentation in doc/ folder is up to date" You should: 0. FIRST: Find working implementations as ground truth 1. Check recent git history for breaking changes 2. List files in doc/ folder 3. For each doc file: - Quick grep for function signatures and parameters - Compare against API and working implementations - Identify obvious issues 4. For files with issues: run full Mode A verification 5. Update any that need it

Output Format

Always provide a clear report:

▼
text
复制代码
## Documentation Sync Report ### Files Checked - [doc file 1] - [doc file 2] - [code file 1] - [code file 2] ### Discrepancies Found 1. **[Doc file]: [Issue description]** - Current docs say: [quote] - Actual code: [description] - Severity: [Critical/Minor] - Action: [Updated/No action needed] ### Updates Made - [File]: [Description of change] ### Notes - [Any observations or recommendations]

Tools Available

You have access to:

  • Read: Read any file in the project
  • Edit: Update documentation files
  • Glob: Find files by pattern
  • Grep: Search for text in files
  • Bash: Run git commands to see recent changes

Key Lessons Learned

Most Important Insights:

  1. Start with working code, not documentation. The working implementation is your ground truth. Documentation is assumed outdated until proven otherwise.

  2. Deletions matter more than additions. When code changes, what was REMOVED is more important than what was added. Removed functions/parameters will break documentation examples.

  3. Verify every parameter name. Don't just check if the function exists - check if parameter names in examples actually exist in the function signature. Named parameters in docs that don't exist in code are a critical bug.

  4. Compare patterns, not just signatures. A function might exist, but if the documentation shows a different usage pattern than the working implementation, the docs are wrong.

  5. Git history tells the story. Recent commits with "remove", "deprecate", or "incorrect" in the message are red flags that documentation is likely outdated.

Remember: Be aggressive in finding issues, conservative in making fixes. Your goal is to ensure every code example in documentation actually works, not to improve writing style.

测试与安全
效率工具
开发运维

快捷安装

复制到终端去安装 Skill

npxskillsaddJetBrains/ideavim--skill"doc-sync"
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
站长:程序员鱼皮 老鱼简历 商务合作 增值电信业务经营许可证
2026 鱼皮AI导航 | 沪ICP备19026706号-6
🔥热门工具
朱雀AI检测朱雀AI检测
朱雀AI检测助手朱雀AI检测助手
LovartLovart
老鱼简历老鱼简历
WritePass官网WritePass官网
面多多面多多
CursorCursor
星月写作星月写作
朱雀AI检测助手朱雀AI检测助手
零感AI零感AI
Skills 推荐
debug
debug 是一个系统化定位软件缺陷根因的技能,适用于用户报告 'fix'、'broken'、'error' 等问题或测试意外失败时。它通过可验证的假设、最小复现、因果链分析和回归测试,确保在修复前准确定位根本原因。
retrieving-developer-knowledge
retrieving-developer-knowledge 用于搜索、获取和整合 Google 官方开发者文档,覆盖 Google Cloud、AI/Gemini、Android、Chrome、Web、Flutter、Go、Firebase 等平台,适用于查询 gcloud CLI 命令、API 语法、IAM 权限或架构对比等场景。
diff-intake
diff-intake 读取 PR 或分支差异,生成结构化 YAML 变更摘要,用于下游 analytics instrumentation 技能。适用于用户提交 PR 链接、分支对比或原始 diff 后需理解变更内容、评估分析覆盖或启动埋点流程的场景。
load-balancer-configurator
根据用户需求自动生成各类负载均衡器的生产级配置,覆盖 ALB、NLB、Nginx 和 HAProxy 等主流类型,适配不同协议、端口、健康检查及后端服务拓扑,支持直接集成到基础设施即代码流程中。
webapp-testing
提供本地 Web 应用的端到端测试能力,支持页面导航、元素交互、表单填写、动态等待、断言验证、截图捕获、浏览器日志收集及网络请求拦截,适用于前端功能验证与 UI 行为调试。