FAQ from Issue Tracker

What this skill does

Pulls all closed GitHub issues for a repo, clusters them by title similarity, and produces a FAQ document for the top-N recurring questions. Each FAQ entry includes a one-paragraph answer synthesized from the resolution comments of the cluster.

Inputs

• repo: <owner>/<name>.
• top_n: number of FAQ entries to produce (default 10).
• since_days: only include issues closed in the last N days (default 365).
• GITHUB_TOKEN env var.

Steps

1. Fetch closed issues: gh issue list --repo <repo> --state closed --limit 1000 --search "closed:>=<date>" --json number,title,body,labels,comments.
2. Normalize titles: lowercase, strip punctuation, drop stopwords ("how", "to", "do", "i").
3. Compute MinHash signatures over normalized titles (use a small JS/Python helper). Cluster with locality-sensitive hashing at Jaccard threshold 0.5.
4. Drop clusters with fewer than 3 issues.
5. Rank clusters by size descending; take top top_n.
6. For each cluster, pick a canonical question from the issue with the most reactions (use reactions.total_count).
7. Synthesize an answer: extract the resolution comment from the issue with the highest reactions per cluster (look for "Resolved by", "Fixed in", or a closing comment from a maintainer); if no clear resolution, summarize the closing message.
8. Cite source issues at the end of each entry as a list of #NNN links.
9. Add a "How to ask a new question" prelude pointing to the issues new template.
10. Write to docs/FAQ.md.

Output

docs/FAQ.md containing a numbered list of FAQ entries: question (H3), answer paragraph, "Source issues:" footer linking back to GitHub. Stdout prints cluster sizes for transparency.

Verification

Sample three entries: open the linked source issues and confirm the synthesized answer matches the resolution direction (not necessarily verbatim, but no contradictions). Re-run the cluster step with top_n + 5 and verify entries 1..top_n remain stable — non-stable rankings suggest tighter clustering threshold needed. If gh issue list returned fewer than 100 issues, prepend a "small sample" note to the FAQ header.

Edge cases

• Repo with bot-generated issues (Dependabot): exclude by label dependencies or by author bot suffix.
• Issues lacking resolution comments: emit the entry with the question only and a TODO marker for a maintainer to write the answer.
• Non-English issues: cluster separately; produce a sub-FAQ per detected language.
• Very small repo (< 50 closed issues): exit with a "not enough corpus" warning rather than over-fit.