Research harness
Three-stage research pipeline (collect → synthesize → analyze) for iterating on Ryu design decisions. Use when user drops URLs/repos/sessions for research, asks to "synthesize" findings, or asks for an "options analysis" / "recommendation". Defaults to non-saving until relevance is confirmed (approval scan). Lives at $PROJECT_ROOT/harness-research/. Never include in deployable.From its SKILL.md
npx -y skills add Jpk0512/ryu-next --skill research-harnessAssembled from the repository path, not quoted from the project. Check it against their README if it does not work.
One thing to look at
- 1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.
SKILL.md
7.1 KB, as published. Nobody here has run it
research-harness Skill
Three-stage research pipeline for iterating on Ryu design decisions:
URL / repo / session drop
│
┌────▼────┐
│ Stage 0 │ Approval scan — score relevance, ask if below threshold
│ Probe │
└────┬────┘
│ approved (relevance ≥4 AND fit=good → auto-save; else ask)
┌────▼────┐
│ Stage 1 │ Collection — fetch, frontmatter, update INDEX.md
│ Collect │
└────┬────┘
│ user: "synthesize X"
┌────▼────┐
│ Stage 2 │ Synthesis — multi-pass, full team flow (Opus reviewers)
│Synthesize│
└────┬────┘
│ user: "analyze" / "build options" / "recommendation"
┌────▼────┐
│ Stage 3 │ Analysis — multi-pass, full team flow → options.md
│ Analyze │
└────┬────┘
│ user picks direction
decisions/YYYY-MM-DD-<topic>.md (mini-ADR)
Workspace root: $RESEARCH_WORKSPACE (default: ./harness-research)
Stage 0 — Approval Scan (required before any save)
When the user drops a URL, repo, or session reference:
- Run
scripts/fetch.sh --probe "$URL"to pull headers/abstract (first 2000 chars). - Apply the prompt at
prompts/approval-scan.mdto score the item. - Output the verdict in this exact format:
TYPE: <article|repo|paper|x-post|session>
TOPIC: <one-liner>
RELEVANCE: <1-5>
FIT: <good|marginal|poor>
REASON: <2 sentences max>
VERDICT: <SAVE | ASK | DROP>
Auto-save threshold: RELEVANCE ≥ 4 AND FIT = good → write to collection/ immediately.
Below threshold or marginal: present verdict to user, ask "Save anyway?" Default is NOT saved.
Probe lifecycle: store probe result ephemerally in inbox/ (no frontmatter, no INDEX entry). On approval → move to collection/<type>/YYYY-MM-DD-<slug>.md. On rejection/discard → delete from inbox/.
Stage 1 — Collection (lightweight capture)
URL routing (host-based)
| Host | Method |
|---|---|
x.com, twitter.com | Jina: r.jina.ai/$URL with Authorization: Bearer $JINA_API_KEY, X-Return-Format: markdown |
github.com | WebFetch + targeted reads (ANGLE-DRIVEN — see below) |
arxiv.org | markdown.new |
| everything else | markdown.new; fallback to Jina if result is blank or < 200 chars |
GitHub repos: ASK FOR ANGLE FIRST
Before fetching anything from a GitHub repo, ask the user:
"What aspect should I profile? (architecture / specific pattern / failure modes / API surface / other)"
Do not fetch blindly. The angle drives which files to read.
Session logs
Parse JSONL from ~/.claude/projects/<encoded-path>/<session-id>.jsonl. Extract user/assistant turns relevant to the research focus; summarize into a session template.
File conventions
- Filename:
YYYY-MM-DD-<slug>.md— ISO date prefix, kebab-case, sortable. - Frontmatter: YAML per the template for the source type (see
templates/). - Tags: must come from
tags.md. Add new tags totags.mdin the same operation. - Index: always update
INDEX.mdafter writing a collection entry (runscripts/index.shor append row manually).
Stage 2 — Synthesis (HIGH EFFORT)
Trigger phrases: "synthesize", "we have enough research on X", "digest"
Process:
- Inventory: list every
collection/*markdown matching the topic (by tag or explicit filter). - Extract: pull
key_techniquesfrom frontmatter + body of each entry. - Group: cluster similar techniques into emergent themes.
- Write: for each theme, 200-400 word section. Every claim cites the collection entry by relative path.
- Surface contradictions and trade-offs across sources.
- Shortlist: end with "what's worth using" — 5-10 techniques ranked by relevance × maturity.
Team flow (mandatory):
Pre-impl reviewer (Opus) + critic (Opus) — parallel
↓
Sonnet writer
↓
Post-impl reviewer (Opus) + critic (Opus) — parallel
↓
Sonnet refinement pass
↓
(repeat up to 3× until both reviewers approve)
Output: $RESEARCH_WORKSPACE/synthesis/YYYY-MM-DD-<topic>-digest.md with full frontmatter (use templates/synthesis.md).
Every claim must cite a collection/<path>.md by relative path from workspace root.
Stage 3 — Analysis (HIGH EFFORT)
Trigger phrases: "analyze", "build options", "give me a recommendation"
Process:
- Restate constraints: from decisions log + current user ask.
- Distill 3-4 named options. For each:
- How it works
- Pros / cons
- Fit to constraints
- What we'd build
- Token budget estimate
- Risks
- Falsifiability test ("we'd know this is wrong if…")
- Explicit recommendation with rationale.
- Cross-reference to synthesis (preferred) or collection (allowed exception) by relative path.
- Phased rollout plan if recommendation is non-trivial.
Team flow: same full-team multi-pass as Stage 2.
Output: $RESEARCH_WORKSPACE/analysis/YYYY-MM-DD-<topic>-options.md with full frontmatter (use templates/analysis.md).
Decisions Log
After analysis review, when the user picks a direction, write a mini-ADR to $RESEARCH_WORKSPACE/decisions/YYYY-MM-DD-<topic>.md:
---
topic: <topic-slug>
status: accepted
date: YYYY-MM-DD
---
# Decision: <what we picked>
## Context
## Options considered
(link to analysis file)
## Choice
## Rationale
- bullet 1
- bullet 2
- bullet 3
## Consequences
## Supersedes
(links if any)
Change status: accepted → status: superseded when a later decision overrides this one.
Tag Canon
All tags must come from tags.md in this skill directory. Adding a new tag requires updating tags.md in the same operation (same file write, no separate step).
- Lowercase kebab-case only.
- 2-5 tags per entry.
Quality Notes
- No token-economy constraints in harness-research/ — quality over economy. Use Opus liberally for Stages 2 and 3.
- Never include harness-research/ in ryu-next-deploy-v1 or any deployable artifact.
- This skill is reusable: when bootstrapping a new research effort, copy
.claude/skills/research-harness/into the target project and pointRESEARCH_WORKSPACEat a fresh directory.