insane-research-main

Insane Research for Codex

Multi-phase research system — session state management, source verification, structured deliverables. AI autonomously performs multi-step research and verifies sources.

Read first:

• $PLUGIN_ROOT/skills/insane-research-main/references/phase_contracts.md
• $PLUGIN_ROOT/skills/insane-research-main/references/citation_rules.md
• $PLUGIN_ROOT/skills/insane-research-main/references/quality_rubric.md

Read when needed:

• $PLUGIN_ROOT/skills/insane-research-main/references/query_generator.md
• $PLUGIN_ROOT/skills/insane-research-main/references/tool_strategy.md
• $PLUGIN_ROOT/skills/insane-research-main/references/agent_prompts.md
• $PLUGIN_ROOT/skills/insane-research-main/references/query_schema.json
• $PLUGIN_ROOT/skills/insane-research-main/examples/*.json

Execute immediately when triggered

Do not just output this document, execute the research flow immediately. Extract the topic from the user input and proceed to the mode determination below.

Mode Determination (Argument Parsing)

Determine the action from the user input:

Input Pattern	Action
resume [session_id]	Resume previous research session
status	List all research sessions and progress
query	Interactive query builder → insane-research-query delegate to skill
[그 외 텍스트]	Start new research on the given topic
(no arguments)	Output the numbered menu in §A below and wait for a response

When there are no arguments — §A numbered menu

The Codex CLI does AskUserQuestion not have a multiple-choice card UI like have. shared/questioning-policy.md §Areplace it with a chat numbered block. Output the following to the chat and wait for the user's response:

무엇을 할까요?
1. 새 리서치 — 임의 주제로 딥리서치 시작 (주제 → 범위 → 멀티검색 → 종합 → 리포트, 10~30분)
2. 세션 재개 — 중단된 리서치를 마지막 체크포인트부터 이어서 (RESEARCH/*/state.json)
3. 세션 현황 — 모든 세션의 현재 페이즈/소스 수/갱신 시각 나열
4. 쿼리 빌더 — 모호한 주제를 구조화된 리서치 쿼리로 다듬기
(번호 또는 "X 주제로 새 리서치"처럼 문장으로 답해도 됩니다)

After the response:

