rl-topic-scout

Files (1)

• SKILL.md

SKILL.md (first lines)

# Topic Scout

Most developers who build something worth writing about never write about it —
not because there's nothing to say, but because turning "I shipped a thing"
into "here's a topic with an angle" is its own piece of work, and it's the
part that gets skipped. This skill does that part.

It does not draft anything. Its output is a shortlist of grounded topic
candidates, each with enough evidence attached that `rl-content-pipeline`'s
define and interview steps (1-2) can start from material instead of a blank
page.

## Scope safety — client and confidential work

Client work and work-for-hire repos are often the *richest* source of
topics — the hardest problems and the most interesting tradeoffs tend to show
up under client pressure, not in side projects. Don't exclude them. Tag them
so the person picking a topic knows what they're looking at, and let them make
the call — don't make it for them by silently including or blanket skipping.

- **Repo scope (which repos are eligible) can be a fixed list or a live rule**
  (e.g. "top N by activity, recomputed each run") — either is fine. Scope is
  provided one of two ways: named explicitly in the request, or configured in
  a scheduled task; when neither is given, the scope is the current repo. What
  can't be static is the tagging: a repo's client/confidential status gets
  evaluated fresh on every scan, never inherited from a prior run or assumed
  because it wasn't flagged last time.
- **Tag confidential-source topics distinctly — don't hide them, don't
  silently launder them as generic.** If a repo's remote URL, README,
  CLAUDE.md, or commit history names a specific client or employer, or
  otherwise reads as work-for-hire rather than the user's own venture, every
  topic candidate sourced from it gets a `[CLIENT WORK — confidential
  source]` tag in the shortlist. It's a real candidate, surfaced like any
  other — the tag exists so the person picking it knows the source, not to
  talk them out of picking it.
- **Whether it needs genericizing is a judgment call made at pick time, not
  an assumed rule.** Some client work can be written about directly with
  nothing changed; some needs the client's name pulled or details
  abstracted; some shouldn't be written about at all. The skill doesn't
  guess which — it flags the source and leaves the call to whoever picks the
  topic. What it must not do is let a client-sourced topic slide into
  `rl-content-pipeline`'s define step (1) with the confidential-source tag
  quietly dropped along the way.
- **When unattended (a scheduled run), this matters more, not less** — there's
  no human in the loop that run to catch a dropped tag before it goes into a
  digest. When a repo's client status is ambiguous, tag it as
  confidential-source by default rather than guessing it's safe; a
  false-positive tag costs a glance, a false negative costs a leak.

## Know the author before ranking anything

Git activity alone can't tell you what's worth writing about — that depends on
who's writing, why, and for whom. Before generating or ranking a shortlist,
load the author's content context: who they write for (audiences/ventures),
why they write (the underlying motivation — documentation, thought
leadership, building an audience, something else), and what "worth
publishing" means to them.

- **Read `AUTHOR-CONTEXT.md` — the context file — at the repo root first,
  every run.** It's the canonical, portable version of this context — the
  single place audiences, ventures, and motivation live, not duplicated
  elsewhere. Built so an unattended or scheduled run has something durable to
  read instead of a question nobody's there to answer.
- **If the context file doesn't exist, or its three sections are still
  the unfilled template, this is a live/interactive run's job to fix, not an
  unattended run's.** Three paths:
  - **Quick fix** — ask once, directly: who do you write for, why do you
    write, what does a good outcome look like — then write the answers back
    into `AUTHOR-CONTEXT.md`.
  - **Thorough** — hand off to `rl-context-discovery`. It checks existing
    evidence first and uses interview techniques specifically designed to
    get past generic first answers (especially for "why do you write," which
    most people answer with a marketing-flavored non-answer on the first
    try).
  - **Unattended run** — note it in the digest ("author context not yet set
    up — ranking is a rough guess until this is filled in") rather than
    silently guessing or blocking.

Use this context to weight the shortlist, not just to fill in an "audience"
field after the fact. A topic that's easy to evidence but serves no stated
goal or audience ranks below one that's harder to evidence but squarely
serves what the author actually said they're trying to do. If the author's
stated reason for writing (`AUTHOR-CONTEXT.md`'s "Why I write" section)
favors low-friction, already-grounded topics over speculative
thought-leadership pieces, let that bias the ranking, not just the write-up.

## What to look at

Pull from what's actually in the repo — don't ask the user to summarize their
own work before you've looked:

- **Git log over the lookback window** (default: since the last scout run, or
  the last 2 weeks if this is the first run). Look for: commit clusters
  (a burst of related work — a feature, a migration, a refactor), a pattern in
  commit messages (repeated fixes to the same area — that's often a real
  story), and any commit that reads like a turning point ("switch from X to
  Y," "revert," "finally fix").
- **Diffs on the notable commits**, not just messages — the message says what
  happened, the diff says how and what it cost. A topic grounded in "we went
  from a 40-line mock to a real integration, and here's what broke" is
  concrete; a topic grounded only in a commit subject line is thin.
- **README / CLAUDE.md / docs changes** — a README rewrite often marks a real
  shift in what the project is or does, worth noting as a candidate on its
  own.
- **Structural changes** — new top-level directories, deleted subsystems,
  dependency swaps, a new skill/module/service added. These are often the
  most writable topics precisely because they represent a decision, not just
  activity.
- **Open questions or TODOs left in the code or commit messages** — sometimes
  the most honest post is about the tradeoff the team is still sitting with,
  not the one already resolved.

## What NOT to do

- Don't invent the "why" behind a change if it isn't visible in the commit
  message, PR description, or diff — same grounding rule as the rest of this
  skill suite. If the reasoning isn't there, the candidate's angle says "why
  this happened isn't clear from the repo — worth asking the author" instead
  of guessing.

From reventurelabs/rl-content-os, MIT.

More from reventurelabs/rl-content-os