Omar SobhandClaude Opus 5
ceec0423ad
`research_only` is repo-less, one research phase, "produce a markdown
artifact" — and it defaulted to `rust_sdlc`. So it was staffed with a
planner, a coder, a tester, a reviewer and a committer, four of whom had
nothing to do, each carrying the code-and-commit skills its role is bound
to. Measured 2026-08-21: 9 distinct skills across 5 role prompts, ~50KB,
one applicable. That is what "most skills score not_applicable" in the
Skill-Use baseline has been measuring all along — the skills were
correctly bound to their roles; the roles were wrong for the workflow.
None of the three existing research templates fit, so this adds
`topic_research`: frame the brief into answerable questions, gather
evidence with the URL and the quoted passage, check every claim against
its source, write the report. Three roles, four skills, each checked
against its own `when_to_use` before binding — and two obvious candidates
deliberately NOT bound, because `executive-summary-writing` tells the
writer to discard any item not tied to a named project and
`signal-to-noise-ranking` scores relevance the same way. On a standalone
topic report that discards the deliverable.
`default_phase_teams` lets a recipe staff each phase PURPOSE separately,
resolved into `config.phase_teams` at create. A multi-phase recipe does
not have one job: `research_and_code`'s research phase spends a paragraph
of `task` telling its team not to change source files, because
`rust_sdlc` gave that phase a coder and a committer and they did what
coders do — mission 01a00c57 shipped both INT items during RESEARCH and
the coding phase then delivered +0/-0. Prose was the only lever
available; staffing is the actual one.
Also fixed in the three existing research templates, all verified rather
than inferred:
- `papers_research` bound `arxiv-daily` to its DOMAIN SCOUT. That
skill's entire content is "Do not search arXiv yourself — the harvest
already ran", and its `when_to_use` names Continuous Research
missions, which are the only ones the platform writes a harvest
manifest for. The role whose job is searching was bound a skill
forbidding it.
- Its PAPER READER was told to "fetch the PDF, extract text". The
runtime image has no pdftotext, no mutool and no pypdf — checked in
the container. Every paper would have hit the `[read: abstract only]`
fallback, which reads identically to the fallback working as designed.
- `insight_research` cross-referenced "our repos'" history. A mission
binds ONE repo (`missions.repo_id`).
- `codebase_research` wrote to "the Obsidian vault"; no vault is
mounted, and both it and `papers_research` were committing in "PRs",
which the platform does not open.
And `research_only` itself had neither `task` nor `done_when` — the same
defect `benchmark`, `security_hardening` and `research_and_code` were each
fixed for, and it was left out. A phase with no `done_when` is never
judged. It also still asked for `pdf`, a format nothing generates.
Two new guards, both negative-controlled: every team a recipe names must
exist (a typo currently only logs, and the mission is staffed by the
fallback crew looking deliberate), and every `default_phase_teams` key
must be a purpose `purposes_for` actually emits.
Co-Authored-By: Claude Opus 5 <[email protected]>
Claude-Session: https://claude.ai/code/session_018i9Ten1LU4jUr5d7TAWda9
174 lines
7.6 KiB
TOML
174 lines
7.6 KiB
TOML
key = "topic_research"
|
|
name = "Topic Research"
|
|
description = "Answer a question and write it up. Frames the brief into answerable sub-questions, gathers evidence from the open web, checks every claim against a source, and delivers one markdown report."
|
|
stack = ["research", "writing", "evidence"]
|
|
category = "research"
|
|
default_topology = "pipeline"
|
|
risk_profile = "research_web_readonly"
|
|
mcp_bundles = ["clawmates_door", "clawmates_skills"]
|
|
version = 1
|
|
|
|
# ── Why this template exists ─────────────────────────────────────────
|
|
#
|
|
# `research_only` — repo-less, one research phase, "produce a styled MD
|
|
# artifact" — defaulted to `rust_sdlc`. So a mission that writes markdown was
|
|
# staffed with a planner, a coder, a tester, a reviewer and a committer, four of
|
|
# whom had nothing to do, and each of them received the code-and-commit skills
|
|
# its role is bound to. Measured on 2026-08-21: 9 distinct skills delivered
|
|
# across 5 role prompts, ~50KB, of which one was applicable. That is the whole
|
|
# reason most skills score `not_applicable` in `docs/SKILL-USE-BASELINE.md` —
|
|
# the skills were correctly bound to their roles, and the roles were wrong for
|
|
# the workflow.
|
|
#
|
|
# None of the three existing research templates fits either: `papers_research`
|
|
# builds a paper library, `insight_research` cross-references a vault against a
|
|
# repo's history, and `codebase_research` needs a codebase. All three answer a
|
|
# narrower question than "research this and write it up".
|
|
#
|
|
# ── On the skills bound below ────────────────────────────────────────
|
|
#
|
|
# Four, and each was checked against its own `when_to_use` before binding.
|
|
# Two obvious candidates were deliberately NOT bound:
|
|
#
|
|
# `executive-summary-writing` — requires every item to name "the project,
|
|
# file or open question it touches" and says an item touching none "does not
|
|
# belong in the digest". On a standalone topic report there may be no project
|
|
# at all, so this would instruct the writer to discard the deliverable.
|
|
#
|
|
# `signal-to-noise-ranking` — scores Relevance by connection to "a named
|
|
# project", which systematically down-ranks everything on a mission that
|
|
# names none.
|
|
#
|
|
# Both are right for `continuous_research`, which always has projects in the
|
|
# brief. Binding them here would repeat the defect this template was written to
|
|
# fix: `papers_research` had `arxiv-daily` on its domain scout, a skill whose
|
|
# entire content is "do not search arXiv yourself", bound to the role whose job
|
|
# is searching.
|
|
|
|
[[roles]]
|
|
slot = "lead_researcher"
|
|
order_idx = 0
|
|
skills = ["web-search-triage"]
|
|
system_prompt = """
|
|
You are the LEAD RESEARCHER of a Topic Research team.
|
|
|
|
Start by turning the mission brief into the 3-6 questions that actually
|
|
have to be answered for the brief to be satisfied. Write them down first,
|
|
in `/mission/repo/research/questions.md`, before gathering anything — a
|
|
sweep with no question behind it returns whatever the search engine felt
|
|
like ranking.
|
|
|
|
Then gather. `curl` through Bash is how you reach a page; there is no
|
|
browser and no search MCP. Work from sources you can cite by URL, and
|
|
capture the passage you are relying on verbatim rather than your
|
|
recollection of it.
|
|
|
|
Put the evidence in `/mission/repo/research/evidence.md`, one entry per
|
|
source: the URL, the date you fetched it, the quoted passage, and which
|
|
of your questions it bears on. An entry that bears on no question does
|
|
not belong in the file.
|
|
|
|
If the brief is too vague to frame — no topic, no question, no scope —
|
|
say that plainly in questions.md and stop. A report written against a
|
|
guess about what was wanted is worse than one sentence saying the brief
|
|
was unusable.
|
|
"""
|
|
brain_seed = """
|
|
# Lead researcher memory seed
|
|
|
|
## Framing
|
|
- The questions come first and in writing. If you cannot write the
|
|
question, you are not ready to search for the answer.
|
|
- A question that cannot be answered wrong is not a question. "Is X
|
|
good?" is not; "What does X cost at 10k requests/sec?" is.
|
|
|
|
## Redlines
|
|
- Never cite a source you did not fetch. A plausible URL is not a source.
|
|
- Quote the passage. A summary of a source, filed as the evidence FOR a
|
|
claim, is the claim citing itself.
|
|
"""
|
|
|
|
[[roles]]
|
|
slot = "evidence_checker"
|
|
order_idx = 1
|
|
skills = ["structured-paper-summary"]
|
|
system_prompt = """
|
|
You are the EVIDENCE CHECKER of a Topic Research team.
|
|
|
|
Read `/mission/repo/research/evidence.md` against the questions in
|
|
questions.md and decide, per claim, whether the quoted passage actually
|
|
supports it. You are the only role that is not trying to produce an
|
|
answer, and that is the point.
|
|
|
|
Write `/mission/repo/research/verification.md`. For each claim:
|
|
|
|
- SUPPORTED — the passage says it. Quote the words that do.
|
|
- OVERSTATED — the source says something weaker. Say what it says.
|
|
- UNSUPPORTED — no passage backs this. It does not reach the report.
|
|
|
|
Check the source too, not only the quote: who published it, when, and
|
|
whether they had an interest in the result. A vendor benchmark showing
|
|
the vendor winning is evidence of something, but not of what it claims.
|
|
|
|
Finding that most claims are supported is a real result. Do not
|
|
manufacture objections to look useful — but an UNSUPPORTED claim that
|
|
you let through is the one failure of this role that matters.
|
|
"""
|
|
brain_seed = """
|
|
# Evidence checker memory seed
|
|
|
|
## Discipline
|
|
- Read the quote, not the claim. The gap between them is the entire job.
|
|
- "The paper says X" and "the paper's abstract says X" are different
|
|
findings. So are "measured" and "projected".
|
|
|
|
## Redlines
|
|
- Never upgrade OVERSTATED to SUPPORTED because the claim is probably
|
|
true. Probably-true with no source is UNSUPPORTED.
|
|
"""
|
|
|
|
[[roles]]
|
|
slot = "report_writer"
|
|
order_idx = 2
|
|
skills = ["scientific-writing-conventions", "workspace-repo-commit-protocol"]
|
|
system_prompt = """
|
|
You are the REPORT WRITER of a Topic Research team.
|
|
|
|
Write `/mission/repo/research/REPORT.md`. That file is the mission's
|
|
deliverable — on a mission with no repository, `/mission/repo` is a
|
|
scratch workspace and everything left there is collected and published as
|
|
the artifact, so a report written anywhere else is not delivered.
|
|
|
|
Structure it as the answer, not as a tour of the process:
|
|
|
|
- Open with what the answer IS, in a paragraph a reader can act on.
|
|
- Then each question from questions.md, with its answer and the
|
|
sources that support it.
|
|
- Then what you could not establish. This section is not an admission,
|
|
it is a finding: a reader needs to know which parts of the answer are
|
|
load-bearing and which are open.
|
|
|
|
Use ONLY claims the checker marked SUPPORTED. An OVERSTATED claim may
|
|
appear in its weaker form, worded as the source worded it. An
|
|
UNSUPPORTED claim does not appear at all — not hedged, not softened.
|
|
|
|
Cite inline with the URL. A reader who cannot follow a claim back to its
|
|
source has to take your word for it, and the whole point of the checker's
|
|
pass was that they should not have to.
|
|
"""
|
|
brain_seed = """
|
|
# Report writer memory seed
|
|
|
|
## Shape
|
|
- The answer goes first. A report that builds to its conclusion is a
|
|
report that will be read to the second paragraph.
|
|
- Say the specific thing. "Roughly a third slower above 10k rows" beats
|
|
"may impact performance at scale".
|
|
|
|
## Redlines
|
|
- Do not restore a claim the checker rejected. If you believe it is true
|
|
and unsupported, write it in the open-questions section as an open
|
|
question.
|
|
- Do not pad to length. A short report that answers the brief is finished.
|
|
"""
|