• 1 New research → after confirming the topic, execute the 7-phase flow below
• 2 Resume session → RESEARCH/*/state.json present list → select → resume protocol
• 3 Session status → output a summary of progress for all sessions
• 4 Query builder → insane-research-query delegate to skill

Questioning principles (shared/questioning-policy.md §A·§1·§2c)

For narrowing the scope before research, do not ask what can be inferred (§1). If you must ask, present a default and get confirmation ("I'll assume a comprehensive report — let me know if otherwise"). If the request is already specific, proceed immediately without over-questioning (§2c); narrow the scope only when it is truly underspecified.

Language detection: match the language of all questions/options/deliverables to the user's input language (Korean input → Korean).

If the scope is truly ambiguous, ask only once via the §A numbered block, and only about the biggest unknown. Example:

이 리서치의 초점은 무엇이 가장 가까운가요?
1. 모두 포함 (추천) — 현재 상태/기술/시장을 종합 분석
2. 현재 상태와 트렌드 — 최신 동향, 시장 현황, 주요 플레이어
3. 기술 심층 분석 — 아키텍처, 구현, 기술 스택
4. 문장으로 직접 지정
(여러 개면 1,3처럼 적어주세요 / 모르면 1번으로 진행하겠습니다)

Deliverable form (comprehensive report / summary / modular)·audience (technical team / executives / researchers / general)·source preference (academic / industry reports / news / all) are also confirmed via the same numbered block only when truly ambiguous. If they can already be inferred, do not ask and proceed with the defaults (comprehensive report / all sources).

---

7-Phase Deep Research Process

Phase 1: Question Scoping

• Clarify the research question (principles §1·§2c above)
• Define the output format and success criteria
• Identify constraints and tone
• Generate an unambiguous query with clear parameters

Phase 2: Retrieval Planning

• Decompose the main question into 3–5 subtopics
• Generate specific search queries per subtopic
• Select suitable data sources
• Organize the research plan for user approval

---

DATE-AWARE query generation (required)

All search queries include current date context for freshness.

Before creating search queries, first check today's date in the system context.

1. Add the year to the query:
   • Bad: "AI code assistants market"
   • Good: "AI code assistants market 2026"
   • Good: "AI code assistants trends 2026"
2. Use recency operators: "after:2025", "since:2025", "2025..2026"
3. freshness keywords: "latest", "recent", "current", "new", "[current year] update"
4. Conversion examples:

   User query	Generated search query
   AI coding assistants	AI coding assistants 2026 latest trends
   startup trends	startup trends 2026 latest
   React vs Vue	React vs Vue 2026 comparison

5. Academic/historical research: Include the current year even in "state of" queries, use date ranges ("climate change research 2020-2026")

Query template: [topic] [현재연도] [freshness_keyword] [specific_aspect]

---

Phase 3: Iterative Querying

• Execute searches systematically (follow the Rate-Limit & Reliability Guard below)
• Extract and quote relevant information
  • On WebFetch/browsing failure → tool_strategy.mdtry the platform-specific access strategies of or the Fallback order
  • On successful bypass, add a via_fallback tag to the source reliability
  • Record the failed URL and bypass attempt results in sources/failed_urls.txtrecord in
• Derive new queries from findings, use multiple search modalities (web, academic, code)

Phase 4: Source Triangulation

• Compare findings across multiple sources
• Cross-verify key claims with at least 2 sources
• Handle discrepancies and record contradictions
• Evaluate source reliability with grades A–E

⚠️ Claim Verification Layer — required output contract

Before asserting key claims (figures, market share, dates, statutes, causation, etc. — claims where "being wrong is costly") in a smooth sentence, create claim ledger. The ledger **must be artifacts/claim_ledger.jsonlstored as 1 record per line (JSONL)** in — this file is the input to the validate_ledger.py gate in Phase 6. Record per key claim:

{
  "claim_id": "clm_001",
  "text": "주장 텍스트",
  "risk": "high | normal",
  "claim_type": "numeric | legal | causal | descriptive",
  "source_ids": ["src_001", "src_003"],
  "counter_search": "반증 검색 1회 결과 요약 (high-risk 필수)",
  "counter_refuted": false,
  "conflicting": false,
  "primary_source": true
}

status/confidenceis not written directly. validate_ledger.pycompares source_ids against the registry (sources/sources.jsonl) and, based on the number of independent domains, presence of counter_search, primary sources, and grade, reports computes the statusdoes. risk:"high"is assigned to numerical/market share/date/statute/causal/financial claims. source_ids는 sources/sources.jsonl의 idmust exactly match (a mismatch causes the gate to hard error).

Abstention enforcement rule (inviolable) — if any one of the following applies, the gate computes it as status=unresolved("undetermined"), and the claim is not allowed to be asserted in the body. Label it as "Unconfirmed / Needs verification" and Unresolved collect in the section:

• Fewer than 2 independent sources (domains)
• Conflicts between sources are not resolved (conflicting=true)
• Primary source unreachable (high-risk but primary_source=false)
• high-risk but no source of grade B or higher

Lightweight red-team (required) — for each high-risk claim, run 1 counter-search for disconfirmationand perform counter_searchrecord the summary in (if empty, the gate exits 1 as a process violation). If a credible rebuttal appears, counter_refuted=trueleave it as so the gate status=refutedcomputes it as and Refuted sends it to the section (no assertions in the body).

Primary source first — government/legal DB (law.go.kr·moleg), disclosures (SEC/IR), and peer review over secondary aggregators and blogs first try, and quality_rubric.md grade by the criteria and primary_source record whether it satisfies in the ledger.

→ This layer only for core claims applies. Keep the broad narrative, context, and readability of the body, but only core figures/claims pass through the ledger gate.

Phase 5: Knowledge Synthesis

• Structure the content logically
• Write the synthesis section
• Include inline citations for all claims
• Add data visualizations when relevant

⚠️ Verified-only synthesis gate (inviolable — data flow lock)

Before entering Phase 5, validate_ledger.pyrun outputs/verified_claims.jsonmust first be generated(the command under Phase 6 "Closing the verification layer" below). Then:

• Core claims (high-risk such as figures, statutes, causation, finance) are written in assertive form in the body only for items in outputs/verified_claims.jsonin raw search results (sources.jsonl·search findings) directly and do not assert core figures.
• outputs/unresolved_claims.json·outputs/refuted_claims.jsonclaims in no assertions in the body — Unresolved/Refuted expose only in the annex section.
• Write broad narrative, context, and readability sentences freely as they are, but the verification gate only for core claims applies.

Reason: only the checker produces verified_claims.json. If you skip the checker, the input to synthesize is empty and self-destructive, so verification cannot be bypassed (enforced not by pure prompt advice but by data dependency).

Phase 6: Quality Assurance

• Check for hallucinations and errors
• Verify that all citations match the content
• Ensure completeness and clarity
• Apply Chain-of-Verification

Closing the core claim verification layer (required — deterministic gate)

Verification is not a "recommendation" but a code gate. artifacts/claim_ledger.jsonl과 sources/sources.jsonlOnce this is ready, you must run the following (run it first before Phase 5 synthesis to create verified_claims.json, then rerun it just before Phase 7 to confirm it passes):

python3 "$PLUGIN_ROOT/skills/insane-research-main/scripts/validate_ledger.py" --session "RESEARCH/{topic}_{timestamp}"

Depending on the exit code:

• exit 2 (hard error) — broken schema, unregistered source id, A-E grade contradiction. Fix the data and rerun. Never proceed to Phase 7.
• exit 1 (process violation) — for high-risk claims, counter_search is missing. Perform one counter-evidence search for the relevant claim, update the ledger, and rerun.
• exit 0 (pass) — outputs/{verified,unresolved,refuted}_claims.json generated, state.json.verification.signature recorded. Phase 7 can now proceed.

Final check:

• state.json에 verification.signatureis present and verification.passed=truewhether verify (if absent, the gate did not run = incomplete).
• In the report, Confidence / Refuted / Unresolved expose the 3 sections.
• unresolved/refuted Finally check that claims are not mixed into the body in assertive form (whether the verified-only synthesis gate was violated).

Strict mode (opt-in — high-risk claim re-verification)

The default mode is fast and broad — a core claim ledger + deterministic gate is sufficient. However, topics where being wrong is costly (law, medicine, finance, regulation, key figures) or when the user strictspecifies, select only the ledger's unresolved or high-risk claims and perform adversarial re-verification:

1. From the Phase 4 ledger, extract claims that the gate computed as unresolvedor that are high-risk (strong figures, statutes, causation).
2. Turn each claim into a verifiable question and confirm/refute it via independent search (using primary sources when possible). Since Codex has no separate Workflow harness, perform the additional searches directly in the main thread.
3. Merge the results into the ledger (source_ids·counter_search·counter_refuted·primary_source update), then validate_ledger.pyrerunto recompute status: confirmed → promote to verified, refuted → Refuted, still inconclusive → keep as Unresolved.
4. The default mode skips this step (fast). Only strict mode attaches auditable re-verification.

→ Combine breadth (default search) + precision (strict re-verification), but not the whole thing, only high-risk/unresolved claims to control cost. Assertions/synthesis are always based only on the verified_claims.jsonproduced by the gate.

Phase 7: Output & Packaging

• readability-optimized format
• include executive summary
• generate a formal bibliography
• export in the requested format
• (optional) generate an interactive website

Final self-verification (required — measured)

After finishing the report, run the evaluation grader to verify numerically whether the body actually honored the verification contract check with numbers:

python3 "$PLUGIN_ROOT/skills/insane-research-main/scripts/eval_report.py" --session "RESEARCH/{topic}_{timestamp}"

• verdict: FAIL(unverified/refuted claims leaked into the body or citations not in the registry), fix and rerun — do not finalize in that state.
• Metrics (leak_rate·citation_resolution_rate·orphan_source_rate·verified_coverage_rate)는 outputs/eval_report.jsonare stored. Used for gate on/off A/B testing and regression tracking.

---

Multi-source research strategy

Split subtopics, source types, and cross-validation to increase coverage. In Codex, the following principles apply:

Role	Focus	Output
Web research	Current information, trends, news	Structured summary including source URLs
Academic/technical	Papers, specs, methodologies	Technical analysis including citations
Cross-validation	Fact-checking, verification	Confidence rating of key findings

The default is main-thread sequential execution. Only use Codex subagents when the user explicitly requests parallel/team research, and keep each delegated subtopic narrowly scoped. Agent prompt templates and Graph of Thoughts integration: $PLUGIN_ROOT/skills/insane-research-main/references/agent_prompts.md

⚠️ Rate-Limit & Reliability Guard (Required)

1. Concurrent fan-out throttle — Running many agents (or many parallel verification calls) at once hits the subscription plan's server-side rate-limit and causes mass failures. Even when using parallelism, run in sequential batches of at most 2–3 at a timeand launch the next batch after one batch completes. Steps with many calls, such as cross-validation and fact-checking, should especially be processed sequentially.
2. Avoid background silent death — Agents launched in the background can die without notification due to rate-limits or session load, producing no output. After using the background, confirm survival via deliverables/transcripts, and if they died or it is uncertain, switch to the fallback of searching directly and sequentially in the main thread. If stability matters, prioritize foreground/main-thread sequential from the start.

---

Tool usage

Perform research with the default tools (web search, browsing, curl/gh and other shell tools). For platform-specific optimal approaches, refer to tool_strategy.md. If MCP tools (Perplexity, Firecrawl, Exa, browser, etc.) are installed in the environment, use them preferentially, but the default tools alone are sufficient even without them.

큰 run_in_background Avoid fan-out — because it hits rate-limits and background agents can die silently, prioritize foreground/main-thread sequential when reliability matters. Detailed strategy and examples: $PLUGIN_ROOT/skills/insane-research-main/references/tool_strategy.md

---

Citation requirements

All factual claims include inline citations.

Required standard

1. Author/Organization — who claimed it
2. Date — publication date
3. Source Title — paper/article/report name
4. URL/DOI — direct link for verification
5. Page Numbers — for long documents (if applicable)

Source quality rating

Rating	Description	Example
A	Peer-reviewed, systematic review, meta-analysis	Nature, Lancet, IEEE
B	Official documentation, clinical guidelines, cohort studies	FDA, W3C, WHO
C	Expert opinion, case reports, industry reports	Gartner, conferences
D	Preliminary research, preprints, white papers	arXiv, company blogs
E	Anecdotal, theoretical, speculative	Social media, forums

Red Flags (unreliable sources)

Unknown author / missing publication date / broken or suspicious URL / claims without data / undisclosed conflicts of interest / predatory journals / retracted papers.

Detailed citation rules: $PLUGIN_ROOT/skills/insane-research-main/references/citation_rules.md Source quality rubric: $PLUGIN_ROOT/skills/insane-research-main/references/quality_rubric.md

---

Hallucination prevention

1. Ground every statement in sources — Do not assert without a verifiable source. If uncertain, say "Source needed" instead of guessing.
2. Chain-of-Verification for key claims — Generate verification questions → independent search → confirm only after verification.
3. Cross-reference multiple sources — Key findings require 2 or more independent sources. If sources conflict, state it explicitly.
4. State uncertainty — Instead of "Studies show...", use "According to [source]...". Qualify preliminary/contested findings.

Verification checklist

• Inline citations for every claim
• All URLs accessible
• No orphan citations
• State contradictions
• Apply source quality ratings

---

State management

state.json schema

{
  "session_id": "Topic_Name_20260224_143000",
  "topic": "Research Topic",
  "created_at": "2026-02-24T14:30:00Z",
  "updated_at": "2026-02-24T15:45:00Z",
  "status": "PHASE_3_QUERYING",
  "current_phase": 3,
  "requirements": {
    "focus": ["aspect1", "aspect2"],
    "output_format": "comprehensive_report",
    "scope": {"timeframe": {}, "geography": {}},
    "sources": {"required_types": [], "min_quality": "B"},
    "audience": "executive",
    "special_requirements": []
  },
  "plan": {"subtopics": [], "search_queries": {}, "agent_assignments": []},
  "progress": {
    "phase_1": "completed", "phase_2": "completed", "phase_3": "in_progress",
    "phase_4": "pending", "phase_5": "pending", "phase_6": "pending", "phase_7": "pending"
  },
  "sources_count": 0,
  "artifacts": {},
  "errors": []
}

sources.jsonl schema (one JSON per line)

{"id": "src_001", "url": "https://...", "title": "Article Title", "author": "Author", "date": "2024-06-15", "domain": "nature.com", "type": "academic", "quality_rating": "A", "snippet": "relevant excerpt...", "claims": ["claim1"], "verified": true}

Phase input/output contract: $PLUGIN_ROOT/skills/insane-research-main/references/phase_contracts.md

---

Output structure

RESEARCH/{topic}_{timestamp}/
├── state.json                    # 세션 상태 (재개 가능)
├── README.md                     # 네비게이션 가이드
├── artifacts/                    # 중간 산출물
│   ├── research_plan.json
│   ├── agent_results/
│   └── drafts/
├── sources/
│   ├── sources.jsonl            # 수집 소스 전체
│   ├── bibliography.md          # 정리된 인용
│   └── quality_report.md        # 소스 품질 등급
├── outputs/                     # 최종 산출물
│   ├── 00_executive_summary.md
│   ├── 01_full_report/
│   │   ├── 01_introduction.md
│   │   ├── 02_current_landscape.md
│   │   ├── 03_challenges.md
│   │   ├── 04_future_outlook.md
│   │   └── 05_conclusions.md
│   ├── 02_appendices/
│   └── comparison_data.json
└── website/                     # (선택) 비주얼 프레젠테이션
    ├── index.html
    ├── styles.css
    └── script.js

Output templates

For consistent formatting, $PLUGIN_ROOT/skills/insane-research-main/assets/templates/use the templates in:

Template	Purpose
executive_summary.md	Summary structure
full_report_section.md	Individual report section template
bibliography.md	Bibliography including quality distribution
readme_research.md	Research session README/navigation
website_template.html	Interactive web presentation

---

Dynamic generation of skeleton based on Research Type (for reference — keep the default 5 sections)

The default 5-section skeleton (introduction/landscape/challenges/future_outlook/conclusions) is the default for all research. Only when the user explicitly requests a different type, look at the reference example patternsbelow and dynamically generate on the flya skeleton tailored to the user's research.

Note: The default 7-Phase + 5-section + Date-aware are all preserved as the core contract of insane-research. The per-type skeleton is an advanced option applied only upon explicit user request , and the table is not a menu but examples for learning dynamic generation다.

Reference examples (not a menu — for pattern learning)

Research Type	5-section pattern examples	Suitable cases
Exploratory (exploring a new area)	introduction / landscape / opportunities / challenges / conclusions	Exploring a new market/technology
Comparative (A vs B comparison)	introduction / criteria / comparison_matrix / recommendation / conclusions	Tool/product comparison
Predictive (future scenarios)	introduction / current_state / trends / scenarios / risks_and_recommendations	Market forecasting / technology roadmaps
Analytical (cause-effect)	introduction / problem / causes / effects / conclusions	Incident analysis / causal tracing
Generic	introduction / current_landscape / challenges / future_outlook / conclusions	Comprehensive research (default)

Application procedure

1. In Phase 1, infer the research type from the user's natural language (closest pattern)
2. After learning example patterns, Dynamically generate 5 section names tailored to the user's topic (do not copy section names verbatim)
3. Confirm with the user (§A numbered block): "This research seems close to the [Comparative] pattern — shall we go with 5 sections as [introduction / X comparison criteria / X vs Y comparison / recommendation / conclusion], or with the default 5 sections?"
4. confirm → use dynamic skeleton / unspecified or ambiguous → default 5 sections (safe default)
5. state.json report_skeleton Record the final skeleton in the field (resumable)

⚠️ Caution

• Do not auto-decide the type — user confirmation is required
• The table is not a catalog but a pattern example collection — do not add new type cases to the table
• All contracts such as 7-Phase / minimum 2 sources / A-E quality / Hallucination Prevention remain unchanged

---

Structured query support

For precise control, accept structured JSON queries following this schema: $PLUGIN_ROOT/skills/insane-research-main/references/query_schema.json

If the user provides a JSON object as input, parse it according to the schema and skip Phase 1 (Question Scoping) (requirements are already defined). Example query: $PLUGIN_ROOT/skills/insane-research-main/examples/

---

Resume protocol

On resume trigger:

1. List available sessions: RESEARCH/*/state.json
2. Load the selected session's state.json load
3. progress Check the last completed phase in the object
4. Resume from the next pending phase
5. Continue the execution loop

