Opensourcefaq

Overview

Use this skill to produce a verified, source-backed, diagram-rich Markdown answer for questions about open-source products. Require the user to provide the question, every relevant project source directory, and the corresponding DeepWiki repoName values; remind them to clone the source first and run init to generate project framework notes before using the skill.

Inputs

Confirm these inputs before writing the final article:

• question: the exact technical question to answer.
• source_dirs: absolute paths to all open-source project checkouts involved.
• deepwiki_repo_names: DeepWiki repoName values such as owner/repo for each relevant project.
• version_context: branch, tag, commit, release, or product version if the answer depends on version-specific behavior.

If any required input is missing, ask for it. If only the version context is missing, inspect the local checkout with git -C <dir> rev-parse --abbrev-ref HEAD, git -C <dir> rev-parse HEAD, and release files when useful, then state the inferred version and its limits.

Workflow

1. Restate the question and scope.

   • Identify the involved projects, versions, modules, configuration, and runtime assumptions.
   • Split broad questions into concrete subquestions that can be checked against source code.

2. Analyze the problem.

   • Form hypotheses from the user's wording, known architecture, and likely code paths.
   • Name ambiguity early instead of silently choosing one interpretation.
   • Prefer the simplest explanation that source code and docs support.

3. Prepare evidence.

   • Search local source directories first with rg, rg --files, and targeted file reads.
   • Search both implementation code and project documentation relevant to the question. Include source files, tests, examples, SQL/API definitions, configuration templates, README/manual/reference docs, release notes, design docs, and migration notes when present.
   • When code and docs disagree, verify against the code path and note the documentation drift.
   • Read the project framework notes generated by init when present, then verify important claims against source files.
   • Browse DeepWiki project overviews for the listed repoName values.
   • Ask DeepWiki focused questions about architecture, relevant modules, and the exact technical behavior under investigation.
   • Search the web for relevant articles, issues, release notes, documentation, design docs, and discussions when current or external context matters.

4. Filter evidence quality.

   • Prefer source code, official docs, release notes, design docs, and maintainer comments.
   • Treat blogs, forum answers, and copied snippets as secondary evidence.
   • Check publication date, project version, branch, API names, file paths, and whether the behavior still exists in the local checkout.
   • Discard or clearly qualify outdated material.

5. Write the Markdown article.

   • Save under the current project's markdown/ directory. Create that directory if it does not exist.
   • Use a clear filename derived from the question, for example markdown/opensourcefaq-<topic>.md.
   • Cite local files with paths and line numbers when possible.
   • Cite DeepWiki and web sources with links or repoName references.
   • Make the article diagram-rich. Include Mermaid diagrams for architecture, flow, sequence, state, dependency, data model, or query plans whenever they clarify the answer.
   • Add tables for evidence, version differences, tradeoffs, parameters, or operational checklists when useful.
   • If the user asks for practical execution, troubleshooting, benchmarking, reproduction, or "how to use", include a complete simulated environment and sample data generation method unless the real environment is already provided and sufficient.
   • Keep the article focused on the user's question; do not expand into an unrelated product overview.

6. Verify before finalizing.

   • Re-check every important technical claim against local code and DeepWiki.
   • Verify commands, configuration examples, API names, SQL, YAML, code snippets, and file paths.
   • If a claim cannot be verified, mark it as an inference and explain the basis.
   • If code behavior differs across versions, state exactly which version was verified and what may differ elsewhere.
   • For practical examples, verify that setup steps, generated data shape, commands, and expected outputs are internally consistent. If commands were not actually run, say so explicitly.

Practical Reproduction Requirements

When the answer includes hands-on usage, troubleshooting, benchmarking, or an executable example, include:

• A minimal simulated environment: container commands, local build steps, package prerequisites, service configuration, database/schema setup, or equivalent project-native setup.
• Data generation: SQL, scripts, fixtures, API calls, or command sequences that create representative data covering normal cases and edge cases.
• Execution steps: commands or queries the reader can run in order.
• Expected observations: key outputs, metrics, query plans, logs, errors, or screenshots/diagrams to compare against.
• Cleanup steps when the setup creates services, containers, databases, files, or test data.

Prefer project-native tooling already present in the repository. Do not invent heavyweight infrastructure when a lightweight local or containerized setup demonstrates the point.

Article Structure

Use this structure unless the user's question calls for a shorter answer:

# <Question as a precise title>

## 问题描述
<Restate the question, scope, projects, and verified versions.>

## 结论先行
<Direct answer in a few paragraphs.>

## 问题分析
<Break down the reasoning path and key assumptions.>

## 准备素材
### 本地代码与文档搜索
<Important implementation files, tests, examples, docs, release notes, configs, functions, modules, and line references. State any mismatch between code and docs.>

### DeepWiki 综述与问答
<Relevant architecture summary and focused DeepWiki answers.>

### 网络资料筛选
<Current, high-quality external sources and rejected outdated sources when relevant.>

## 原理与实现细节
<Explain mechanisms, data flow, call flow, configuration, and edge cases.>

## 图解
<Mermaid architecture/flow/sequence/data-model diagrams and, when useful, tables that make the answer visually clear.>

## 实操示例
<If practical execution is relevant, provide simulated environment setup, sample data generation, executable commands, expected observations, and cleanup. Otherwise explain why no hands-on reproduction is needed.>

## 拓展思考
<How to generalize the method, compare adjacent designs, or avoid common mistakes.>

## 验证记录
<What was checked in source code, DeepWiki, tests, or commands, and any remaining uncertainty.>

## 参考资料
<Local paths, DeepWiki repoNames, and web URLs.>

Validation Rules

• Do not rely on memory alone for product behavior.
• Do not cite web articles without checking version freshness and consistency with local source.
• Do not treat DeepWiki as final authority when local code contradicts it; source code wins.
• Do not invent line numbers, functions, flags, or configuration names.
• Do not omit related local documentation when searching source directories; code-only evidence is insufficient unless the project has no relevant docs.
• Do not output a text-only article when diagrams or tables would clarify the answer.
• Do not provide practical SQL/code/CLI examples without a reproducible environment and sample data plan, unless the user explicitly asks for conceptual explanation only.
• Keep final Markdown in Chinese by default unless the user asks for another language.
• End the response to the user with the saved file path and a concise verification summary.