opensourcefaq

---
name: opensourcefaq
description: Answer open-source product questions by combining local source-code and documentation research, project framework notes generated by init, DeepWiki repository knowledge, and current web evidence, then save a sourced, diagram-rich Markdown answer to the current project's markdown directory. Use when the user asks about behavior, architecture, internals, configuration, APIs, troubleshooting, performance, operations, extension points, practical reproduction, or version-specific details of one or more open-source projects and provides the question, all relevant local source directories, and DeepWiki repoName values.
---

# 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:

```markdown
# <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.