for phase_num in range(1, 8):
    phase_key = f"phase_{phase_num}"
    if state["progress"][phase_key] == "in_progress":
        resume_phase(phase_num); break
    elif state["progress"][phase_key] == "pending":
        start_phase(phase_num); break

---

Error handling

Phase failure

1. state.json Log the error in the errors array
2. Mark the phase in progress as failed(status)
3. Notify the user in detail
4. Propose: Retry / Skip / Abort

Network failure

• Retry up to 3 times with backoff
• If it still fails → tool_strategy.mdSee the "Fallback strategy when inaccessible" (mobile UA curl → OGP meta tags → Google cache/Wayback → curl_cffi → browser)
• Determine success/failure by response validation rules (detect login pages, CAPTCHA, empty SPA)
• Log the failed URL + fallback result to sources/failed_urls.txtlog
• Continue with available sources (including content recovered via fallback)

Token limit

• Split long documents into chunks / save intermediate results frequently / summarize very long sources

---

Pre-completion quality checklist

• Every claim has a verifiable source
• Key findings are supported by multiple sources
• Contradictions are stated and explained
• Sources are recent and authoritative
• No hallucinations or unsupported claims
• Clear logical flow from evidence to conclusion
• Formal citation format throughout
• Executive summary reflects the entire content
• Bibliography complete
• All background tasks completed and results collected

---

Scripts and utilities

Script: $PLUGIN_ROOT/skills/insane-research-main/scripts/

Script	Purpose	Authority
validate_ledger.py	Validation gate (required). Read claim_ledger + sources to deterministically compute status, verified_claims.json produce, state.jsonrecord signature in	authoritative — Phase 5/7 entry gate
eval_report.py	Evaluation grader (required). Measure whether the body adhered to the validation contract — 4 metrics: leak/citation-resolution/orphan/coverage, eval_report.json produce	authoritative — Phase 7 closing self-validation
orchestrator.py	Session folder/state.json creation, source append, etc. state helper. Internal phase transition logic has no authority (the SKILL.md flow is the orchestration)	helper (static asset)
pipelines.py	Agent prompt templates, clarification, synthesis prompts static assets	helper (static asset)

Orchestration is handled by the prompt (this SKILL.md), and validation by the code (validate_ledger.py). orchestrator.py/pipelines.pyThe state-machine and plan stubs are reference helpers only and have no execution authority, so validation/synthesis gates must be enforced with validate_ledger.py.

---

References

Reference	Location
Citation format rules	$PLUGIN_ROOT/skills/insane-research-main/references/citation_rules.md
Phase input/output contract	$PLUGIN_ROOT/skills/insane-research-main/references/phase_contracts.md
Source quality rubric	$PLUGIN_ROOT/skills/insane-research-main/references/quality_rubric.md
Agent prompt templates & GoT	$PLUGIN_ROOT/skills/insane-research-main/references/agent_prompts.md
Tool strategy & code examples	$PLUGIN_ROOT/skills/insane-research-main/references/tool_strategy.md
Structured query schema	$PLUGIN_ROOT/skills/insane-research-main/references/query_schema.json
Query generation guide	$PLUGIN_ROOT/skills/insane-research-main/references/query_generator.md