Proactive and schedule-driven; the ledger is what keeps runs from redrafting the same gap or duplicating a PR still under review.

Step 0 — Orient and resume

bash

# Read the durable ledger first — covered topics, drafted-but-unmerged
# topics, and clusters seen before that didn't clear the bar.
cat .singulacomp/memory/kb-gap-mining-log.md 2>/dev/null || echo "(no ledger yet)"

# Check any open KB-gap PR from a prior run.
gh pr list --repo {{kb_repo}} --state open \
  --search 'in:title "kb: draft" OR label:kb-gap' \
  --json number,title,headRefName,statusCheckRollup,url

If a prior PR is still open and unreviewed, note its topics and don't duplicate them in this run's batch.

Step 1 — Pull recently resolved tickets from Plain (read-only)

Using PLAIN_API_KEY, pull threads resolved since the ledger's last-run timestamp (or the trailing 7 days if this is the first run). For each resolved thread, extract:

The question or problem as the customer originally stated it.
The resolution actually used to close it — the steps, the answer, the workaround — in the agent's or teammate's own words.
Enough context (thread ID) to trace the draft back to its source tickets, without carrying customer names or account details forward.

Skip threads with no reusable resolution (spam, duplicate of an in-progress bug, "never replied").

Step 2 — Cluster into topics

Group extracted tickets into topics using intent, not wording — "can't reset my password" and "reset link never arrives" are the same topic if the underlying question and resolution are the same; a superficially similar phrase with a different root cause is a different topic. For each candidate topic, keep: the ticket count, a representative set of the actual resolution steps, and the source thread IDs.

Step 3 — Freshen the KB repo and check existing coverage

bash

if [ -d /workspace/repo/.git ]; then
  cd /workspace/repo && git fetch origin && git checkout main && git reset --hard origin/main
else
  git clone --filter=blob:none https://github.com/{{kb_repo}}.git /workspace/repo
  cd /workspace/repo
fi

grep -ril "<likely topic keyword>" {{kb_path}} 2>/dev/null

For each candidate topic from Step 2, check both {{kb_path}} in the repo and the ledger's covered-topics list. A topic is a gap only if neither shows an existing article for it. A topic with an article that's out of date is not a gap for this skill — that's a refresh, not a new draft; skip it here.

Step 4 — Rank and select this week's batch

Rank remaining gap topics by ticket volume (how many resolved threads recurred on it). Re-check against the ledger's "seen before, below bar" entries — a topic that just crossed the volume threshold this week is promoted; a topic that's been circling near the bar for months without crossing it stays logged, not drafted. Take the top 3–5 as this week's batch.

Step 5 — Isolated drafting branch

bash

cd /workspace/repo
BRANCH="kb-gap/$(date +%Y-W%V)"
git checkout -b "$BRANCH" origin/main

One branch per weekly run.

Step 6 — Draft each article from real resolutions

For each topic in the batch:

Write the article under {{kb_path}}, matching the existing article format and tone in that directory.
Base every step in the article on the actual resolution steps gathered in Step 1 — never invent a fix the source tickets don't support.
Strip all customer names, account identifiers, and specifics; generalize to the reusable version of the question and answer.
Note the ticket count and topic in the PR description (not in the article itself) so the reviewer can judge whether the batch reflects real demand.

Step 7 — Commit

bash

cd /workspace/repo
git add {{kb_path}}
git commit -m "kb: draft $(date +%Y-W%V) batch

$(for each topic: echo "- <article path>: <ticket count> resolved tickets")"

Step 8 — Open the PR (draft only, never publish)

bash

cd /workspace/repo
git push origin "$BRANCH"
gh pr create --repo {{kb_repo}} --base main --head "$BRANCH" \
  --title "kb: draft $(date +%Y-W%V) batch" \
  --label kb-gap \
  --body "Generated by the ticket-to-KB agent. Each article was drafted from
the real resolutions used to close its cluster of Plain tickets, with
customer specifics stripped. Per article: the topic, the resolved-ticket
count that triggered it, and source thread IDs for verification. This PR is
never merged by the agent — a human reviews, edits, and decides what
publishes."

Step 9 — Update the ledger

Append a dated entry to .singulacomp/memory/kb-gap-mining-log.md (see <ledger-format>).

Step 0 — Orient and resume

Step 1 — Pull recently resolved tickets from Plain (read-only)

Step 2 — Cluster into topics

Step 3 — Freshen the KB repo and check existing coverage

Step 4 — Rank and select this week's batch

Step 5 — Isolated drafting branch

Step 6 — Draft each article from real resolutions

Step 7 — Commit

Step 8 — Open the PR (draft only, never publish)

Step 9 — Update the ledger

Run your whole company from one repo you own.