research

research-skill

Persistent project-scoped store for deep research findings, with progressive disclosure and contrarian-pass investigation.

---

What this is

A Claude Code and Codex skill that gives you a persistent, project-scoped store for deep research findings.

Stop re-researching the same topics across sessions. Stop polluting conversation context with raw web search dumps. The skill maintains a structured local knowledge base under <project>/.research/, looks it up before fetching the web, and uses progressive disclosure to load only what's actually needed.

---

Built for compaction and large-research recall

Long Claude Code sessions run out of context. /compact summarizes older turns and drops the rest, so findings from a deep research thread evaporate and the next question re-triggers the same web searches.

This skill makes the data layer outlive the chat. Research written today survives /compact, /clear, IDE restarts, and machine moves. The next session reads INDEX.md first (a tiny dispatcher), matches the topic, and pulls only the matched entry's ## Summary section into context. The full body stays on disk until you actually need it.

Loading tiers, cheapest first:

Tier	Loads	Approx tokens	When
1	INDEX.md	100 to 500	Every retrieval
2	Entry's ## Summary only	50 to 200	When INDEX shows a match
3	Full FINDINGS.md body	500 to 3000	When the summary doesn't cover it

Heavy research artifacts become cheap to recall: you only pay for the tier you need.

---

What's distinctive

• Project-scoped, not global. Each repo has its own research store, kept private (gitignored by default).
• Progressive disclosure. Index, then summary, then full body, in that order. Most lookups never load the full entry.
• Conflict-handling history. When findings change, old claims move to a ## Discarded approaches table with reasons; never silently overwritten. Prevents re-trying refuted approaches.
• Subagent-isolated investigation. Heavy web research can run in a separate subagent: Opus 4.7 in Claude Code, or GPT-5.5 xhigh in Codex when subagents are explicitly authorized. Your main context stays clean.
• Async where supported. In Claude Code, the investigation subagent runs in background mode (run_in_background: true) so the conversation stays interactive while research happens. In Codex, the plugin investigates inline unless the user explicitly authorizes subagents.
• Cognitive phases. Decompose, Gather, Validate, Contrarian pass, Synthesize. The contrarian pass actively searches for "why this is wrong" rather than confirming. It earns its keep.

---

How findings reach your conversation

When a Claude Code Investigation subagent finishes, its full structured return (Summary, Findings, contrarian objection, sources) is injected into the main agent's context as a task-notification message. No file round-trip, no tail-the-log polling. The main agent parses the return directly and writes the data layer. In Codex, the same structured shape is used, either from an explicitly authorized subagent or from inline investigation.

Why this matters: