research

name	research
description	Research external tools/competitors for a topic and write findings to BRAINSTORM.md (project topics) or ~/.clade/research/ (personal topics). Use when user says "/research [topic]".

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Plugin skills are namespaced. Invoke this workflow explicitly as $clade:research; a bare $name does not select the installed Clade plugin.
• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $clade:skill-name plugin skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

Research external tools/competitors/approaches for a given topic and write a structured analysis to BRAINSTORM.md (project-scoped topics) or ~/.clade/research/ (personal topics — see Rules).

Capability Detection (run first)

Detect available research tools before starting:

Tier	Tools available	What you can do
Tier 0 — Training data only	No MCP tools, web search unavailable	Use knowledge cutoff (Aug 2025). Mark all results with ⚠ Training data only — verify current status.
Tier 1 — web search available	web search tool responds	Search with current year (2026) for up-to-date data. Max 5 searches.
Tier 2 — web search + web page fetch	Both tools available	Search for results, then fetch primary sources for depth.

Test by attempting a web search call. If it fails or returns no results → fall back to Tier 0 and note it prominently in the output.

Steps

0. FIRST: Determine if topic is personal or project-scoped (see Personal Topic Detection below)
   • If personal → skip step 1, go to step 5 (write to ~/.clade/research/ instead)
   • If project-scoped → proceed with steps 1-5 (write to BRAINSTORM.md)
1. Read VISION.md, TODO.md, and BRAINSTORM.md for project context (understand what already exists before researching)
2. Detect research tier (see above). Run web search with current year (2026) for 3-5 relevant tools/approaches. Max 5 searches.
3. For each result: extract key features, pricing/licensing, UX patterns, what they do well, what they do poorly
4. Compare against current VISION.md — what gaps does this research reveal? what patterns can we borrow?
5. Write findings:

## [Research] {date} — {topic}

### Tools surveyed
| Tool | Key features | What to borrow |
|---|---|---|
| ... | ... | ... |

### Gaps vs current VISION
- ...

### Recommended additions to TODO.md
- [ ] ...

Personal Topic Detection

Before starting research, check ALL of these:

Criterion	Personal	Project-Scoped
Ownership	User's own infrastructure, accounts, hardware, tools	Project's domain, codebase, user's work assignments
Scope	User's life decisions, personal setup, self-improvement	Product features, tech decisions, competitor analysis
Audience	Only the user cares	Project team cares, code review will see it
Reusability	Specific to user's context, not portable	Patterns generalizable to the project

Apply the "Stranger Clone Test": If someone cloned this repo, would they learn anything about the user's personal life, accounts, or infrastructure? If YES → PERSONAL. If NO → project-scoped.

Examples:

• ✅ PERSONAL: "what laptop to buy", "best personal finance apps", "home server setup", "password manager comparison for my accounts"
• ✅ PROJECT-SCOPED: "auth libraries for Node", "UI component libraries", "competitor analysis vs SalesForce", "LLM pricing tiers"

Rules

• Always read VISION.md first — generic suggestions are noise, project-specific insights are signal
• Always search with year 2026 for up-to-date information
• Be specific and actionable — "add OAuth2 login flow like tool X's 2-click setup" not "add authentication"
• Mark entries as [Research] (not [AI]) so they're distinguishable in BRAINSTORM.md
• Do NOT auto-process into GOALS.md or TODO.md — just write to BRAINSTORM.md inbox or personal research dir
• Personal-topic routing: If determined to be PERSONAL in step 0, write report to ~/.clade/research/{YYYY-MM-DD}-{slug}.md INSTEAD of BRAINSTORM.md — personal context must never land in a git-tracked project file

---

Completion Status

• ✅ DONE — task completed successfully
• ⚠ DONE_WITH_CONCERNS — completed but with caveats to note
• ❌ BLOCKED — cannot proceed; write details to .clade/blockers.md
• ❓ NEEDS_CONTEXT — missing information; use AskUserQuestion

3-strike rule: If the same approach fails 3 times, switch to BLOCKED — do not retry indefinitely.

Delivery completion

If this workflow changes files or external state:

• Inspect the real final state before responding, including git status for a repository task.
• Never report DONE while task-owned changes are uncommitted. Use or continue $clade:delivery and create a repository-compliant checkpoint or preserve the work when committing is unavailable.
• When the user request or trusted repository policy makes publication, deployment, or live verification part of the task, do not silently downgrade the result to local-only work.
• If a required delivery transition lacks authority, credentials, a destination, or reachable external state, report BLOCKED or NEEDS_CONTEXT rather than appending a "not committed/pushed/deployed" caveat after DONE.