/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 pre